Reference

API reference

Every endpoint, field and value. For a guided walkthrough, start with the Quickstart.

Basics

Topic	Details
Base URL	`https://api.manimotion.dev`
Authentication	Header `x-api-key: chalk_live_sk_v1_…`, from Settings → API keys
Format	JSON request bodies with `Content-Type: application/json`; JSON responses
Errors	4xx/5xx with `{"detail": "…"}`. See Errors

Endpoint	Purpose
`POST /video/request`	Start a video
`GET /video/status/{job_id}`	Progress and result
`GET /models`	Supported models and your access
`GET /health`	Uptime check, no key needed

POST /video/request

Starts a video and returns right away with a job_id. Checks run in order (key, model, storage, plan limit), and a request that fails any of them is rejected without counting toward your limit.

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",
    "style": "auto"
  }'

RESPONSEresponse.json

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "cached": false,
  "video_url": null,
  "eta_seconds": 150,
  "eta_display": "~2–3 min",
  "message": "Queued…",
  "tier": "tier2",
  "model": "anthropic/claude-haiku-5.5",
  "key_source": "platform"
}

Body

Field	Type	Description
`prompt`	string	What the lecture is about. 10–2000 characters. Name the audience and the visual you want for best results.
`model`	optional	Model id, e.g. `anthropic/claude-sonnet-5.5`. Defaults to Claude Haiku 5.5, or to your connected AI key’s default model. See Models.
`llm`	optional	`{ "provider", "api_key" }`: run this video on your own AI key. Provider is `openrouter`, `anthropic`, `openai` or `gemini`. Not stored. See Bring your own key.
`style`	optional	`auto` (default), `math` or `graphics`. See Styles.
`duration`	optional	Target length in seconds, 15–180. A soft target; leave it out to let the lesson set its own length (usually 20–120).
`tier`	optional	`tier1` (fastest, ~1–2 min), `tier2` (default, ~2–3 min) or `tier3` (most detailed, ~4–5 min).
`storage`	optional	`{ "integration_id" }` for a saved bucket, or `{ "inline": {…} }` for per-request credentials. Leave it out to use your most recent saved bucket. See Storage.

Response

Field	Description
`job_id`	Id to pass to GET /video/status
`status`	`queued`, or `completed` when `cached` is true
`cached`	`true` if an identical recent request was reused; `video_url` is then already set
`eta_seconds`	Rough time to finish; `eta_display` is the same, for humans
`model`	The model that will write the lesson
`key_source`	`byok` (your AI key) or `platform` (ours)
`tier`	The tier the job runs at

GET /video/status/{job_id}

Returns the job’s progress, then its result. Poll every 2–3 seconds. You can only read jobs created with your own account’s keys.

status.sh

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

RESPONSEresponse.json

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "video_url": "https://cdn.example.com/videos/a1b2c3d4.mp4",
  "error": null,
  "error_code": null,
  "model": "anthropic/claude-haiku-5.5",
  "key_source": "platform",
  "cached": false,
  "style": "math",
  "duration": 54.2,
  "phase": "completed",
  "message": "Done!",
  "eta_seconds": 0,
  "tier": "tier2"
}

Response

Field	Description
`status`	Where the job is; see below
`message`	Human-readable progress, e.g. “Generating narration…”
`eta_seconds`	Estimated seconds left, while in progress
`video_url`	The MP4, once `completed`
`duration`	Video length in seconds
`style`	`math` or `graphics`: the style that was used
`error`	Why it failed, when `failed`. Safe to show to users
`error_code`	Machine-readable reason, when `failed`. See job failure codes
`model`	The model that wrote the lesson
`key_source`	`byok` or `platform`

Status values

status	Meaning
`queued`	Accepted, about to start
`processing` `planning` `generating_audio` `generating_code` `merging` `uploading`	Working. Each step updates message and eta_seconds
`completed`	Done. Use `video_url`
`failed`	Stopped. Read `error` and `error_code`

GET /models

The model catalog. Send your API key and each model includes available and via (byok, platform or null), and providers shows which AI keys you’ve connected. Full example on the Models page.

GET /health

Returns {"status": "ok", "service": "manimotion"} when the API is up. No key needed; use it for uptime checks.

Limits

Plan	Videos	Output
Free	3 per day	720p, watermarked
Hobby	40 per month	1080p
Pro	80 per month	1080p

Videos are counted per API key. Daily limits reset at midnight UTC, monthly ones on the 1st. Separately, each IP address can send up to 20 video requests per 10 minutes. Over either limit you get 429.

Errors

Status codes, job failure codes and retry advice are on the Errors page.