
i2v.ai 面向 Agent 的媒体 API 上线:CLI、TypeScript SDK、远程 MCP 与 Skill
i2v.ai 开发者生态今天上线:npm 上的 CLI 与 TypeScript SDK、带读写分离 OAuth 权限的远程 MCP、两个 Agent Skill,以及可直接运行的后端与工作流示例。本文说明每个入口的用途,以及十分钟上手路径。
要点
i2v.ai 现在通过五个入口开放同一套媒体生成能力,它们共用一份模型目录、一个美元钱包和同一套安全模型:
- CLI —— npm 上的
@i2v-ai/cli1.2.1。列出模型、按输入报价、带美元上限提交,并能在中断后找回任务。 - TypeScript SDK ——
@i2v-ai/sdk0.1.2,包含"响应丢失但提交已受理"的类型化恢复。 - 远程 MCP ——
https://i2v.ai/api/mcp,13 个工具,OAuth 读写权限分离。 - Agent Skill ——
i2v-models与i2v-integrate,把完整流程教给编程 Agent。 - 示例 —— Bash、Python、TypeScript、Next.js、n8n、Make 和 Zapier。
所有付费路径都是先报价:任务创建之前,你就能看到这次调用的美元预留上限。
为什么要有开发者入口
大多数人通过 Studio 使用 i2v.ai。开发者需要另一套保证:可预测的支出、自己持有的任务 ID、网络中断后的恢复能力,以及能融入现有工具链的接入方式。
API 此前已经存在。这次补上的是外围设施:可分发的客户端、机器可读的文档,以及让 AI 助手不必人工复制请求体就能直接使用的插件形态。
本次上线的内容
| 入口 | 版本 | 安装或连接方式 | 适合场景 |
|---|---|---|---|
| CLI | 1.2.1 | npm i -g @i2v-ai/cli 或 npx --yes @i2v-ai/cli | 终端脚本、本地素材、快速检查 |
| TypeScript SDK | 0.1.2 | npm i @i2v-ai/sdk | 需要类型化错误的服务端代码 |
| 远程 MCP | 1.1.0 | https://i2v.ai/api/mcp | ChatGPT、Codex、Claude、Cursor、VS Code、Copilot、Gemini CLI |
| Skill | i2v-models 1.2.1、i2v-integrate 1.0.0 | npx skills add https://i2v.ai | 让 Agent 按你的流程工作 |
| 示例 | main | github.com/i2v-ai/i2v-api-examples | 后端、n8n、Make、Zapier |
这些入口背后的公开目录包含 12 个图像模型和 16 个视频模型,覆盖 GPT Image 2、Seedream、Kling、Seedance、Wan 与 Veo。定价以美元计价,不用积分。
十分钟上手
先不配置密钥,直接看目录:
npx --yes @i2v-ai/cli list --type image --json
npx --yes @i2v-ai/cli price gpt-image-2list、doc 和 price 只读公开目录,不接触你的账户。准备真正提交时,把密钥放在发起请求的那台机器上:
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 会校验参数,并返回当前账户的报价和模型修订号。只在你能接受的上限内提交:
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.png等待过程中如果遇到 HTTP 429、502、503 或 504,status --wait 会在同一等待期限内遵守 Retry-After,继续查询同一个任务,而不是另起一个。
在 TypeScript 中,SDK 封装的是同一套契约:
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:AI 助手的接入路径
远程服务在 https://i2v.ai/api/mcp 提供 Streamable HTTP。客户端通过标准 OAuth 元数据发现它,授权流程把读和写分开:
mcp:read—— 发现模型、读取参数、按输入报价、查询余额与用量、跟踪自己的任务。mcp:write—— 创建任务、上传参考图。付费任务会预留并消耗你的美元余额。
默认先给读权限。写权限需要单独二次同意,之后可以在站点上撤销连接。REST 的 API Key 仍然可用,也可用于 MCP,但它始终同时具备读写权限;想让助手只拿到最小权限,就用 OAuth。
13 个工具覆盖完整闭环:目录与参数查询、报价与准备、上传、提交、任务状态、恢复、账户余额、用量和文档检索。每个工具都声明了自己是只读,还是会产生外部副作用。
目前有 14 个宿主提供接入指南,从 ChatGPT、Codex 到 Claude、Cursor、Copilot、VS Code 和 Gemini CLI。
Skill:把 Agent 教会你的流程
两个 Agent Skill 封装了最容易出错的部分:
i2v-models—— 目录发现、报价、安全提交和回执恢复,自带 CLI,Agent 不需要全局安装。i2v-integrate—— 后端与工作流接入:租户隔离、预算校验、签名回调和重放规则。
它们可以从官网或 GitHub 仓库安装,支持 Codex、Claude、Cursor、Copilot、Gemini CLI 等具备 Skill 能力的 Agent。
支出安全是 API 的一部分
媒体生成是价格浮动的付费动作,因此契约围绕三条规则设计:
- 先报价再提交。 报价返回这组输入的最大预留金额,以及你同意的模型修订号。
- 上限由你明确给出。 提交时传
maxCostUsd;报价高于上限时,任务不会创建,请求直接失败。 - 恢复优先于重放。 每次提交都带你的
Idempotency-Key。响应丢失时,用原幂等键查询回执,而不是重新发一次请求。回执会告诉你原操作是已受理、仍待受理、可重试,还是查不到。

Webhook 遵循同一套纪律:用时间戳和原始报文计算 HMAC 签名,携带事件 ID 用于去重,并在投递延迟时以同一任务的轮询作为兜底。
SDK 直接暴露这些状态:仍在受理中的提交返回 HTTP 409 时抛出 I2VSubmissionUnknownError,带上原幂等键和 Retry-After 元数据;明确的冲突则在 I2VHttpError 上给出原因。这个区别就是"小心重试"和"不要重试"的分界。
工作流与示例
示例仓库提供可运行代码而不是片段:图像与视频模型的 Bash、Python、TypeScript 示例,带模拟与真实模式的 Next.js 起步项目,以及可导入 n8n 的商品图与参考图视频模板。
每个示例都是先报价。n8n 模板默认 approved: false、凭据绑定为空,并要求美元上限,因此导入后不会悄悄开始扣费。
上线前的验证
这次发布是对着生产环境验收的,不只是本地夹具:26 份双语 MCP 指南的 HTML 与 Markdown、两个域名上的 OpenAPI 2.2.0、签名回执契约、OAuth 发现、12 个图像与 16 个视频模型的目录,以及一致的 Skill 归档。发布到 npm 的 CLI 与 SDK 归档与已审阅的产物逐字节一致。
从这里开始
如果你要把 i2v.ai 接进更特殊的场景——会丢响应的队列、多租户产品、需要硬预算的 Agent——回执与上限模型是我们最想听到反馈的部分。