Create a new video

The content for your video. How this field is used depends on inputType.

Script mode (inputType: "script", default): Provide the exact narration text. This is what the voice will speak word-for-word. Must be at least 5 words. Max 30,000 characters (enough for a 20-minute video at normal voice speed). The AI automatically splits it into visual segments and generates matching visuals.

Visual control: By default, the AI decides what visuals to show for each part of your narration. For more control, add visual instructions in brackets before each narration segment:

[A dark forest at night] The wind howled through the trees. [Glowing eyes peering from shadows] Something was watching.

Each [bracketed text] tells the AI exactly what to show for that scene. The text after it is the voiceover.

Put a real person, product, or place in the video (@mentions): reference a saved element by its handle, e.g. [@Maya holding @Red-Bottle] Meet the founder who started it all. The element's reference photo is fed to the image model so the same face or product appears consistently across the whole video. Get handles from GET /elements; create new elements with POST /elements. Rules: works with mediaType images and video; not with stock. The photo decides how the element looks; never describe its appearance in the script. Mentions are spoken as the plain name (the @ is never read aloud), and unknown handles are treated as plain words.

Idea mode (inputType: "idea"): Provide a short topic or concept. The AI writes a full narration script for you. Keep it under 800 characters. Pair with expectedDurationSeconds to control video length.

Source mode (inputType: "source"): Provide the TEXT of an article, a web page, or a document. It is not the narration. The AI reads it and writes a short narration script from it, faithful to it. Max 200,000 characters. Pair with expectedDurationSeconds (required) to set the script length, and with the source object to say where the text came from.

You can skip this field in source mode by sending source.url (a web page) or source.assetId (a PDF you uploaded) instead. We then fetch and read the page or the file while the video is being made, so you do not have to read it yourself.

Supports any language. The voice will speak naturally in whatever language the text is written in.

How to interpret the script field.

• script (default): Your text is the exact narration. You control every word that is spoken.
• idea: You provide a topic and the AI writes an engaging narration script for you. Use expectedDurationSeconds to control the target length.
• source: Here is the text of an article or a document. Write a short video script from it. The AI keeps to that text and invents nothing. expectedDurationSeconds is required, because it sets how long the script is. Send source.url or source.assetId to have us read the page or the PDF for you, or send the text yourself in script.

For background mode: an id from GET /background-videos. One clip repeats under the full narration; source audio is muted.

The type of visuals for your video. Each produces a different look and feel.

• images (default): AI generates a unique image for each segment, displayed with smooth Ken Burns pan/zoom animation. This is the classic "faceless narration video" style used by top YouTube channels. Most popular and cheapest option. Control the look with imageQuality and imageStyleId.
• video: AI generates short video clips for each segment. More dynamic and cinematic than images, but costs more credits. Also used internally by the skeleton and character templates.
• stock: Automatically finds and matches real stock footage to each segment. Great for news, educational, and documentary-style content.
• avatar: A talking-head video where an avatar speaks your script. Requires avatarId (from GET /avatars) and voiceId. Script mode only (no idea mode), max 5 minutes, aspect ratio 9:16 or 16:9. Costs ~480 credits per minute of video plus narration, far more than other media types. Generation also takes longer (usually 3-10 minutes).

For most use cases, leave this as default (images) unless you are using a template. When using templateId, the template automatically selects the best media type for you, so you do not need to set mediaType separately.

Required when mediaType is "avatar". The avatar that speaks your script. Get valid IDs from GET /avatars (built-in avatars plus characters created in the dashboard). Ignored for other media types.

Optional direction for how the avatar moves and gestures, e.g. "excited, talking with hands, leaning toward the camera". Only applies when mediaType is "avatar".

The voice ID for narration. Browse all 1,300+ available voices and listen to previews at GET /voices, or use one of your cloned voices from GET /voices/cloned.

If omitted, defaults to "Adam", a deep, natural American male voice. Exception: required when mediaType is "avatar" (no default; pick a voice that fits the avatar, or use its defaultVoiceId from GET /avatars).

Filter voices by gender, accent, or use case using the GET /voices endpoint query parameters. Use the previewUrl from each voice to hear a sample before selecting.

