API

Reference

Official API: https://api.manimotion.dev. Two endpoints. Examples in cURL, JavaScript, and Python — flip the tabs. Response JSON sits under every request example.

Auth header

Every call needs x-api-key (chalk_live_sk_v1_… from Settings → API keys). Public keys must also send storage.inline — there is no shared default bucket for API users.

auth.sh

# set once in your shell / CI secrets
export MANIMOTION_API=https://api.manimotion.dev
export MANIMOTION_KEY=chalk_live_sk_v1_...

# then pass on every request
curl -sS "$MANIMOTION_API/health" -H "x-api-key: $MANIMOTION_KEY"

RESPONSEGET /health (optional ping)

{
  "status": "ok",
  "service": "clarity-video"
}

POST /video/request

Starts a job. Returns immediately.

request.sh

curl -sS -X POST "$MANIMOTION_API/video/request" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $MANIMOTION_KEY" \
  -d '{
    "prompt": "Explain Bayes theorem with a medical testing example",
    "engine": "auto",
    "storage": {
      "inline": {
        "provider": "r2",
        "bucket": "my-lectures",
        "access_key_id": "'"$R2_ACCESS_KEY_ID"'",
        "secret_access_key": "'"$R2_SECRET_ACCESS_KEY"'",
        "account_id": "'"$R2_ACCOUNT_ID"'",
        "public_url": "'"$R2_PUBLIC_BASE_URL"'"
      }
    }
  }'

RESPONSEresponse.json

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "cached": false,
  "video_url": null,
  "engine": null
}

Field	Required	Notes
`prompt`	yes	STEM topic / lecture request. Min ~3 chars.
`engine`	no	`auto` (default) \| `manim` \| `remotion`
`model`	no	LLM id. Default deepseek/deepseek-v3.2
`duration`	no	Target seconds 15–180. Omit for auto (~20–120).
`storage`	no	Optional upload target — see Storage

GET /video/status/{job_id}

Poll until the job finishes.

status.sh

curl -sS "$MANIMOTION_API/video/status/$JOB_ID" \
  -H "x-api-key: $MANIMOTION_KEY"

RESPONSEcompleted.json

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "video_url": "https://cdn.example.com/videos/a1b2c3d4.mp4",
  "error": null,
  "cached": false,
  "engine": "manim",
  "duration": 54.2
}

FAILED SHAPE

cURL

curl -sS "$MANIMOTION_API/video/status/$JOB_ID" \
  -H "x-api-key: $MANIMOTION_KEY"

RESPONSEfailed.json

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "video_url": null,
  "error": "Render timed out after 3 retries",
  "cached": false,
  "engine": "remotion",
  "duration": null
}

Status values

status	Meaning	What you do
`queued`	Accepted, waiting	Keep polling
`processing`	Planning / TTS / render	Keep polling (2–3s)
`completed`	MP4 ready	Use video_url
`failed`	Generation crashed	Read error, fix prompt, retry

HTTP errors

Code	When
401	Missing / invalid x-api-key
400	Bad body (empty prompt, bad duration, bad storage)
404	Unknown job_id
429	Quota: guests 1 video / IP; free plan 3 / day; paid & owner unlimited

Prompt tips

One clear topic beats “explain all of physics”.
Name the audience (“first-year CS”, “AP Calc”).
Ask for the visual: graph, derivation steps, timeline…
Prefer omitting duration unless you need a hard length.

Engines details → Engines. BYO bucket → Storage.