---
title: "Create a new video"
method: POST
path: "/videos/generate"
tags: ["Videos"]
---

# Create a new video

`POST /videos/generate`

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):
```json
{
  "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):
```json
{
  "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.

## Request body

- object
  - `script` string, 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.
  - `avatarId` string, 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.
  - `motionPrompt` string — 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"`.
  - `voiceId` string — 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.
  - `voiceSpeed` number — 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"`.
  - `expectedDurationSeconds` number — 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.
  - `imageStyleId` string — 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.
  - `captionStyleId` string — 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](https://app.aituber.app/dashboard). Use the custom style ID here.
  - `captionsEnabled` boolean — 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.
  - `captionPosition` string — 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).
  - `videoQuality` string — 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.
  - `templateId` string — 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 `200`

OK

- object
  - `videoId` string, 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`.

## Other responses

- `401` — 401
- `402` — 402
- `403` — 403

---

[API](https://skmtc.net/aituber/apis/aituber-api.md) · [All operations](https://skmtc.net/aituber/apis/aituber-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aituber/aituber-api/revisions/35448566f143/schema)