# Ivan

> Ivan is the explainer video layer for AI. It turns a question, a deck, a PDF, notes or a script into a narrated, hand-drawn explainer video. People use it on the site; servers and AI agents use its API to ask for a video from a prompt, follow it while it is made, download its files and share it by link. Videos are paid for in credits (1,000 credits = $1), by the minute of what they deliver.

## Four ways in

- On the site, with a question: https://tryivan.com/create. A person types what they want explained and Ivan writes, draws and narrates it.
- On the site, with their own material: the same page takes up to 5 files (PDF, Word, PowerPoint, images, text or Markdown; PDFs up to 20 pages, decks up to 60 slides). Ivan explains from notes and slides, and follows an attached script closely.
- Through the API, from an agent or a product: a prompt in, a film out. The API takes a prompt only; files are attached on the site.
- As tools inside an AI agent, through Ivan's MCP server: no code to write. Claude, ChatGPT and Grok connect by signing in; other agents use the same key.

Ivan is invite-only for now: making a video, or an API key, needs an account.

## The API

- API base: https://api.tryivan.com/v1 (answers only /v1, and only to a secret key)
- Authentication: `Authorization: Bearer ivan_sk_live_…`. Keep the key on a server; never put it in a web page.
- Every error is application/problem+json with a stable `code`. Branch on `code`, not on `detail`.

## The MCP server

- URL: https://mcp.tryivan.com/mcp (Streamable HTTP; tools are called with POST /mcp)
- Claude, ChatGPT and Grok: add that URL as a custom connector. The person signs in on tryivan.com and presses Allow, setting a monthly limit ($10 by default) and a limit for one video ($3). Public links are off unless they switch them on, so give them `watch_url`. No key, client ID or secret is needed.
- Every other agent: the same header as the API, `Authorization: Bearer ivan_sk_live_…`.
- 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, VS Code and other clients: the URL and that header in the client's MCP settings; the [API guide](https://tryivan.com/docs/api#mcp) shows each.
- Tools: estimate_video, create_video, wait_for_video, get_video, list_videos, cancel_video, share_video, get_account. Each answers with the same JSON as its API call, and a refusal carries the same `code`.
- To make a video: create_video, then wait_for_video until `status` is `completed`, then give the user `watch_url`, or call share_video for a public link.
- A completed video from wait_for_video or get_video carries `download_url` (a list does not): its MP4 at a link that needs no key and works for an hour (`download_expires_at`). Where you can upload or attach a file, as in Slack or another chat app, fetch it and post the video itself so it plays where the user is. Give the link only to the user who asked. Read the video again for a new one. It is null for an app connected by sign-in with public links off. If share_video answers `insufficient_scope`, public links are off for this connection: give `watch_url`.

## Docs

- [API guide](https://tryivan.com/docs/api): quickstart, keys and scopes, idempotency, credits and limits, the video object, every endpoint, rate limits and every error code
- [OpenAPI 3.1](https://tryivan.com/docs/api/openapi.json): the whole contract, machine-readable
- [Pricing](https://tryivan.com/pricing): the rate for each power, what is charged and what is free
- [API keys](https://tryivan.com/?account=keys): a person signs in, opens Account, and makes a key under API keys. The key is shown once. A team's admins make the team's own keys in the team console (https://tryivan.com/team#keys).

## The four calls

1. Make a video. Send a new Idempotency-Key with each new video, and the same one to repeat a request whose outcome you did not see; a repeat never makes a second video.
   `POST https://api.tryivan.com/v1/videos` with headers `Idempotency-Key: <uuid>`, `Content-Type: application/json` and body `{"prompt": "How do vaccines train the immune system?", "max_credits": 1000}`. The answer is 202 with a video object whose `id` starts with `vid_`.
2. Wait for it. `GET https://api.tryivan.com/v1/videos/{id}?wait_seconds=25`, repeated until `status` is `completed`, `failed` or `canceled`. Each call returns as soon as the video reaches a new stage or moves a tenth further along, or after 25 seconds. `progress` (0 to 1) moves steadily and never goes back, except that a video Ivan restarts after an interruption returns to `queued` and starts again from the scenes it saved; `stage` says what Ivan is doing: checking, writing, drawing, voicing, rendering, finishing.
3. Fetch it. `GET https://api.tryivan.com/v1/videos/{id}/content` streams the MP4. Where a key cannot be sent, the `download_url` of a completed video read at `GET /v1/videos/{id}` is the same film at a link that works for an hour without one. Add `?variant=captions`, `transcript` or `poster` for the WebVTT captions, the plain-text transcript or a PNG poster.
4. Share it. `POST https://api.tryivan.com/v1/videos/{id}/share` returns a public `url` anyone can watch, and an `embed_url` for a player.

## Good to know

- Optional create fields: `power` (eco, max), `look` (illustrated, flat, doodle, board), `language` (such as en, hi, es), `aspect` (16:9, 9:16), `narrator` (male, female), `motion` (false keeps drawings still), `max_credits`, `metadata`.
- A team's key can put a company's logo in a corner of every frame, at no charge: add `logo_url` (a public link to a PNG or JPG file under 2 MB) and, to choose the corner, `logo_corner` (bottom_right by default, bottom_left, top_right, top_left). Send the same logo with every video of one company or workspace. Any other key is refused with `permission_denied`.
- A team's key can also dress a video in a company's brand colours, at no charge: add `brand`, such as `{"colors": ["#283C8B", "#1AA06B"]}` (one to three colours as #RRGGBB, the main one first; optionally `page`: light, white or a pale #RRGGBB, and `ink` and `accent`). The page stays pale so every drawing reads; colours that would not read are fixed, and `POST /v1/videos/estimate` returns the colours the video will use. Illustrated and flat looks only. Each video takes its own brand, so an agent working for several companies sends each one's colours and logo with its videos.
- Price: eco 200 credits a minute ($0.20), max 400 ($0.40), charged for the length delivered. A video that fails is not charged. Cancelling is free until the first scene can be watched; after that the scenes already made are charged.
- Ivan checks a fact or two on the web when a prompt is about something recent, and a video's `web_check` names the pages. It is not a research tool: a prompt that needs real research is refused with 422 `research_needed`. Research it, then send the prompt again with your findings written into it (text or links), and Ivan will explain them.
- A video is private until it is shared.
- `POST /v1/videos/estimate` prices a video without making it. `GET /v1/me` names the key and, with the usage:read scope, what it can spend.
- On 429 and 503, wait for the Retry-After header, then repeat; repeat a create with the same Idempotency-Key.
- A key has scopes (videos:read, videos:create, videos:share, usage:read), a monthly credit cap and a limit of videos in progress.
- An account makes 3 videos at once (6 from $50 bought, 12 from $500); more still start while Ivan has machines to spare (it keeps a couple free for others), and up to 20 more may wait. `GET /v1/me` reports these in `limits`; past them a create answers 429 `too_many_waiting`.