KolaVid

npx add-mcp 'https://kolavid.com/mcp'

Quickstart

Make a key, start a video, check it until it's finished, then download the MP4. A video takes a minute or two.

# 1. Start a video
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}'

# 2. Check it (repeat until "status" is "completed")
curl https://kolavid.com/api/v1/videos/VIDEO_ID \
  -H "Authorization: Bearer $KOLAVID_API_KEY"

# 3. Download "video_url" from the answer: it needs no key

Authentication

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 and appear in your library.
• Revoke a key on the same page and it stops working at once.
• Keep keys on your server. Integrations may name themselves in an X-KolaVid-Client header, such as zapier.

Create a video

POST /api/v1/videos

Send a JSON body with at least one of prompt, text or source_url (not both text and source_url).

Field	Type	Required	Description
prompt	string	One of these three	The topic and any instructions: audience, tone, what to cover.
text	string	One of these three	Source text to explain (an article, notes, a script), up to 100,000 characters.
source_url	string	One of these three	A public web page to explain (up to three, separated by spaces).
length_minutes	integer	Optional	1 to 5. Default 1.
aspect_ratio	string	Optional	16:9 (default), 9:16 or 1:1.
voice	string	Optional	female (default), male, or a voice by name: Kore, Leda, Aoede, Zephyr, Puck, Charon, Fenrir, Orus...
language	string	Optional	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-..."
}

Get a video

GET /api/v1/videos/{id}

A video takes a minute or two. Ask for it (the status_url) every 15 to 30 seconds until status is completed or failed.

status	Meaning
queued	Accepted, waiting to start.
making	Being written, drawn and narrated. progress goes from 0 to 100.
completed	Finished: video_url and thumbnail_url are set.
failed	Stopped: error says why. No credits are used.

{
  "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:01:40Z",
  "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.
• error says why a video failed (no credits are used).

List videos

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.

Your account

GET /api/v1/me

Your credit balance and plan: free, starter, creator or studio.

{
  "email": "[email protected]",
  "credits": 4880,
  "plan": "starter"
}

Errors

Errors are JSON with detail, a sentence you can show to people, and error, a code for your program.

{
  "detail": "A 2-minute video needs 120 credits and you have 40. Choose a shorter video or open Billing to subscribe or top up credits.",
  "error": "insufficient_credits",
  "pricing_url": "https://kolavid.com/pricing"
}

Status	Meaning
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).

Limits and credits

• One video at a time per account; a second one answers 429 until the first is finished.
• 60 requests a minute per key; past that the answer is 429 with a Retry-After header.
• 60 credits per minute of video, charged when the video is finished. A video that fails costs nothing.
• Files (MP4 and thumbnail) are signed links that last 24 hours.

Plans and credits are on the pricing page.

SDKs

The official clients send your key, wait for a video to finish, download it, retry when you hit the rate limit, and turn errors into typed exceptions (for example InsufficientCreditsError with the pricing link). Both have no dependencies.

Python

Python 3.9 or newer, on PyPI.

pip install kolavid

JavaScript and TypeScript

Node 18 or newer, Deno, Bun and edge workers, on npm.

npm install kolavid

• videos.create, videos.get, videos.list, videos.wait, videos.download and me match the endpoints above. Examples are in the Quickstart.
• The key comes from KOLAVID_API_KEY or the constructor. The JavaScript client refuses to run in a web page unless you say the key is the user's own.
• A request that may have started a video is never sent again, so a retry can't make a second video.

MCP server for AI assistants

Add https://kolavid.com/mcp to ChatGPT, Claude or any MCP client, sign in to KolaVid when asked, and ask for a video in the chat. It is listed in the official MCP Registry as com.kolavid/kolavid.

Tool	What it does
make_whiteboard_video	Starts a video from a topic, a text or a web page: length, shape and narration language.
get_video	Its progress while it's being made, then the download link and a link to watch, edit or share it.
list_recent_videos	The account's recent videos.
get_my_account	Credit balance and plan.

Claude

In Customize, Connectors, add a custom connector with the address above. Step by step: KolaVid in Claude.

Claude Code

claude mcp add --transport http kolavid https://kolavid.com/mcp

Cursor and other clients

{
  "mcpServers": {
    "kolavid": { "url": "https://kolavid.com/mcp" }
  }
}

ChatGPT

In Settings, Apps, turn on developer mode and add an app with the address above.

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.