Clippie AI logo
Get Started
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 create scope.
  • 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

curl
# 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", ... } }

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

tools/call
{
  "name": "write_script",
  "arguments": {
    "prompt": "Why octopuses have three hearts",
    "durationSeconds": 60,
    "tone": "educational",
    "idempotencyKey": "a-unique-key-per-thing-you-make"
  }
}