Narration speed multiplier. Range: 0.7 to 1.2.

• 0.7: 30% slower. Great for educational, meditation, or non-native audiences.
• 1.0 (default): Natural speed.
• 1.2: 20% faster. Great for energetic, hype, or fast-paced content.

Most creators use values between 0.9 and 1.1.

Video dimensions. Choose based on where you plan to publish.

• 9:16 (default): Vertical/portrait. Best for YouTube Shorts, TikTok, and Instagram Reels.
• 16:9: Horizontal/landscape. Best for standard YouTube videos and presentations.
• 1:1: Square. Best for Instagram feed posts and LinkedIn. Not available for mediaType: "avatar".

Target video duration in seconds. Required when inputType is "idea" so the AI knows how long a script to write.

Examples: 30 for a 30-second Short, 60 for a 1-minute video, 180 for a 3-minute video, 600 for a 10-minute video, 1200 for a 20-minute video.

Max varies by template:

• Default faceless template (no templateId): 1200 seconds (20 minutes)
• templateId: "skeleton" or templateId: "character": 420 seconds (7 minutes) (these templates have different cost profiles and are not designed for long-form content)
• templateId: "rebuild": 60 seconds (1 minute)

Also required when inputType is "source", in both source modes. With source.mode: "summarize" it is the TARGET: the AI writes a script about that long. With source.mode: "read-out" it is the CEILING: the text is read word for word, and anything past that length is cut at a sentence end.

Passing a value above the template-specific cap returns a 400 error. Ignored when inputType is "script" because the duration is determined by the word count.

Image generation quality tier. Only applies when mediaType is "images". Higher quality produces more detailed, accurate images but costs more credits per image.

• basic (default): 1 credit/image. Fast generation. Good for testing and drafts.
• good: 5 credits/image. Better detail and accuracy. Good for most published content.
• premium: 10 credits/image. High detail, very accurate to the script. Great for professional content.
• max: 20 credits/image. Maximum quality. Best for high-production content.

A typical 60-second video has 15-18 images (one every 3-5 seconds), so factor that into credit calculations.

Every tier can use the reference photo of an @mentioned saved element. Each photo used in a scene adds 3 credits to that scene, on top of the tier price above.

Visual art style for AI-generated images. Only applies when mediaType is "images". Each style applies a consistent aesthetic across all images in your video.

Realistic:

• photorealistic (default): Hyperrealistic photography, DSLR quality.
• cinematic: 35mm film look, dramatic lighting, movie still aesthetic.
• vintage-retro: 1980s VHS aesthetic, neon colors, synthwave vibes.
• noir: Classic black and white film noir, dramatic shadows.

Illustrated:

• 3d-pixar: 3D Pixar-style cartoon, smooth rounded shapes.
• anime: Japanese anime/manga style, cel-shaded, vibrant colors.
• digital-art: Professional concept art, Artstation quality.
• comic-book: American comic book, bold outlines, halftone shading.

Artistic:

• pencil-sketch: Detailed graphite pencil drawing on textured paper.
• oil-painting: Classical oil painting with visible brushstrokes.
• watercolor: Soft watercolor with translucent color washes.
• pop-art: Andy Warhol style, bold primary colors.

Modern:

• kurzgesagt: Flat vector educational style (like the YouTube channel).
• pixel-art: Retro 16-bit video game aesthetic.
• minimalist: Clean, simple, lots of white space.
• claymation: Stop-motion clay animation, Aardman-inspired.

And 11 more styles. Combine with imageStyleCustom for fine-tuning.

Caption (subtitle) visual style. Captions are rendered directly onto the video with word-by-word timing sync.

Built-in styles:

