Browse the 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.

Or open inClaude Code Codex Cursor Claude ChatGPT

Paste it into any AI assistant. The shortcuts open with the prompt typed in; nothing is sent until you press enter.

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) first to see the exact cost without spending anything.
Limit bucket	`render` (see Rate limits)

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) first to see the exact cost without spending anything.
Limit bucket
render (see Rate limits)

Parameters

Name	In	Type	Required	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`.

prompt
In:
body
Type:
string
Required:
No
Description:
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
In:
body
Type:
string
Required:
No
Description:
The exact narration to use (it sets the length; durationSeconds is ignored). 20-12000 chars.
voiceoverFileId
In:
body
Type:
string
Required:
No
Description:
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
In:
body
Type:
string
Required:
No
Description:
Project and file name. Defaults to the start of the prompt or script. 1-120 chars.
storyTemplateId
In:
body
Type:
string
Required:
No
Description:
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
In:
body
Type:
string
Required:
No
Description:
Narration voice id from list_voices (catalog voices or your own cloned ones). Defaults to your brand voice. 1-64 chars.
artStyleId
In:
body
Type:
string
Required:
No
Description:
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
In:
body
Type:
string
Required:
No
Description:
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
In:
body
Type:
string
Required:
No
Description:
Style preset (a type "stylePrompt" id) for imageModel. Up to 64 chars.
aspectRatio
In:
body
Type:
string
Required:
No
Description:
Frame shape. Defaults to the story template, then your brand. One of 9:16, 16:9.
durationSeconds
In:
body
Type:
integer
Required:
No
Description:
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
In:
body
Type:
string
Required:
No
Description:
Narration and caption language code from list_languages (e.g. "en", "es", "ja"). Default: detected. Up to 10 chars.
captionStyleId
In:
body
Type:
integer
Required:
No
Description:
Caption style id from list_caption_styles. Defaults to your brand caption style. 1-17.
musicId
In:
body
Type:
string
Required:
No
Description:
Background music id from list_music, or "none" for no music. Defaults to your brand track. Up to 64 chars.
theme
In:
body
Type:
string
Required:
No
Description:
Subject direction for a script written from prompt. One of any, historical, scientific, geography, politics, nature, religion, technology, psychology, mystery, space, mythology, war.
tone
In:
body
Type:
string
Required:
No
Description:
Voice and pacing for a script written from prompt. One of cinematic, suspenseful, educational, dark, inspirational, humorous, dramatic, casual, horror, scary, thriller, creepy.
render
In:
body
Type:
boolean
Required:
No
Description:
Default true: render the MP4 (spends export minutes). false keeps an editable project and returns only editorUrl.
dryRun
In:
body
Type:
boolean
Required:
No
Description:
Check the request and return { estimate } (credits and minutes) without spending anything.
webhookUrl
In:
body
Type:
string (URL)
Required:
No
Description:
https URL that receives job.completed / job.failed, signed with your webhook secret. Up to 2048 chars.
Idempotency-Key
In:
header
Type:
string
Required:
No
Description:
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

# 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

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 (?wait=30) or a webhookUrl; see Jobs and waiting. With "dryRun": true the answer is 200 { dryRun: true, estimate } and nothing is started.

202 Accepted

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

{
  "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 to connect one.

tools/call

{
  "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"
  }
}