
i2v.ai Is Now an Agent-Ready Media API: CLI, TypeScript SDK, Remote MCP and Skills
The i2v.ai developer ecosystem ships today: an npm CLI and TypeScript SDK, a remote MCP server with read/write OAuth scopes, two Agent Skills, and runnable examples for backends and workflow tools. Here is what each surface is for and how to start in ten minutes.
TL;DR
i2v.ai now exposes the same media generation stack through five surfaces that share one catalog, one wallet, and one safety model:
- CLI —
@i2v-ai/cli1.2.1 on npm. List models, quote inputs in USD, submit with a hard ceiling, and recover an interrupted task. - TypeScript SDK —
@i2v-ai/sdk0.1.2, including typed recovery for a submission whose response was lost. - Remote MCP —
https://i2v.ai/api/mcp, 13 tools, OAuth with separate read and write scopes. - Agent Skills —
i2v-modelsandi2v-integrateteach coding agents the workflow end to end. - Examples — Bash, Python, TypeScript, Next.js, n8n, Make and Zapier.
Every paid path is quote-first: you see the maximum USD reservation before any task exists.
Why a developer surface at all
Most people reach i2v.ai through the studio. Builders need a different set of guarantees: predictable spend, a task ID they own, recovery when a network hop fails, and an integration that fits the tools they already run.
The API existed before today. What shipped now is the scaffolding around it: distributable clients, machine-discoverable documentation, and a plugin surface that AI assistants can use without a human copying payloads between tabs.
What shipped
| Surface | Version | Install or connect | Best for |
|---|---|---|---|
| CLI | 1.2.1 | npm i -g @i2v-ai/cli or npx --yes @i2v-ai/cli | Shell scripts, local files, quick checks |
| TypeScript SDK | 0.1.2 | npm i @i2v-ai/sdk | Server code that needs typed errors |
| Remote MCP | 1.1.0 | https://i2v.ai/api/mcp | ChatGPT, Codex, Claude, Cursor, VS Code, Copilot, Gemini CLI |
| Skills | i2v-models 1.2.1, i2v-integrate 1.0.0 | npx skills add https://i2v.ai | Teaching an agent your specific workflow |
| Examples | main | github.com/i2v-ai/i2v-api-examples | Backends, n8n, Make, Zapier |
The public catalog behind all of them lists 12 image models and 16 video models, including GPT Image 2, Seedream, Kling, Seedance, Wan and Veo. Pricing is quoted in USD, not credits.
The ten-minute path
Install the CLI and look around without an API key:
npx --yes @i2v-ai/cli list --type image --json
npx --yes @i2v-ai/cli price gpt-image-2list, doc and price read the public catalog and never touch your account. When you are ready to spend, keep the key on the machine that submits:
export I2V_API_KEY="YOUR_API_KEY"
npx --yes @i2v-ai/cli plan gpt-image-2 --input '{"prompt":"A ceramic mug on an oak table"}'plan validates the inputs and returns the account-specific quote plus the model revision. Submit only with a ceiling you approve:
npx --yes @i2v-ai/cli run gpt-image-2 \
--input '{"prompt":"A ceramic mug on an oak table"}' \
--max-cost-usd 0.20
npx --yes @i2v-ai/cli status TASK_ID --wait 120 --out ./mug.pngIf the wait runs into HTTP 429, 502, 503 or 504, status --wait honors Retry-After inside the same deadline and keeps polling the same task instead of starting a new one.
From TypeScript, the SDK wraps the same contract:
import { I2VClient } from '@i2v-ai/sdk';
const client = new I2VClient({ apiKey: process.env.I2V_API_KEY });
const models = await client.listModels();
console.log(models.data.length);MCP: the assistant route
The remote server speaks Streamable HTTP at https://i2v.ai/api/mcp. Clients discover it through standard OAuth metadata, and the authorization flow separates reading from writing:
mcp:read— discover models, read parameters, quote inputs, check balance and usage, track your own tasks.mcp:write— create tasks and upload reference images. Paid tasks reserve and consume your USD balance.
Read is what you get first. Write requires an explicit second consent, and you can revoke a connection from the site afterwards. API keys still work for REST and for MCP, but they always carry both permissions; OAuth is the way to hand an assistant the minimum it needs.
Thirteen tools cover the loop: catalog and parameter lookup, quoting and preparation, uploads, submission, task status, recovery, account balance, usage, and documentation search. Each tool declares whether it is read-only or produces an external side effect.
Fourteen hosts have setup guides today, from ChatGPT and Codex to Claude, Cursor, Copilot, VS Code and Gemini CLI.
Skills: teach the agent your workflow
Two Agent Skills encode the parts that are easy to get wrong:
i2v-models— discovery, quoting, safe submission, and receipt recovery, with a bundled CLI so the agent does not need a global install.i2v-integrate— backend and workflow integration: tenancy, budget checks, signed webhooks, and replay rules.
They install from the website or the GitHub repository and work in Codex, Claude, Cursor, Copilot, Gemini CLI and other Skill-aware agents.
Spending safety is part of the API
Media generation is a paid action with a variable price, so the contract is built around three rules:
- Quote before submit. A quote returns the maximum reservation for those exact inputs and the model revision you are agreeing to.
- Ceilings are explicit. Submission takes
maxCostUsd; if the quote exceeds it, the request fails before a task exists. - Recovery beats replay. Every submission carries your
Idempotency-Key. If the response is lost, look the receipt up with the original key instead of re-sending the request. A receipt tells you whether the original operation was accepted, still pending, retryable, or missing.

Webhooks follow the same discipline: signed with an HMAC over the timestamp and the raw body, carrying an event ID for deduplication, with polling on the same task as the fallback when delivery is late.
The SDK surfaces this directly. A pending submission that returns HTTP 409 raises I2VSubmissionUnknownError with the original idempotency key and the Retry-After metadata, while a definitive conflict exposes a reason on I2VHttpError. That distinction is the difference between "retry carefully" and "do not retry".
Workflows and examples
The examples repository has runnable code rather than snippets: Bash, Python and TypeScript for image and video models, a Next.js starter with mock and live modes, and importable n8n templates for product images and reference-image videos.
Every example quotes first. The n8n templates ship with approved: false, an empty credential binding, and a USD ceiling, so importing one cannot quietly start spending.
What we verified before shipping
The release was checked against production, not just fixtures: 26 bilingual MCP guides rendered in HTML and Markdown, OpenAPI 2.2.0 on both i2v.ai and api.i2v.ai, the signed webhook contract, OAuth discovery, the 12 image and 16 video model catalog, and matching Skill archives. The CLI and SDK archives published to npm were byte-identical to the reviewed artifacts.
Start here
- CLI and Skills
- MCP setup and client guides
- Integration guide
- npm: @i2v-ai/cli and @i2v-ai/sdk
- Examples and the i2v.ai organization
If you are wiring i2v.ai into something unusual — a queue that loses responses, a multi-tenant product, an agent that needs a hard budget — the receipt and ceiling model is what we want feedback on.