Make videos from code.

Quickstart

Four calls take a prompt to a video you can play and share. Every example uses curl; any HTTP client works.

1. Make a key

Sign in at tryivan.com, open Account, and choose Create a key under API keys. The key is shown once. Keep it on your server, never in a web page or an app people download.

export IVAN_API_KEY=ivan_sk_live_…

2. Ask for a video

Send what the video should explain. The Idempotency-Key makes the request safe to repeat: keep it, and if the call fails or times out, send it again with the same key. You get the same video, never a second one.

KEY=$(uuidgen)
curl https://api.tryivan.com/v1/videos \
  -H "Authorization: Bearer $IVAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"prompt": "How do vaccines train the immune system?", "max_credits": 1000}'

The answer is 202 Accepted with the video, "status": "queued", and its id, such as vid_01J8….

3. Wait for it

Ask for the video with wait_seconds=25. Ivan holds the call until the video changes or 25 seconds pass, so a loop of these calls follows it closely without hammering. Stop when status is completed, failed or canceled.

curl "https://api.tryivan.com/v1/videos/vid_01J8…?wait_seconds=25" \
  -H "Authorization: Bearer $IVAN_API_KEY"

4. Fetch it

Download the film, or its captions, transcript or poster, from Ivan's own host.

curl -o video.mp4 "https://api.tryivan.com/v1/videos/vid_01J8…/content" \
  -H "Authorization: Bearer $IVAN_API_KEY"

5. Share it

A video is private until you share it. Sharing gives it a public page anyone with the link can watch, and a player other sites can embed.

curl -X POST https://api.tryivan.com/v1/videos/vid_01J8…/share \
  -H "Authorization: Bearer $IVAN_API_KEY"

MCP server

An AI agent can use Ivan as tools, with no code to write. Ivan's MCP server is at https://mcp.tryivan.com/mcp. Claude, ChatGPT and Grok connect to it by signing in; coding agents send the same key as the API, the same way. Connect it once, then ask your agent for a video: "Make me an Ivan video on how tides work."

Claude, ChatGPT and Grok

These three connect with no key to copy. Add Ivan to the app as a custom connector with the URL https://mcp.tryivan.com/mcp; it needs no client ID or secret. The app sends you to tryivan.com, where you sign in and press Allow.

Claude, on claude.ai or the desktop app: open Add custom connector with Ivan filled in, or go to Settings, Connectors, Add custom connector and paste the URL.

ChatGPT, and Grok on grok.com: add a custom connector in the app's settings and paste the URL. ChatGPT lists custom connectors under Apps, with developer mode switched on.

On the Allow screen you set what the app may spend: a limit for the month, $10 unless you change it, and a limit for any one video, $3. A video that would hold more than the one-video limit is made shorter to fit. Public links are off unless you switch them on there: the app gives you a private link to watch, and share_video is refused with insufficient_scope. A connected app has up to 5 videos in progress at once.

The app never holds a key. It holds a token that lasts an hour and renews itself, and asks you to sign in again once it has gone 90 days unused. See what each app has spent, and disconnect one, under Connected apps in your account. A disconnected app is stopped the way a revoked key is, and the videos it started still finish. To change a limit, connect the app again. However often an app is connected, and after a disconnect too, what it spent this month still counts. These tokens work on the MCP server only, never on the API.

Ivan is invite-only, so signing in needs an account. Only these three apps can connect this way; every other agent uses a key.

Claude Code

claude mcp add --transport http ivan https://mcp.tryivan.com/mcp \
  --header "Authorization: Bearer $IVAN_API_KEY"

Codex

codex mcp add ivan --url https://mcp.tryivan.com/mcp \
  --bearer-token-env-var IVAN_API_KEY

Cursor

In ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ivan": {
      "url": "https://mcp.tryivan.com/mcp",
      "headers": { "Authorization": "Bearer ${env:IVAN_API_KEY}" }
    }
  }
}

VS Code

In .vscode/mcp.json:

{
  "servers": {
    "ivan": {
      "type": "http",
      "url": "https://mcp.tryivan.com/mcp",
      "headers": { "Authorization": "Bearer ${input:ivan-key}" }
    }
  },
  "inputs": [
    { "id": "ivan-key", "type": "promptString", "description": "Ivan API key", "password": true }
  ]
}

