apimodels

apimodels-mcp

适用于 apimodels.app 的 MCP 服务——只需一个 API 密钥，即可在 Claude Desktop、Cursor 或任何 MCP 客户端中调用图像、视频、大模型聊天和文本转语音模型。

一个密钥即可使用 GPT-6.1、Claude、Gemini、GLM、DeepSeek、Qwen、Seedance、Veo、Kling、gpt-image-2、Gemini Image、MiniMax speech 等更多服务——以 USD 计费，仅对成功生成的内容收费。

最快的设置方式：Codex / Claude Code 插件

编码 Agent 擅长规划——脚本、镜头列表、提示词，以及用 ffmpeg 编辑。apimodels 插件为它们补上无法完成的部分：渲染视频、图像和配音。插件捆绑了此 MCP 服务，以及一项教 Agent 何时使用它、如何选择模型、如何等待长时间渲染，以及何时在花费前征求确认的技能。

1. 登录一次（需要 Node.js 18 或更高版本）：

   npx -y apimodels-mcp login
   

   浏览器会打开 apimodels.app；点击 Authorize。系统会为此设备创建一个名为 CLI · <date> 的密钥，并将其保存到 ~/.apimodels/credentials.json，所有客户端都能在其中找到该密钥——包括无法读取 shell 环境变量的桌面应用。无需复制或粘贴，Agent 也可以替你完成此步骤。在没有浏览器的设备上，使用 --no-browser（打印链接）或 --paste（粘贴来自 https://apimodels.app/console/api-keys 的密钥）。
2. 安装插件。
   • Claude Code（2.1.275 或更高版本）：

     /plugin install apimodels --marketplace stimQQ/apimodels-mcp
     

     较旧版本：先运行 /plugin marketplace add stimQQ/apimodels-mcp，再运行 /plugin install apimodels@apimodels。
   • Codex：

     codex plugin marketplace add stimQQ/apimodels-mcp
     codex plugin add apimodels@apimodels
     

     只有 Codex 桌面应用，没有 codex 命令？使用 npx -y @openai/codex 代替 codex——它会即时运行官方 CLI，并共用桌面应用的配置。 然后重启 Codex。对于会消耗额度的每次调用（generate_video、generate_image、text_to_speech、chat、review_image），Codex 都会请求你批准；查看进度、模型列表和余额则无需批准。
3. 用日常语言提出请求，例如 “制作一个 5 秒、16:9 的视频，画面中一只小猫在晨光中慢慢抬起头”，或 “为这个代码库规划一段 20 秒的产品视频，并逐镜头渲染”。

还没有 Node.js？照常安装插件并请求制作视频：技能会让 Agent 检查是否安装了 Node.js，并在获得你的许可后，替你安装官方 LTS 版本（Windows 上使用 winget，macOS 上使用 Apple 安装器）。

托管服务：无需 Node.js，通过 OAuth 登录

相同的工具也运行在 https://api.apimodels.app/mcp（Streamable HTTP）上。无需安装或复制密钥：将 URL 添加到客户端，然后按提示登录 apimodels.app 并点击 Authorize。获取到的访问令牌是一个专用 API 密钥，名称为 MCP · <app> · <date>；在控制台删除该密钥即可断开连接。

• Codex——将以下内容添加到 ~/.codex/config.toml，然后运行 codex mcp login apimodels：

  [mcp_servers.apimodels]
  url = "https://api.apimodels.app/mcp"
  

• Claude Code——运行 claude mcp add --transport http apimodels https://api.apimodels.app/mcp，然后选择 /mcp → apimodels → Authenticate。
• ChatGPT、Claude.ai、Cursor 和其他支持远程 MCP URL 的客户端——使用此 URL 将其添加为自定义连接器，并按提示登录。

与本地服务的区别：托管服务无法读取你设备上的文件——Agent 会调用 get_upload_url，使用 curl -T 上传文件，并传入返回的 URL（如果传入本地路径，会拒绝并给出此提示）；每次调用最多等待 50 秒，之后会返回一个供 get_task 使用的任务 ID。如果使用普通 API 密钥登录，请将其作为 Authorization: Bearer sk_… 发送。

工具

