# Create a 3D story series

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

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.

## At a glance

| Property | Value |
| --- | --- |
| 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](https://clippie.ai/developers/docs/estimate-cost.md)) first to see the exact cost without spending anything. |
| Limit bucket | `ai_video` (see [Rate limits](https://clippie.ai/developers/docs.md#rate-limits)) |

## Parameters

| Name | In | Type | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `idea` | body | string | Yes |  | The "What if" idea, e.g. "What if every time you sneeze you teleport?" 8-400 chars. |
| `lengthSeconds` | body | number | No | `60` | About how long each episode is: 30, 60, 120 or 300 seconds. One of `30`, `60`, `120`, `300`. |
| `episodes` | body | integer | No | `1` | How many episodes, 1-4. Same rule and cast, a new story each. 1-4. |
| `voiceId` | body | string | No |  | 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` | body | string | No | `"blockworld"` | The 3D look, a style id from list_story_styles. Default: blockworld. Up to 40 chars. |
| `look` | body | object | No |  | Optional look settings. Anything you leave out is chosen for the story (or taken from referenceVideo). |
| `referenceVideo` | body | string | No |  | 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` | body | string | No |  | 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` | body | boolean | No |  | false: no background music; the voice and sound effects stay. For adding your own sound when you post. Default true. |
| `captions` | body | boolean | No |  | false: the videos come without burned-in captions (on-screen cards and counters stay). Default true. |
| `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/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", ... } }
```

create-3d-story.mjs:

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

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

const input = {
  "idea": "IDEA"
};

async function call(body, headers = {}) {
  const res = await fetch('https://api.clippie.ai/v1/videos/3d-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_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:

```json
{
  "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](https://clippie.ai/developers/docs.md#mcp) to connect one.

tools/call:

```json
{
  "name": "create_3d_story",
  "arguments": {
    "idea": "IDEA",
    "idempotencyKey": "a-unique-key-per-thing-you-make"
  }
}
```