• cinematic (default): Clean white text with one key word per phrase in a glowing italic serif.
• wrap-1: Active word highlight with 2-word groups.
• koe: Small lowercase serif, one quiet phrase at a time. No word highlight.
• pill: Black text on a white rounded box, one short phrase at a time.
• hormozi: Bold uppercase with yellow highlight on black pill. Alex Hormozi inspired.
• beast: Bold Bangers font with letter-spacing bounce animation. MrBeast inspired.
• noah: Bold italic Oswald with colored highlight.
• handwritten: Organic casual style with handwriting font. Personal and authentic.
• subtitle: Clean streaming-style subtitles on a dark bar. Professional and readable.
• impact: Massive bold text, one word at a time. Maximum emphasis.
• pop: Playful spring animation with bouncy words. Fun and energetic.
• chronicle: Ancient serif for history, mythology, and epic stories.
• cyber: Futuristic neon style for sci-fi, tech, and cyberpunk content.
• grit: Raw marker style for true crime, street, and intense stories.
• luxe: Elegant serif for luxury, fashion, and celebrity content.
• terminal: Monospace style for tech, hacker, and AI content.

You can also create custom caption styles with your own fonts, colors, and animations via the AITuber dashboard. Use the custom style ID here.

Whether to show captions (subtitles) on the video. Default: true.

Captions are auto-synced word-by-word to the narration. We strongly recommend keeping captions on as they significantly boost engagement, accessibility, and watch time. Set to false only for music-only or ambient videos.

Vertical position of captions on the video.

• bottom (default): Captions at the bottom of the screen.
• center: Captions in the middle of the screen.
• top: Captions at the top of the screen.

Not supported for mediaType: "avatar" (avatar captions always use the default position).

Video clip generation quality. Only applies when mediaType is "video".

• basic: Fastest generation, lower visual quality.
• good (default): Good balance of quality and speed.
• premium: High quality video clips. Slower generation.
• max: 1080p clips, the sharpest we make. Costs the most per second.

Specialized video template that applies a specific visual format and style. Leave empty for standard faceless narration videos (the default).

Available templates:

• skeleton: "What happens if..." style educational videos with skeleton/X-ray visuals. Uses AI video generation internally. Popular viral format on YouTube Shorts. Example script: "What happens if you eat only ice cream for 30 days".
• medical: Medical animation videos with scientifically accurate anatomy, for health education, patient explainers, and clinic content. Works with mediaType images (default) or video only (no stock: stock libraries carry no anatomy footage). Optional curated styles via imageStyleId: medical-3d (realistic 3D), medical-translucent (see-through body), medical-xray, medical-darkstudio (organ on black), medical-cartoon (patient-friendly), or omit for auto. Example idea: "How a total knee replacement works, step by step".
• character: Character-driven animated videos. AI generates a consistent character across all scenes and animates them. Uses AI video generation internally. Example script: "A robot learns what friendship means on its first day at school".
• rebuild: AI Construction Timelapse. One place changing from messy or empty to finished, in a single locked shot: the camera never moves, so the viewer compares the same frame from the first second to the last. No voiceover and no captions. You hear the sounds of the work, and background music is added over the whole video. The last few seconds always show the finished place in use rather than standing empty. Duration 15-60 seconds. Works from a prompt alone, from beforeImageUrl and afterImageUrl, or from any mix. The prompt must describe a PHYSICAL PLACE that changes; a lecture, a joke, or a product review is rejected. Example idea: "A dirty canal becomes a park with paths and lights".

Important: When you set a template, it handles the visual settings for you; just provide your script (or inputType: "idea" with a topic). skeleton, character, and rebuild also pin mediaType automatically. medical keeps mediaType open: send images (default) or video; sending stock returns a 400.

For talking-head avatar videos, do NOT use a template: set mediaType: "avatar" with an avatarId instead.

Public HTTPS image URL used as the FIRST FRAME for templateId: "rebuild". The video starts on this picture and the camera stays at its angle throughout. The place does not have to exist: a photo, a drawing, or a render all work. Uploaded pictures are free and replace a still we would have generated, so they lower the credit cost. Optional. Ignored on other templates.

Public HTTPS image URL used as the LAST FRAME for templateId: "rebuild". The video ends on this picture, at the same camera angle as the rest. Often a render or a drawing of the finished build rather than a photograph, which is fine. Uploaded pictures are free and replace a still we would have generated. Optional. Ignored on other templates.

Unique video identifier. Use this to poll GET /videos/{id} for generation status.

Initial status. Will be pending or processing.