Developers
KolaVid API and MCP server
Make narrated whiteboard explainer videos from your own code, Zapier, Make, or right inside ChatGPT, Claude and other AI assistants. Videos use your account's credits and appear in your KolaVid library.
API keys
Make a key in Account > API keys. It starts with kv_live_ and is shown once, so copy it then. Send it with every request:
Authorization: Bearer kv_live_...A key acts as your account: videos use your credits (60 credits per minute of video, charged when the video is finished; a video that fails costs nothing). Revoke a key on the same page and it stops working at once. Integrations may name themselves in an X-KolaVid-Client header, such as zapier.
Start a video
POST https://kolavid.com/api/v1/videos with a JSON body. Give at least one of prompt, text or source_url (not both text and source_url).
| Field | Type | What it is |
|---|---|---|
prompt | string | The topic and any instructions: audience, tone, what to cover. |
text | string | Source text to explain (an article, notes, a script), up to 100,000 characters. |
source_url | string | A public web page to explain (up to three, separated by spaces). |
length_minutes | integer | 1 to 5. Default 1. |
aspect_ratio | string | 16:9 (default), 9:16 or 1:1. |
voice | string | female (default), male, or a voice by name: Kore, Leda, Aoede, Zephyr, Puck, Charon, Fenrir, Orus... |
language | string | Narration language, for example Spanish. Default English. |
curl https://kolavid.com/api/v1/videos \
-H "Authorization: Bearer $KOLAVID_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "How vaccines work, for 12-year-olds", "length_minutes": 2}'The answer is 201 Created:
{
"id": "4d018ec2-...",
"status": "queued",
"created_at": "2026-11-02T12:00:00Z",
"app_url": "https://kolavid.com/app/jobs/4d018ec2-...",
"status_url": "https://kolavid.com/api/v1/videos/4d018ec2-..."
}Check a video
A video takes about 2 to 4 minutes. Poll GET /api/v1/videos/{id} (the status_url) every 30 seconds or so. status is queued, making, completed or failed; progress is 0 to 100.
{
"id": "4d018ec2-...",
"status": "completed",
"progress": 100,
"title": "How vaccines work, for 12-year-olds",
"length_minutes": 2,
"aspect_ratio": "16:9",
"created_at": "2026-11-02T12:00:00Z",
"completed_at": "2026-11-02T12:03:10Z",
"video_url": "https://kolavid.com/api/v1/files/4d018ec2-.../video?expires=...&sig=...",
"thumbnail_url": "https://kolavid.com/api/v1/files/4d018ec2-.../thumbnail?expires=...&sig=...",
"share_url": null,
"app_url": "https://kolavid.com/app/jobs/4d018ec2-...",
"error": null
}video_url is the MP4 once the video is completed. It needs no key and works for 24 hours; ask again for a fresh link. share_url is the public page if you shared the video in the app, and error says why a video failed (no credits are used).
List videos and your account
GET /api/v1/videos?limit=25&status=completed returns {"videos": [...]}, newest first, each in the shape above. limit is 1 to 100; with status=completed the list is ordered by when each video finished.
GET /api/v1/me returns {"email", "credits", "plan"}; the plan is free, starter, creator or studio.
Errors
Errors are JSON with detail, a sentence you can show, and error, a code.
| 401 | Missing, wrong or revoked key. |
| 402 | Not enough credits for that length. The body has pricing_url. |
| 403 | The account is closed. |
| 404 | No such video in this account, or an expired file link. |
| 422 | A field is wrong, the link can't be read, or the request was refused under the content rules. |
| 429 | Another video of this account is still being made (one at a time), or more than 60 requests a minute with one key (see Retry-After). |
ChatGPT, Claude and other AI assistants (MCP)
The KolaVid MCP server is https://kolavid.com/mcp. Add it as a connector or app in your assistant, sign in to KolaVid when asked, and ask for a video in the chat. Its tools are make_whiteboard_video, get_video, list_recent_videos and get_my_account.
- Claude: in Customize, Connectors, add a custom connector with the address above (step by step: KolaVid in Claude).
- ChatGPT: in Settings, Apps, turn on developer mode and add an app with the address above.
- Cursor: add
{"mcpServers": {"kolavid": {"url": "https://kolavid.com/mcp"}}}to~/.cursor/mcp.json. - Claude Code:
claude mcp add --transport http kolavid https://kolavid.com/mcp
Sign-in is OAuth 2.1 with PKCE and dynamic client registration, found from /.well-known/oauth-protected-resource. Clients that take a header instead can send an API key as Authorization: Bearer kv_live_.... See and disconnect connected apps in Account > API keys.
Help
Email [email protected]. Use of the API is covered by the Terms of Service and the Privacy Policy.