Browse the docs
Developers / Docs / AI tools
Write a script
Writes a narration script for a short video from a topic, with the AI Story editor's writer, a theme, a tone and a target length. Free: spends no credits or minutes. Finishes within the call: the job comes back completed with output.script. Pass the script on to text_to_speech or create_ai_story_video.
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/ai/scripts
- MCP tool
write_script
- Scope
create
- Cost
- Spends nothing, but starts a job like the other create calls and needs the
createscope.
- Spends nothing, but starts a job like the other create calls and needs the
- Limit bucket
llm(see Rate limits)
Parameters
prompt- In:
- body
- Type:
- string
- Required:
- Yes
- Description:
- The topic or idea, e.g. "the fall of the Roman Empire". 1-2000 chars.
durationSeconds- In:
- body
- Type:
- integer
- Required:
- No
- Default:
60- Description:
- Target narration length, 30-300 seconds. 30-300.
theme- In:
- body
- Type:
- string
- Required:
- No
- Default:
"any"- Description:
- One of
any,historical,scientific,geography,politics,nature,religion,technology,psychology,mystery,space,mythology,war.
tone- In:
- body
- Type:
- string
- Required:
- No
- Default:
"cinematic"- Description:
- One of
cinematic,suspenseful,educational,dark,inspirational,humorous,dramatic,casual,horror,scary,thriller,creepy.
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
# 1. Dry run: the exact cost, nothing is spent.
curl https://api.clippie.ai/v1/ai/scripts \
-H "Authorization: Bearer $CLIPPIE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Why octopuses have three hearts",
"durationSeconds": 60,
"tone": "educational",
"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/ai/scripts \
-H "Authorization: Bearer $CLIPPIE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $KEY" \
-d '{
"prompt": "Why octopuses have three hearts",
"durationSeconds": 60,
"tone": "educational"
}'
# => 202 { "job": { "id": "job_...", "status": "queued", ... } }import { randomUUID } from 'node:crypto';
const auth = { Authorization: `Bearer ${process.env.CLIPPIE_API_KEY}` };
const input = {
"prompt": "Why octopuses have three hearts",
"durationSeconds": 60,
"tone": "educational"
};
async function call(body, headers = {}) {
const res = await fetch('https://api.clippie.ai/v1/ai/scripts', {
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.
{
"job": {
"id": "job_abc123",
"object": "job",
"kind": "write_script",
"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
}
}{
"dryRun": true,
"estimate": {
"credits": 0,
"minutes": {
"voiceover": 0,
"captions": 0,
"export": 0
},
"wouldSucceed": true
}
}From an MCP client
Your AI calls write_script with the same fields as JSON arguments, plus idempotencyKey instead of the header. See MCP server to connect one.
{
"name": "write_script",
"arguments": {
"prompt": "Why octopuses have three hearts",
"durationSeconds": 60,
"tone": "educational",
"idempotencyKey": "a-unique-key-per-thing-you-make"
}
}