apimodels-mcp 是一个 MCP 服务器:装上之后,你的 AI 客户端就多了一组调用我们图片、视频、对话、语音模型的工具,用的还是你现有的那把 key。你描述想要什么,助手自己写提示词、生成、看结果、再改提示词重出 —— 不用离开聊天窗口,也不用记模型名。
Codex、Claude Code 这类编码智能体擅长规划:写脚本、拆分镜、写提示词、用 ffmpeg 剪辑。apimodels 插件补上它们做不了的那一步 —— 把视频、图片、配音真正生成出来。插件 = 这个 MCP 服务器 + 一份技能说明,告诉智能体什么时候用、怎么选模型、视频要等多久、什么时候该先问你再花钱。装好后直接用大白话提需求,不用点名工具。
浏览器会打开 apimodels.app,点「授权」即可:会为这台电脑新建一把专用 key 并存到本机,不用复制粘贴,Codex / Claude Code 等所有客户端都能读到。这一步也可以让智能体替你运行,你只需要点授权。
npx -y apimodels-mcp loginClaude Code(2.1.275+):
/plugin install apimodels --marketplace stimQQ/apimodels-mcpCodex(装完重启 Codex):
codex plugin marketplace add stimQQ/apimodels-mcp
codex plugin add apimodels@apimodels只装了 Codex 桌面版、终端里没有 codex 命令?把命令里的 codex 换成 npx -y @openai/codex,它会临时运行官方命令行,和桌面版共用同一份配置。
例如「做一段 5 秒 16:9 的视频:小猫在晨光里缓慢抬头」或「给这个项目规划一段 20 秒的产品视频,逐镜头生成出来」。会花钱的调用(生成视频、图片、语音)Codex 会先请你确认;查进度、查余额不会打扰你。
插件和 MCP 都需要本机有 Node.js。没装也没关系:装好插件后直接提需求,智能体会发现工具没加载,征得你同意后替你安装官方 Node.js(Windows 用系统自带的 winget,只需在弹窗点「是」;Mac 打开官方安装器点「继续」「安装」),之后重启智能体即可。
同一组工具也跑在我们的服务器上。把下面这个地址加进客户端,它会让你登录 apimodels.app 并点「授权」,之后就能用 —— 不用装 Node.js,也不用复制 key。授权会为该应用新建一把名为「MCP · 应用名 · 日期」的专用 key,要断开就到控制台删掉它。
https://api.apimodels.app/mcp# ~/.codex/config.toml
[mcp_servers.apimodels]
url = "https://api.apimodels.app/mcp"
# then, in a terminal:
codex mcp login apimodelsclaude mcp add --transport http apimodels https://api.apimodels.app/mcp
# then in Claude Code: /mcp → apimodels → Authenticate{
"mcpServers": {
"apimodels": { "url": "https://api.apimodels.app/mcp" }
}
}写进 ~/.cursor/mcp.json,再到 Customize → MCPs 点 apimodels 旁的 Authenticate。一键安装按钮、每一步的截图和授权超时(8787 端口)的解决办法见 Cursor 图文教程。
在「连接器 / Connectors」或 MCP 设置里添加自定义连接器,填上面的地址,按提示登录并授权。
和本地版的两点区别:托管版读不到你电脑上的文件 —— 智能体会先调 get_upload_url,用 curl 把文件传上来再使用(直接给本机路径会收到这个提示);每次调用最多等 50 秒,视频没出来就交回任务号,再用 get_task 取。已经有 key 的话,也可以直接用请求头 Authorization: Bearer sk_… 连接。
不用插件、自己配置也可以。没有要下载的东西,它通过 npx 按需运行。先运行上面的 login 在浏览器里授权一次(之后下面配置里的 env 那一行可以省掉),或到 控制台 → API Keys 拿一把 sk_… key 填进去。
Settings → Developer → Edit Config,打开 claude_desktop_config.json 加入下面这段,然后重启。
{
"mcpServers": {
"apimodels": {
"command": "npx",
"args": ["-y", "apimodels-mcp"],
"env": {
"APIMODELS_API_KEY": "sk_your_key_here"
}
}
}
}写进 ~/.cursor/mcp.json(Customize → MCPs 里能看到它)。不想装 Node.js 的话用上面的托管版,图文教程在 /docs/cursor。
{
"mcpServers": {
"apimodels": {
"command": "npx",
"args": ["-y", "apimodels-mcp"],
"env": { "APIMODELS_API_KEY": "sk_your_key_here" }
}
}
}写进 ~/.codex/config.toml。Codex 默认 60 秒就会中止一次工具调用,这些工具自己会控制在这个时间内(见下面「长任务」);tool_timeout_sec 只在你想让 generate_video 一次调用就拿到 URL 时才需要。
[mcp_servers.apimodels]
command = "npx"
args = ["-y", "apimodels-mcp"]
env = { APIMODELS_API_KEY = "sk_your_key_here" }
# tool_timeout_sec = 660 # optional, see "Long generations" belowSettings → MCP Servers → 新建一个 stdio 类型的服务器,填下面三项。启用后在输入框下方的 MCP 控件里为当前对话选中它,并把对话模型换成支持函数调用的(Claude、GPT、Gemini 等)。
| Command | npx |
| Arguments | -y apimodels-mcp |
| Environment variables | APIMODELS_API_KEY=sk_your_key_here |
其它 MCP 客户端都一样:以 stdio 方式运行下面这条命令即可。
APIMODELS_API_KEY=sk_your_key_here npx -y apimodels-mcpnpx 需要本机装了 Node.js。Windows 用户到 nodejs.org 装一个即可,Cherry Studio 也依赖它来拉起 MCP 服务器。
| 工具 | 作用 |
|---|---|
| get_balance | 查账户余额(美元),智能体批量生成前先看一眼。 |
| list_models | 列出可用模型 id(对话 / 图片 / 视频 / 语音)。 |
| chat | 用任意 LLM 做对话或补全(gpt-5-5、claude-opus-4-8、gemini-3-pro-preview 等)。 |
| generate_image | 文生图或图片编辑;返回图片 URL,并附一张模型自己能看的缩略预览。 |
| review_image | 让视觉模型对照你的要求审图,返回「哪里对、哪里错、改后的提示词」。 |
| generate_video | 文生视频(可带参考图);在 wait_seconds 内做完就返回视频 URL,否则返回 task id。 |
| get_upload_url | 仅托管版:给一个 15 分钟有效的上传链接,智能体用 curl -T 把本地文件传上来,返回公开 URL。 |
| get_task | 等待或查询一个还在跑的任务(图片 / 视频 / 语音),返回结果 URL,图片任务附预览。 |
| text_to_speech | 文字转语音(MiniMax 音色);返回音频 URL。 |
ElevenLabs 的 TTS 不在这里:它从 POST /v1/tts/stream 直接流式返回音频字节,没有可回传的 URL,走 音频 API 调用。
你可以直接说「做一张 16:9 的横幅,上面写 SAVE 10%,检查拼写,错了就改」,然后让助手自己循环到满意为止。它靠两条路看结果,选哪条取决于你的客户端:
Claude Desktop、Claude Code、Cursor 会把工具返回的图片一并喂给模型,所以 generate_image 附带的那张预览(最长边 1024 的 JPEG)模型是真能看见的,它会照着自己改。不想要预览就传 return_image: false。
Cherry Studio(1.9.11 实测)把工具结果里的图片只渲染给用户,给模型的是一句文字占位 —— 模型其实看不见自己刚做的东西。这种情况用 review_image:它把图和你的要求送给视觉模型,回来的是文字版的「符合项 / 问题 / 修订后的提示词」,同样能闭环,且在任何客户端都成立。
审图默认用 gpt-5.6-luna,一次远低于 $0.01;要更严格的读图可以指定 claude-sonnet-5。对话模型本身只需要支持函数调用 —— Claude、GPT-5.x、gpt-6-astra、Gemini 都可以。比例和分辨率不用你填,助手会按你说的话自己定(说「16:9」就够了)。
generate_image 和 generate_video 的 image_url 收四种写法:公网 https:// 链接、本机文件路径(/Users/me/photo.png、./ref.jpg、~/Pictures/x.webp)、本机地址(http://127.0.0.1:8000/photo.png)、以及 data:image/png;base64,… 。
后三种由 MCP 服务器先替你上传,再拿公网 URL 去生成。这一步只能在你这边做:文件只存在于你的机器上,而 127.0.0.1 在我们服务器上解析出来是我们自己 —— 所以直接把本机路径丢给 REST 接口会被拒(private/reserved IP addresses not allowed)。上传的文件落在你账号的存储里,30 天后自动删除。
站上所有生成都是异步任务,而视频很慢:按我们生产数据(截至 2026-09-22 的一周),视频中位约 2.5 分钟、九成在 8 分钟内,图片约 50 秒。另一边,Codex 默认 60 秒就中止一次工具调用,MCP SDK 自带的客户端超时也是 60 秒。一个「阻塞到视频出来为止」的工具会在等待中途被杀:任务照常跑完并计费,助手却拿不到 URL —— 0.2.x 就是这样。
从 0.3.0 起,生成工具最多等 wait_seconds(默认 50 秒),没做完就交回 task id 和一句「还在跑」;助手接着调 get_task,它再等最多 wait_seconds,返回 URL(图片任务附预览)或再次「还在跑」。任务不会重复提交,也不会重复计费,这一切助手自己会做。Claude Code、Claude Desktop、Cursor 没有 60 秒限制,给 generate_video 传 wait_seconds: 600 就能一次拿到 URL;在环境变量里设 APIMODELS_WAIT_SECONDS=600 可以把它变成默认值。
| 变量 | 默认值 | 说明 |
|---|---|---|
| APIMODELS_API_KEY | 可选 | 你的 sk_… key。运行过 apimodels-mcp login 就不用设;两者都有时以它为准。 |
| APIMODELS_CREDENTIALS_FILE | ~/.apimodels/credentials.json | login 把 key 存在哪、服务器去哪读。 |
| APIMODELS_BASE_URL | https://api.apimodels.app/v1 | API 地址。 |
| APIMODELS_WAIT_SECONDS | 50 | generate_image / generate_video / text_to_speech / get_task 默认等多久再交回 task id(秒,最大 900)。 |
| APIMODELS_TIMEOUT_MS | — | 已弃用(0.2.x):同一个等待时长,单位毫秒;设了仍然生效。 |
| 症状 | 原因 / 修法 |
|---|---|
| 客户端里看不到这些工具 | 多半是 npx 跑不起来 —— 本机没装 Node.js,或客户端没继承到 PATH。先在终端手动跑一次上面那条 stdio 命令看有没有报错。 |
| 工具返回 No apimodels API key found | 还没登录。运行 npx -y apimodels-mcp login,在浏览器里点「授权」;不用重启客户端。智能体也可以替你运行这条命令。 |
| 模型说它看不到图 | 你的客户端属于「只把图给你看」那一类(如 Cherry Studio)。改用 review_image,或换 Claude Desktop / Cursor。 |
| 助手一直只聊天、不调用工具 | 对话模型不支持函数调用,或这次对话没启用该 MCP 服务器。换成 Claude / GPT-5.x / Gemini,并在输入框下方确认服务器是勾选状态。 |
| 视频等到一半,工具调用被客户端中止(Codex 常见) | 升级到 apimodels-mcp 0.3.0 以上:生成工具最多等 wait_seconds(默认 50 秒)就交回 task id,助手再用 get_task 取结果,任务不会丢也不会重复扣费。0.2.x 会一直阻塞到 5 分钟,被中止后 URL 就拿不到了(任务照常完成并计费,可到控制台「调用记录」找)。 |
| 提示 private/reserved IP addresses not allowed | 你把本机地址直接给了 REST 接口。经 MCP 的 image_url 传就没这个问题 —— 它会先替你上传。 |
可以。装上 apimodels-mcp 后直接用大白话提要求即可。在 Claude Desktop、Claude Code、Cursor 里,生成的图会一并交给模型,它能看见自己的作品并用修正后的提示词重出。在只把图给用户看的客户端(如 Cherry Studio),用 review_image 走文字版闭环:把图和你的要求送给视觉模型,返回问题清单和改好的提示词。
有。先运行 npx -y apimodels-mcp login,在浏览器里点「授权」,再装插件:Claude Code 里输入 /plugin install apimodels --marketplace stimQQ/apimodels-mcp;Codex 里依次运行 codex plugin marketplace add stimQQ/apimodels-mcp 和 codex plugin add apimodels@apimodels。插件里带了 MCP 服务器和一份技能说明,智能体知道什么时候用、怎么选模型、什么时候该先问你再花钱,所以直接用大白话要视频就行,不用点名工具。
可以。把客户端指向托管地址 https://api.apimodels.app/mcp,按提示登录 apimodels.app 并点「授权」即可,会为该应用新建一把专用 key。Codex 在 [mcp_servers.apimodels] 里填这个 url 后运行 codex mcp login apimodels;Claude Code 运行 claude mcp add --transport http apimodels https://api.apimodels.app/mcp 再在 /mcp 里授权;Cursor 写进 ~/.cursor/mcp.json 后点 Authenticate(图文教程见 /docs/cursor);ChatGPT、Claude 网页版作为自定义连接器添加。托管版读不到本地文件,智能体会先用 get_upload_url 把文件传上来。
Codex 和 Claude Code 装插件即可;Claude Desktop、Cursor、Cherry Studio 文档里给了配置;其它 MCP 客户端以 stdio 方式跑 npx -y apimodels-mcp,先运行过 npx -y apimodels-mcp login 或在环境变量里带上 APIMODELS_API_KEY 即可。对话模型需要支持函数调用 —— Claude、GPT-5.x、gpt-6-astra、Gemini 都可以。
从 apimodels-mcp 0.3.0 起不会。generate_video 最多等 wait_seconds(默认 50 秒,低于 Codex 60 秒的工具时限)就返回 task id,助手再用 get_task 取 URL,还没出片就再调一次。任务不会重复提交,也不会重复扣费。按生产数据,视频中位约 2.5 分钟、九成在 8 分钟内,通常要调一到两次 get_task。Claude Code、Claude Desktop 没有 60 秒限制,传 wait_seconds: 600 就能一次拿到 URL。
服务器本身免费开源。你只按助手实际调用的模型付正常的单次价格,且只有成功才扣费。review_image 默认用 gpt-5.6-luna,一次远低于 $0.01。