工具	功能
get_balance	你的 apimodels USD 余额——Agent 会在批量处理前检查余额。
list_models	列出可用的模型 ID（聊天 / 图像 / 视频 / 音频）。
chat	使用任意大模型进行聊天 / 文本补全（gpt-6.1-sol、claude-opus-5-5、gemini-3-pro-preview 等）。
generate_image	文本生成图像或编辑图像；返回图像 URL，以及一张可供模型查看的缩小预览。使用 doubao-seedream-5-0-flash 时，还可以保留透明背景（background: "transparent"），或将一张图像拆分为一个底图和最多 16 个带名称与位置的透明图层（layer_decomposition: true，按输出图像计费）。
review_image	视觉模型根据你的要求点评图像，并提出修改后的提示词。
generate_video	文本生成视频（可选参考图像）；返回视频 URL，若在 wait_seconds 内未完成，则返回任务 ID。
get_task	等待 / 检查 generate_image、generate_video 或 text_to_speech 返回的仍在运行的任务。
get_upload_url	仅限托管服务：提供一个有效期为 15 分钟的链接，可用 curl -T 上传本地文件；返回其公开 URL。
text_to_speech	文本转语音（MiniMax 音色）；返回音频 URL。此处不提供 ElevenLabs TTS——它会通过 POST /v1/tts/stream 流式传输原始字节，而不是返回 URL。

长时间生成不会丢失

apimodels 上的所有生成任务都是异步的，而且视频生成很慢：中位耗时约 2.5 分钟，10 个任务中有 9 个会在 8 分钟内完成（生产环境数据，统计截至 2026-09-22 当周）。图像生成约需 50 秒。同时，Codex 默认会在 60 秒后中止 MCP 工具调用，MCP SDK 自带的客户端超时也为 60 秒。因此，阻塞至视频就绪的工具会在等待过程中被终止——任务仍会继续运行，完成后会向账户收费，而助手永远看不到 URL。0.2.x 及之前的版本正是如此。

从 0.3.0 开始，生成工具最多等待 wait_seconds（默认值为 50），然后返回任务 ID，并注明“仍在运行”；随后助手会调用 get_task，再等待最多 wait_seconds，并返回 URL（图像任务还会附带图像预览），若任务仍在运行则再次注明“仍在运行”。不会重新提交任务，也不会重复收费。这一过程由助手自动完成；你只需提出生成视频的请求。

• Codex：保持默认设置即可。也可以在 config.toml 中提高此服务的 tool_timeout_sec，并传入更大的 wait_seconds。
• Claude Code / Claude Desktop / Cursor：没有 60 秒限制，因此在 generate_video 中设置 wait_seconds: 600，一次调用即可获取 URL。在服务的环境变量中设置 APIMODELS_WAIT_SECONDS=600，即可将其设为默认值。

模型可以检查自己的成果

要求生成图像，并让助手反复调整，直到效果满意——“制作一张写有 SAVE 10% 的 16:9 横幅，检查拼写，有需要就修正”：

1. generate_image 会返回 URL 和图像本身的预览（最大 1024px 的 JPEG）。能够将工具结果图像传给模型的客户端——Claude Desktop、Claude Code、Cursor——可以让模型看到生成的内容。传入 return_image: false 可跳过预览。
2. review_image 在所有客户端中都可用，包括那些会向你展示工具结果图像、但不会展示给模型的客户端（Cherry Studio 就是其中之一）。它会将图像和你的要求发送给视觉模型，并返回符合要求的内容、有问题的内容（乱码、构图、宽高比、瑕疵）以及修改后的提示词。使用默认模型 gpt-5.6-luna 进行一次审查的成本远低于 $0.01。

助手会根据你的要求自行选择 aspect_ratio 和 resolution，因此用普通语言说“制作成 16:9”就足够了。

本地图片可直接使用

generate_image 和 generate_video 中的 image_url 支持以下任意内容：

• 公共 https://… URL — 原样传递
• 本地文件路径 — /Users/me/photo.png、./ref.jpg、~/Pictures/x.webp
• 你自己机器上的 URL — http://127.0.0.1:8000/photo.png、http://localhost:3000/…
• data:image/png;base64,… URI

最后三种内容会先为你上传，然后使用生成的公共 URL 进行生成。这一步必须在此处而非服务端完成：文件只存在于你的机器上，而我们的服务解析 127.0.0.1 时，它指的是 我们的 服务——因此直接将其传给 REST API 会因 private/reserved IP addresses not allowed 而失败。这个 MCP 服务与你的文件位于同一台机器上，因此它能做我们的服务无法做到的事。

上传的文件会存放在你账户的 R2 空间中，并在 30 天后自动删除。

设置

1. 运行 npx -y apimodels-mcp login，然后在浏览器中点击 Authorize；或者在 https://apimodels.app/console/api-keys 创建密钥（格式类似 sk_…），并将其作为 APIMODELS_API_KEY 放入服务的环境变量中，如下方示例所示。
2. 将服务添加到你的 MCP 客户端。运行 npx -y apimodels-mcp status 可查看当前使用的密钥和账户余额。

