# Create AI Story video

URL: https://clippie.ai/developers/docs/create-ai-story-video

Makes a narrated AI Story video (script, voiceover, scene images, captions, music) and renders it to MP4. Give one of prompt (a script is written to fill durationSeconds, 30-300, default 60), script, or voiceoverFileId. Spends minutes, not credits: about 1 voiceover, 1 caption and 1 export minute per minute of video (render: false skips the export minutes and returns an editable project). Run estimate_cost (or dryRun: true) first and confirm the cost. Takes a few minutes: wait with get_job (waitSeconds). At most 3 videos are made at once per account. The result has videoUrl and editorUrl.

## At a glance

| Property | Value |
| --- | --- |
| REST | `POST https://api.clippie.ai/v1/videos/ai-story` |
| MCP tool | `create_ai_story_video` |
| Scope | `create` |
| Cost | Spends credits or minutes, at the same prices as the app. Send `"dryRun": true` (or call [estimate_cost](https://clippie.ai/developers/docs/estimate-cost.md)) first to see the exact cost without spending anything. |
| Limit bucket | `render` (see [Rate limits](https://clippie.ai/developers/docs.md#rate-limits)) |

## Parameters

| Name | In | Type | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | body | string | No |  | What the video is about; a script is written from it to fill durationSeconds. Give one of prompt, script or voiceoverFileId. 3-2000 chars. |
| `script` | body | string | No |  | The exact narration to use (it sets the length; durationSeconds is ignored). 20-12000 chars. |
| `voiceoverFileId` | body | string | No |  | file_… id of your own narration audio (upload it with upload_file). It is transcribed for captions; no voice is generated. Up to 5 minutes. Up to 80 chars. |
| `title` | body | string | No |  | Project and file name. Defaults to the start of the prompt or script. 1-120 chars. |
| `storyTemplateId` | body | string | No |  | A format from list_story_templates: sets the look and the aspect ratio in one go. artStyleId, imageModel and aspectRatio override it. Up to 64 chars. |
| `voiceId` | body | string | No |  | Narration voice id from list_voices (catalog voices or your own cloned ones). Defaults to your brand voice. 1-64 chars. |
| `artStyleId` | body | string | No |  | A look from list_art_styles: a type "style" id, or a type "stylePrompt" id (rendered with imageModel, default seedream-5.0-lite). Up to 64 chars. |
| `imageModel` | body | string | No |  | Draw the scene images with this model (from list_art_styles imageModels) instead of a named style. Included with paid plans. One of `nano-banana`, `nano-banana-2.1`, `nano-banana-pro`, `seedream-5.0-lite`, `flux-2-pro`. |
| `stylePromptId` | body | string | No |  | Style preset (a type "stylePrompt" id) for imageModel. Up to 64 chars. |
| `aspectRatio` | body | string | No |  | Frame shape. Defaults to the story template, then your brand. One of `9:16`, `16:9`. |
| `durationSeconds` | body | integer | No |  | Length of the whole video in seconds (30-300, default 60) when the script is written from prompt. The script is sized to the voice's measured speaking speed. 30-300. |
| `language` | body | string | No |  | Narration and caption language code from list_languages (e.g. "en", "es", "ja"). Default: detected. Up to 10 chars. |
| `captionStyleId` | body | integer | No |  | Caption style id from list_caption_styles. Defaults to your brand caption style. 1-17. |
| `musicId` | body | string | No |  | Background music id from list_music, or "none" for no music. Defaults to your brand track. Up to 64 chars. |
| `theme` | body | string | No |  | Subject direction for a script written from prompt. One of `any`, `historical`, `scientific`, `geography`, `politics`, `nature`, `religion`, `technology`, `psychology`, `mystery`, `space`, `mythology`, `war`. |
| `tone` | body | string | No |  | Voice and pacing for a script written from prompt. One of `cinematic`, `suspenseful`, `educational`, `dark`, `inspirational`, `humorous`, `dramatic`, `casual`, `horror`, `scary`, `thriller`, `creepy`. |
| `render` | body | boolean | No |  | Default true: render the MP4 (spends export minutes). false keeps an editable project and returns only editorUrl. |
| `dryRun` | body | boolean | No |  | Check the request and return { estimate } (credits and minutes) without spending anything. |
| `webhookUrl` | body | string (URL) | No |  | https URL that receives job.completed / job.failed, signed with your webhook secret. Up to 2048 chars. |
| `Idempotency-Key` | header | string | No |  | Retry-safe key: a retry with the same key and body within 24 hours returns the first job instead of starting (and charging) again. The same key with a different body is a 409. MCP clients pass it as the idempotencyKey argument. 1-255 chars. MCP: `idempotencyKey`. |

## Example

curl:

```bash
# 1. Dry run: the exact cost, nothing is spent.
curl https://api.clippie.ai/v1/videos/ai-story \
  -H "Authorization: Bearer $CLIPPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The lost library of Alexandria",
    "aspectRatio": "9:16",
    "durationSeconds": 60,
    "dryRun": true
  }'
# => { "dryRun": true, "estimate": { "credits": ..., "minutes": { ... }, "wouldSucceed": true } }

# 2. The real call. Keep the key and send the same one if you retry, so it is never charged twice.
KEY=$(uuidgen)
curl https://api.clippie.ai/v1/videos/ai-story \
  -H "Authorization: Bearer $CLIPPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{
    "prompt": "The lost library of Alexandria",
    "aspectRatio": "9:16",
    "durationSeconds": 60
  }'
# => 202 { "job": { "id": "job_...", "status": "queued", ... } }
```

create-ai-story-video.mjs:

```js
import { randomUUID } from 'node:crypto';

const auth = { Authorization: `Bearer ${process.env.CLIPPIE_API_KEY}` };

const input = {
  "prompt": "The lost library of Alexandria",
  "aspectRatio": "9:16",
  "durationSeconds": 60
};

async function call(body, headers = {}) {
  const res = await fetch('https://api.clippie.ai/v1/videos/ai-story', {
    method: 'POST',
    headers: { ...auth, 'Content-Type': 'application/json', ...headers },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(`${json.error.type}: ${json.error.message}`);
  return json;
}

// 1. Dry run: the exact cost, nothing is spent. Confirm it before going on.
const { estimate } = await call({ ...input, dryRun: true });
console.log(estimate); // { credits, minutes, wouldSucceed, reason }

// 2. Create. Keep the key and reuse it on retries, so a retry never charges twice.
let { job } = await call(input, { 'Idempotency-Key': randomUUID() });

// 3. Wait. Each call holds for up to 30 seconds until the job changes.
while (!['completed', 'failed', 'canceled'].includes(job.status)) {
  const res = await fetch(`https://api.clippie.ai/v1/jobs/${job.id}?wait=30`, { headers: auth });
  ({ job } = await res.json());
}
console.log(job.status, job.output);
```

## Response

`202 { job }`: the job, straight away. Wait for it with [Get job](https://clippie.ai/developers/docs/get-job.md) (`?wait=30`) or a `webhookUrl`; see [Jobs and waiting](https://clippie.ai/developers/docs.md#jobs). With `"dryRun": true` the answer is `200 { dryRun: true, estimate }` and nothing is started.

202 Accepted:

```json
{
  "job": {
    "id": "job_abc123",
    "object": "job",
    "kind": "create_ai_story_video",
    "status": "queued",
    "step": null,
    "progress": null,
    "input": {
      "prompt": "The lost library of Alexandria"
    },
    "output": null,
    "cost": {
      "credits": 0,
      "minutes": {
        "voiceover": 1,
        "captions": 1,
        "export": 1
      }
    },
    "error": null,
    "source": "api",
    "webhookUrl": null,
    "createdAt": "2026-10-24T12:00:00.000Z",
    "startedAt": null,
    "completedAt": null
  }
}
```

Dry run (200), shape only:

```json
{
  "dryRun": true,
  "estimate": {
    "credits": 0,
    "minutes": {
      "voiceover": 0,
      "captions": 0,
      "export": 0
    },
    "wouldSucceed": true
  }
}
```

## From an MCP client

Your AI calls `create_ai_story_video` with the same fields as JSON arguments, plus `idempotencyKey` instead of the header. See [MCP server](https://clippie.ai/developers/docs.md#mcp) to connect one.

tools/call:

```json
{
  "name": "create_ai_story_video",
  "arguments": {
    "prompt": "The lost library of Alexandria",
    "aspectRatio": "9:16",
    "durationSeconds": 60,
    "idempotencyKey": "a-unique-key-per-thing-you-make"
  }
}
```