Any other agent

Point an MCP client at the URL over Streamable HTTP, with the header Authorization: Bearer ivan_sk_live_…. The server answers every protocol version from 2024-11-05 to 2026-07-28, keeps no session, and replies to each POST with plain JSON. Signing in is for Claude, ChatGPT and Grok only; any other client is asked for a key.

The tools

A finished video from wait_for_video or get_video carries download_url, a link to its MP4 file that needs no key and works for an hour. An agent that can upload or attach files, in Slack or another chat app, fetches it and posts the video itself, so it plays where the person asked. The agent is told this when it connects.

Each tool is one of the endpoints below and answers with the same JSON, so the video, the credits and limits and the key's scopes work as they do on the API. A refusal comes back as the tool's answer, marked as an error, with the same code. create_video takes an optional idempotency_key. Without one, the same request from the same key in the last 10 minutes answers with the video it made, so an agent that repeats a call it lost the answer to is never charged twice; once that video is canceled, deleted, or fails with nothing charged, the same request makes a new one. Send a new idempotency_key to make another video like one already made. A video made this way has a channel of mcp: and the name of the agent that asked, such as mcp:claude-code.

Keys and authentication

Send your key on every request as a bearer token, to the API host and nowhere else:

Authorization: Bearer ivan_sk_live_…

The API lives at https://api.tryivan.com/v1. That host answers nothing but /v1, and reads nothing but the key: no cookie, no sign-in. The site at tryivan.com never answers /v1. Call the API from a server or an agent; it does not answer pages in a browser, and a key in a web page is a key anyone can copy.

Make and revoke keys in the API keys section of your account. A key is shown once, when it is made; Ivan keeps only a hash of it. Each key has a name, its scopes, a monthly cap and a limit on videos in progress. An account holds up to 10 active keys. A revoked key can make, cancel, delete or share nothing from that moment, and stops reading within 15 seconds; videos it already started still finish and are settled.

A team's admins make keys for the team itself in the team console, under API keys. Such a key acts as the team, not as a person: it keeps working when people leave, and what it makes is charged to the team's pool, up to the key's monthly cap. A team's keys share the team's rate limits and one set of Idempotency-Keys, so give each service its own.

A key is ivan_sk_live_, 40 random letters and digits, and a 6-character checksum, so a mistyped key is refused without a lookup and secret scanners can recognise a leaked one. The account page shows only its last four characters.

Keys belong to member accounts that are approved. The operator's account cannot hold keys. Every response carries a request-id header, the id Ivan's logs carry; quote it when you contact support. No response is cached.

Scopes

A key does only what its scopes allow. A new key has every scope unless you untick some when you make it. A call outside a key's scopes is refused with insufficient_scope.

GET /v1/me needs no scope.

Idempotency

Every POST /v1/videos must carry an Idempotency-Key header: 8 to 100 visible ASCII characters, such as a UUID. Use a new key for each new video.

Repeating a request with the same key and the same body returns the same video, 202, with the header Idempotent-Replayed: true. The body is compared as JSON, so the order of its fields and its spacing do not matter. The same key with a different body is refused with idempotency_key_reused.

Keys are remembered for the account, across all of its API keys. Repeat a create whenever its outcome is unknown: a dropped connection, a timeout, or any 5xx. A request that runs past 120 seconds is answered timeout and may still have been accepted, so repeat it with the same key.

Credits and limits

Videos are paid for in credits: 1,000 credits are $1. A video is charged by the minute of what it delivers, at its power's rate:

The hold. Ivan's writer chooses each video's length. When a video starts, it holds the price of the longest video it may run: up to 15 minutes, and no more than the account can spend, the key may still commit this month, the request's max_credits allows, or a connected app's limit for one video allows. The writer is told that length. When the video finishes, it is charged for the length it delivered, rounded up to a whole credit, and the rest of the hold is released. A video that fails is not charged. A hold is never less than one minute at the video's rate; a max_credits below that is refused with max_credits_too_low.

