Sign in
latestOpenAPI 3.1.12026-08-22330162.7 KB

35448566f143

Videos

Create a new video

Starts generating a new AI video from a script or idea. The video is created in the background and typically takes 1-3 minutes depending on length and media type.

Two ways to create a video:

1. From a script (you write the narration):

{
  "script": "The human brain is the most complex organ in the body. It contains roughly 86 billion neurons, each connected to thousands of others. Every thought, memory, and emotion is the result of electrical signals racing through this incredible network.",
  "voiceId": "nPczCjzI2devNBz1zQrb",
  "imageStyleId": "cinematic"
}

2. From an idea (AI writes the script for you):

{
  "script": "5 mind-blowing facts about black holes",
  "inputType": "idea",
  "expectedDurationSeconds": 60
}

Workflow after calling this endpoint:

  1. You receive a videoId with status: "pending".
  2. Poll GET /videos/{videoId} every 5-10 seconds.
  3. When status changes to completed, the video is ready.
  4. Call POST /exports to render the MP4, then GET /exports/download to get the file.

Credit cost: Depends on media type, duration, and quality tier. A typical 60-second video with basic quality costs about 50 credits. Check your balance with GET /subscription before generating.

post/videos/generate

Request body

scriptstring required

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. [@Dhiva 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.

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

inputType'script' | 'idea'

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.
mediaType'images' | 'video' | 'stock' | 'avatar'

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 ~840 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.

avatarIdstring uuid

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.

motionPromptstring

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".

voiceIdstring

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.

voiceSpeednumber

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.

aspectRatio'9:16' | '16:9' | '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".
expectedDurationSecondsnumber

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)

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.

imageQuality'basic' | 'good' | 'premium' | 'max'

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.

imageStyleIdstring

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.

captionStyleIdstring

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

Built-in styles:

  • wrap-1 (default): Active word highlight with 2-word groups. Most popular style.
  • 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.

captionsEnabledboolean

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.

captionPositionstring

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).

videoQualitystring

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: Highest quality video clips. Slower generation.
templateIdstring

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".
  • 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".

Important: When you set a template, it automatically handles mediaType and visual settings for you. You do not need to set mediaType, imageQuality, or imageStyleId separately. Just provide your script (or inputType: "idea" with a topic) and the template takes care of the rest.

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

Response

OK

videoIdstring uuid required

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

status'pending' | 'processing' required

Initial status. Will be pending or processing.