Clippie AI logo
Browse the docs

Developers / Docs / Resources

Create a 3D story series

Makes 1-4 finished 3D animated story shorts (9:16, toy block characters, fast cuts, one-word captions, sound effects and music) from one "What if" idea, rendered on Clippie's GPUs. You may choose the narrator (voiceId), the look (style and look, see list_story_styles) or a story template of the style; the job output says which style, voice, look and music were used. Costs 300 credits per minute of video, voice included (each episode counts as at least 30 seconds); no voiceover minutes are spent. The cost shown is an estimate for the length asked: the script decides the real length, and an episode that runs more than 3 seconds longer is charged its extra seconds at the same rate when it finishes, never more than 50% on top. Each failed episode is refunded. Takes about 25-40 minutes per episode: wait with get_job; its output lists every episode with videoUrl and coverUrl as they finish. Run dryRun: true first and confirm the cost.

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

At a glance

  • REST
    POST https://api.clippie.ai/v1/videos/3d-story
  • MCP tool
    create_3d_story
  • 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
    ai_video (see Rate limits)

Parameters

  • idea
    In:
    body
    Type:
    string
    Required:
    Yes
    Description:
    The "What if" idea, e.g. "What if every time you sneeze you teleport?" 8-400 chars.
  • lengthSeconds
    In:
    body
    Type:
    number
    Required:
    No
    Default:
    60
    Description:
    About how long each episode is: 30, 60, 120 or 300 seconds. One of 30, 60, 120, 300.
  • episodes
    In:
    body
    Type:
    integer
    Required:
    No
    Default:
    1
    Description:
    How many episodes, 1-4. Same rule and cast, a new story each. 1-4.
  • voiceId
    In:
    body
    Type:
    string
    Required:
    No
    Description:
    The narrator: a voice id from list_voices (Clippie's or your own cloned voice). Leave it out and a narrator that fits the story is picked from the style's own voices (list_story_styles), a different one from your last few series. 1-64 chars.
  • style
    In:
    body
    Type:
    string
    Required:
    No
    Default:
    "blockworld"
    Description:
    The 3D look, a style id from list_story_styles. Default: blockworld. Up to 40 chars.
  • look
    In:
    body
    Type:
    object
    Required:
    No
    Description:
    Optional look settings. Anything you leave out is chosen for the story (or taken from referenceVideo).
  • referenceVideo
    In:
    body
    Type:
    string
    Required:
    No
    Description:
    A video to imitate: a file id from POST /v1/files (file_…) or a link to a TikTok, Instagram or YouTube video, up to 5 minutes. Its story shape, pacing, captions, narrator type and speed, and look are copied; its story, characters and words never are. Your own voiceId and look settings win over it. Adds about a minute. 1-2048 chars.
  • template
    In:
    body
    Type:
    string
    Required:
    No
    Description:
    A story template of the style, a template id from list_story_styles: a proven kind of video (its story shape, beat order, pace, look, captions and sound) that your idea is told in. Your own voiceId and look settings win over it. Not together with referenceVideo. Up to 60 chars.
  • music
    In:
    body
    Type:
    boolean
    Required:
    No
    Description:
    false: no background music; the voice and sound effects stay. For adding your own sound when you post. Default true.
  • captions
    In:
    body
    Type:
    boolean
    Required:
    No
    Description:
    false: the videos come without burned-in captions (on-screen cards and counters stay). Default true.
  • 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/3d-story \
  -H "Authorization: Bearer $CLIPPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idea": "IDEA",
    "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/3d-story \
  -H "Authorization: Bearer $CLIPPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{
    "idea": "IDEA"
  }'
# => 202 { "job": { "id": "job_...", "status": "queued", ... } }

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_3d_story",
    "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_3d_story with the same fields as JSON arguments, plus idempotencyKey instead of the header. See MCP server to connect one.

tools/call
{
  "name": "create_3d_story",
  "arguments": {
    "idea": "IDEA",
    "idempotencyKey": "a-unique-key-per-thing-you-make"
  }
}