A board prompt. With look board, a prompt of several sentences may be spoken as written, so it can set its own length. If speaking it could run longer than the account's credits, the key's month or max_credits pay for, the video holds the full 15 minutes instead, and is refused if that hold can't be covered. A refusal over money carries credits_needed, the hold to allow for.

Estimates. POST /v1/videos/estimate takes the same body as a create, holds nothing, and says what the video would hold, how long it could run, and whether it can start now.

Each key's monthly cap. A key may commit only so many credits in a calendar month (UTC): held work counts at its hold, finished work at its charge. A new key's cap is 50,000 credits ($50) unless you choose another, up to 10,000,000 ($10,000); 0 stops it spending. A video that would pass it is refused with spend_cap_reached.

Videos in progress. An account makes 3 videos at once, 6 once it has bought $50 of credits, and 12 from $500. Ask for more and they still start straight away while Ivan has machines to spare, though it always keeps a couple free for other people; when it is busy, they wait for the account's own videos to finish while other people's go first. Up to 20 more may wait; past that, a new video is refused with too_many_waiting until one finishes. These numbers are the account's, shared by all its keys and the site, and GET /v1/me reports them in limits. Each key also has a limit of its own, max_in_flight (50), refused with too_many_in_flight.

Videos made through the API are never free videos and never carry the Ivan mark. On a team, videos are charged to the team's pool, and the team's limits apply.

The video object

Every video call answers with this object, or a list of them.

{
  "object": "video",
  "id": "vid_01J8ZQ3N4X7K2M",
  "status": "in_progress",
  "stage": "drawing",
  "progress": 0.4,
  "playable": true,
  "topic": "How vaccines train the immune system",
  "power": "eco",
  "look": "illustrated",
  "aspect": "16:9",
  "language": "en",
  "duration_seconds": null,
  "watch_url": "https://tryivan.com/?video=01J8ZQ3N4X7K2M",
  "share_url": null,
  "download_url": null,
  "download_expires_at": null,
  "credits": { "held": 1000, "charged": 0 },
  "music": {
    "title": "Investigations",
    "by": "Kevin MacLeod",
    "licence": "CC BY 4.0",
    "licence_url": "https://creativecommons.org/licenses/by/4.0/",
    "source": "https://incompetech.com/music/royalty-free/",
    "credit": "Music: “Investigations” by Kevin MacLeod (https://incompetech.com/music/royalty-free/), licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)"
  },
  "web_check": null,
  "error": null,
  "channel": "api",
  "metadata": { "order": "A-1" },
  "logo_corner": null,
  "brand": null,
  "created_at": 1790000000,
  "completed_at": null
}

id

vid_ and the video's own id.

status

queued, in_progress, completed, failed or canceled. The last three are final.

stage

While in_progress, what Ivan is doing now: checking the request, writing, drawing, voicing, rendering (from the moment the first scene is being made into film) or finishing the final cut; or reviewing while its charge is checked. It only moves forward. Otherwise null.

progress

How far along the video is, from 0 to 1, to two decimals: each step’s share of a typical video’s making time, by the scenes it has finished and the ones it has underway. It moves steadily while the video is made, never goes back, and reaches 1 only when the video is completed. If Ivan has to restart a video after an interruption, its status returns to queued and progress starts again from the scenes it saved. A step that takes longer than usual holds it still rather than running it ahead.

playable

Whether its first scenes can already be watched at watch_url.

topic

A short label for the video, drawn from its prompt.

power, look, aspect, language

What it was made with. look is illustrated, flat, doodle or board.

duration_seconds

The delivered length it was charged for, once settled; null before.

watch_url

Where the account's owner watches and edits it, signed in. It is private to the account. It is null for a video made with a team's own key, which no one signs in to: share the video, or use its files.

share_url

Its public page while it is shared, otherwise null.

download_url, download_expires_at

Where one completed video is read (GET /v1/videos/{id}, waited for or not), a link to its film (MP4) that needs no key, and when the link stops working, in Unix seconds: an hour on. Use it where a key cannot be sent, such as a chat app that fetches a file or a tool that uploads one. Anyone holding the link can open the film until then, so hand it only to whoever the video is for. Revoking the key ends its links at once, as does disconnecting an app or connecting it again. Every read gives a new link. Both are null until the video is completed, in a list and in the answer to a create or a cancel, and for an app connected by sign-in with public links switched off.

