Whiteboard Video API: REST and MCP Server Guide

Make narrated whiteboard videos from code with the KolaVid REST API or MCP server: API keys, curl examples, polling, errors, limits and agent setup.

The KolaVid API lets your own software make narrated whiteboard videos. Send one POST request with a topic, some text or a web page URL and your API key, and KolaVid starts the video and returns an ID. Poll that ID until the status is `completed`, then download the MP4. For AI agents and assistants there is also an MCP server at `https://kolavid.com/mcp` with the same abilities as tools.

This guide covers the four REST endpoints with curl examples, the polling pattern, errors and limits, and how to connect an MCP client. The full reference is on the developer page.

What you can build

A few patterns that fit the API well:

• Publish hooks. When an article goes live in your CMS, send its URL and get a short explainer for it.
• Course builders. Generate a video for each lesson in an outline, in the learner's language.
• Internal tools. A "make a video" button in the wiki or help desk that turns a page of text into a 2-minute walkthrough.
• Batch jobs. A list of topics in a CSV, worked through one by one overnight.
• Agents. An AI agent that decides when a video would help and calls the MCP tool itself.

If you would rather not write code, the same API powers the Zapier and Make apps; see KolaVid in your other apps.

Authentication

Create a key in KolaVid under Account, API keys. It starts with `kv_live_` and is shown once, so store it straight away, for example in an environment variable. Send it on every request:

``` Authorization: Bearer kv_live_... ```

A key acts as your account: its videos use your credits and appear in your KolaVid library. Revoking a key on the same page stops it at once. If you are building an integration, you can name it in an `X-KolaVid-Client` header.

Start a video

`POST https://kolavid.com/api/v1/videos` with a JSON body:

```bash 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`:

```json { "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-..." } ```

The request fields

Give at least one of `prompt`, `text` or `source_url`, but not both `text` and `source_url`. Combining `prompt` with one of them works best: the source supplies the facts, the prompt says who the video is for.

Here is a vertical Spanish video made from your own text:

```bash curl https://kolavid.com/api/v1/videos \ -H "Authorization: Bearer $KOLAVID_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "Onboarding video for new warehouse staff", "text": "Every shift starts with a scanner check...", "length_minutes": 3, "aspect_ratio": "9:16", "voice": "male", "language": "Spanish"}' ```

Check a video and download it

A video takes about 2 to 4 minutes. The API does not call you back, so poll `GET /api/v1/videos/{id}` (the `status_url`) every 30 seconds or so:

```bash curl https://kolavid.com/api/v1/videos/4d018ec2-... \ -H "Authorization: Bearer $KOLAVID_API_KEY" ```

`status` is `queued`, `making`, `completed` or `failed`, and `progress` runs from 0 to 100. A finished video looks like this (shortened):

```json { "id": "4d018ec2-...", "status": "completed", "progress": 100, "title": "How vaccines work, for 12-year-olds", "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, "error": null } ```

`video_url` is the MP4. It needs no key and works for 24 hours; ask for the video again to get a fresh link. Copy the file into your own storage if you need it longer. `share_url` is the public page, filled in only if you shared the video in the KolaVid app. When `status` is `failed`, `error` says why, and no credits are used.

A small polling loop in the shell (with `jq` to read the JSON):

```bash while true; do status=$(curl -s "$STATUS_URL" -H "Authorization: Bearer $KOLAVID_API_KEY" | jq -r .status) [ "$status" = "completed" ] || [ "$status" = "failed" ] && break sleep 30 done ```

List videos and check 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, which makes it a simple way to pick up new videos on a schedule.

`GET /api/v1/me` returns your `email`, `credits` and `plan` (`free`, `starter`, `creator` or `studio`). Call it before a batch to be sure the credits will last.

Errors and limits

Errors are JSON with `detail`, a sentence you can show a user, and `error`, a code:

Two limits shape a batch job. First, one video at a time per account: start the next video only after the last one is `completed` or `failed`, or you will get a 429. Second, 60 requests a minute per key, which polling every 30 seconds stays well inside.

Credits work as in the app: 60 credits per minute of video, charged when the video is finished. A free account starts with 120 credits, enough for one 2-minute video, and free accounts make videos up to 2 minutes. Paid plans and their credits are on the pricing page.

The MCP server for AI agents

The KolaVid MCP server is `https://kolavid.com/mcp`, using the Streamable HTTP transport. It has four tools:

• `make_whiteboard_video`: start a video from `prompt`, `text` or `source_url`, with `length_minutes`, `aspect_ratio` and `language`
• `get_video`: status, progress and, when finished, the download link
• `list_recent_videos`: the newest videos, optionally filtered by status
• `get_my_account`: email, credit balance and plan

Sign-in is OAuth 2.1 with PKCE and dynamic client registration, discovered from `/.well-known/oauth-protected-resource`, so most clients only need the address. Clients that take a header instead can send an API key as `Authorization: Bearer kv_live_...`.

Adding it to common clients:

• Claude: Customize, Connectors, add a custom connector with the address above.
• ChatGPT: Settings, Apps, turn on developer mode and add an app with the address.
• 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`

Connected apps are listed under Account, API keys, where you can disconnect them.

FAQ

Is there a webhook when a video finishes?

No. Poll the video's `status_url`, or list `status=completed` videos on a schedule.

Can I make several videos at once?

Not in one account. Videos are made one at a time, so queue them on your side and start the next when the last one finishes.

What should the video explain?

Anything you can describe or paste: a lesson, a policy, a product. Developer teams often use it for their own docs; our post on explaining API concepts with whiteboard video has examples.

Where else can I use KolaVid?

In Slack, Discord, Telegram, Google Docs, Chrome, Zapier, Make and AI assistants. Our overview of all the ways to use KolaVid has each install link.

Make your first call

Create a key, run the first curl example with `"length_minutes": 1`, and open the `app_url` it returns to watch the video being drawn. When the status turns `completed`, you have an MP4 your code made.

Back to blog