Claude Desktop

编辑 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "apimodels": {
      "command": "npx",
      "args": ["-y", "apimodels-mcp"],
      "env": {
        "APIMODELS_API_KEY": "sk_your_key_here"
      }
    }
  }
}

重启 Claude Desktop。现在你可以让它“生成一张……的图片”或“制作一段 5 秒的……视频”。

Cursor

进入 Settings → MCP → Add new MCP server，或将其添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "apimodels": {
      "command": "npx",
      "args": ["-y", "apimodels-mcp"],
      "env": { "APIMODELS_API_KEY": "sk_your_key_here" }
    }
  }
}

Codex CLI

将其添加到 ~/.codex/config.toml：

[mcp_servers.apimodels]
command = "npx"
args = ["-y", "apimodels-mcp"]
env = { APIMODELS_API_KEY = "sk_your_key_here" }
# Optional. Codex aborts a tool call after 60 s by default; the tools stay under that
# on their own (see "Long generations do not get lost"), so this is only needed if you
# want generate_video to return the URL in one call — then also pass wait_seconds: 600.
# tool_timeout_sec = 660

在 Codex 中有两点需要了解：

• 审批。 Codex 会要求你批准任何未标记为只读的工具调用。从 0.4.3 开始，list_models 和 get_task 已标记为只读，因此等待视频完成时，不再会在每次检查时都弹出提示；会产生账户费用的工具（generate_video、generate_image、text_to_speech、chat、review_image）仍会在每次调用时请求一次批准。若要跳过这些提示，也可在 [mcp_servers.apimodels] 下添加 default_tools_approval_mode = "approve"。
• 指定工具名称。 Codex 会按需加载 MCP 工具，而不是一开始就列出所有工具，因此请说明你要使用哪一个——例如 “使用 apimodels generate_video 制作一段 5 秒、16:9 的……视频片段。” 只说“给我做个视频”可能不会让它找到合适的工具。

Cherry Studio

在 Settings → MCP Servers 中，添加一个 stdio 类型的新服务：

• Command：npx
• Arguments：-y apimodels-mcp
• Environment variables：APIMODELS_API_KEY=sk_your_key_here

启用服务，然后通过聊天框下方的 MCP 控件，在对话中选择该服务。将支持工具调用的聊天模型（Claude、GPT、Gemini …）设为对话模型——它会为你调用图片模型。Cherry Studio 需要安装 Node.js 才能使用 npx；在 Windows 上，请从 https://nodejs.org 安装。

其他 MCP 客户端的用法也相同——通过 stdio 运行 npx -y apimodels-mcp，并在环境变量中设置 APIMODELS_API_KEY。

模型、文档和定价

工具调用的所有内容均记录在 apimodels.app 上：

• API 文档 · 定价 · 完整模型目录
• 图像：GPT Image 2.5 API（模型页面）、GPT Image 2 API、Nano Banana 2.1 API（模型页面）、所有图像模型
• 视频：Seedance 2.5 API、Google Veo API、MiniMax H3 API、FlashVSR 视频超分辨率
• 聊天和语音：LLM API（GPT、Claude、Gemini、DeepSeek、GLM、Qwen）、Claude Sonnet 5.5、音频和文本转语音
• 其他接入方式：Claude Code 设置、聊天客户端、Agent Skills、免费计算器和工具
• 提供示例输出的提示词库：GPT Image 2.5 提示词、GPT Image 2 提示词、Seedance 2.5 提示词、MiniMax H3 提示词

配置

环境变量	默认值	描述
APIMODELS_API_KEY	—	您的 sk_… 密钥。运行过 apimodels-mcp login 后可选；如果两者都存在，则优先使用此项。
APIMODELS_CREDENTIALS_FILE	~/.apimodels/credentials.json	apimodels-mcp login 保存密钥的位置，也是服务查找密钥的位置。
APIMODELS_BASE_URL	https://api.apimodels.app/v1	API 基础 URL。
APIMODELS_WAIT_SECONDS	50	generate_image、generate_video、text_to_speech 和 get_task 的默认 wait_seconds：调用等待多久后返回任务 ID。最长 900 秒。
APIMODELS_TIMEOUT_MS	—	已弃用（0.2.x）：相同的等待时长，以毫秒为单位。设置后仍会生效。

本地开发

pnpm install
pnpm build
APIMODELS_API_KEY=sk_... node dist/index.js   # runs over stdio

许可证

MIT