credits

held for work still running and charged for finished work.

music

The music under the narration and its licence, or null for a video without music. Wherever you publish the video, publish credit with it: the music is licensed on that condition. The video's file carries the same line in its metadata.

web_check

For a prompt about something recent, the quick check of the web Ivan made before writing, as {"checked_at", "sources"}: when, in Unix seconds, and the pages its facts came from, each {"title", "site", "url"}. null for every other video, and until the check has found facts. A prompt that needs more than a quick check is refused with research_needed.

error

Why it failed, as {"code", "message"}, or null. Codes: generation_failed, at_capacity, drawing_failed, voice_failed, render_failed, interrupted, canceled, source_unreadable and internal_error.

channel

api; mcp: and the agent's name for a video made through the MCP server; or studio for a video made on the site.

metadata

Your own labels, as you sent them.

logo_corner

The corner its logo sits in, or null for a video without one.

brand

The brand colours it is dressed in, as {"page", "ink", "accent", "desk"}, each #RRGGBB; or null for a video made without them.

created_at, completed_at

Unix seconds. completed_at is null until it is completed.

Endpoints

Paths are relative to https://api.tryivan.com. Bodies are JSON, up to 64 KiB. A field an endpoint does not take is refused, never ignored, so a misspelt option never silently does nothing.

{
  "object": "estimate",
  "max_credits": 1000,
  "credits_per_minute": 200,
  "longest_seconds": 300,
  "available_credits": 12000,
  "key_remaining_credits": 49000,
  "can_start": true,
  "refusal": null
}

{ "object": "list", "data": [ { "object": "video", … } ], "has_more": true }

{ "object": "video", "id": "vid_01J8ZQ3N4X7K2M", "deleted": true }

{
  "object": "share",
  "video_id": "vid_01J8ZQ3N4X7K2M",
  "shared": true,
  "url": "https://tryivan.com/f/…",
  "embed_url": "https://tryivan.com/f/…/embed",
  "shared_at": 1790000400
}

{
  "object": "account",
  "id": "…",
  "key": {
    "id": "key_…", "name": "Support bot", "hint": "ivan_sk_live_…a1B2", "mode": "live",
    "scopes": ["usage:read", "videos:create", "videos:read"],
    "monthly_cap": 50000, "max_in_flight": 50,
    "committed_this_month": 1000, "remaining_this_month": 49000, "in_flight": 1
  },
  "limits": { "videos_at_once": 3, "videos_in_progress": 23, "making": 1, "waiting": 0 },
  "credits": { "available": 12000 }
}

Rate limits

Each key may send bursts of up to 120 requests, then about 10 a second, and all of an account's keys together up to 300, then about 20 a second. Creates and estimates together are limited to 30 a minute for each key, and 60 a minute across all of an account's keys. A held wait_seconds call counts once, and an account may hold 24 at a time; past that, or while Ivan holds as many waits as it can, a wait is answered at once with Retry-After: 5, and the next one should come after it. An account may download 6 films at a time, each for up to 30 minutes; while Ivan sends as many films as it can, a download is refused with unavailable and Retry-After.

Requests with a missing or invalid key count against the address they come from; after about 120 in quick succession, that address is refused for a minute, except for a key that worked from it in the last 10 minutes. An account may make 10 keys an hour.

A refusal over a limit is 429 with a Retry-After header in seconds; so is every 503. The same number is in the body as retry_after. Wait at least that long before trying again, adding a little random delay when many workers share a key.

Errors

Every error is a problem document (RFC 9457), served as application/problem+json. Branch on code, which never changes; detail is a sentence for people. param names the field at fault, and refusals over money carry credits_needed and credits_available.

{
  "type": "https://tryivan.com/docs/api#error-insufficient_credits",
  "title": "Payment Required",
  "status": 402,
  "detail": "This video may hold up to 1000 credits; the account has 200 available. Add credits at https://tryivan.com.",
  "code": "insufficient_credits",
  "request_id": "0f6c…",
  "credits_needed": 1000,
  "credits_available": 200
}