apimodels-mcp is an MCP server. Install it and your AI client gains a set of tools for our image, video, chat and speech models, using the API key you already have. You describe what you want; the assistant writes the prompt, generates, looks at the result and regenerates with a better prompt — without leaving the chat window or memorising model names.
There is nothing to download — it runs on demand through npx. First grab a key at Console → API Keys, then configure your client below.
Settings → Developer → Edit Config, add this to claude_desktop_config.json, then restart.
{
"mcpServers": {
"apimodels": {
"command": "npx",
"args": ["-y", "apimodels-mcp"],
"env": {
"APIMODELS_API_KEY": "sk_your_key_here"
}
}
}
}Settings → MCP → Add new MCP server, or write ~/.cursor/mcp.json directly.
{
"mcpServers": {
"apimodels": {
"command": "npx",
"args": ["-y", "apimodels-mcp"],
"env": { "APIMODELS_API_KEY": "sk_your_key_here" }
}
}
}Add this to ~/.codex/config.toml. Codex aborts a tool call after 60 seconds by default; the tools stay under that on their own (see "Long generations" below), so tool_timeout_sec is only needed if you want generate_video to return the URL in a single call.
[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 → add a new server of type stdio with the three fields below. Enable it, select it for the conversation from the MCP control under the chat box, and use a conversation model that supports tool calls (Claude, GPT, Gemini …).
| Command | npx |
| Arguments | -y apimodels-mcp |
| Environment variables | APIMODELS_API_KEY=sk_your_key_here |
Any other MCP client works the same way — run this over stdio.
APIMODELS_API_KEY=sk_your_key_here npx -y apimodels-mcpnpx needs Node.js on your machine. On Windows install it from nodejs.org — Cherry Studio relies on it to launch the MCP server too.
| Tool | What it does |
|---|---|
| list_models | List available model ids (chat / image / video / audio). |
| chat | Chat or completion with any LLM (gpt-5-5, claude-opus-4-8, gemini-3-pro-preview, …). |
| generate_image | Text-to-image or image edit; returns the image URL(s) plus a downscaled preview the model can look at. |
| review_image | A vision model critiques an image against your brief and returns what matches, what is wrong and a revised prompt. |
| generate_video | Text-to-video (optional reference image); returns the video URL(s), or a task id if it is not done within wait_seconds. |
| get_task | Wait for or check on a running image / video / speech task; returns the URL(s), with a preview for image tasks. |
| text_to_speech | Text-to-speech (MiniMax voices); returns the audio URL. |
ElevenLabs TTS is not exposed here: it streams raw audio bytes from POST /v1/tts/stream rather than returning a URL. Use the audio API directly for it.
You can say "make a 16:9 banner that says SAVE 10%, check the spelling and fix it if it is wrong" and let the assistant iterate until it is right. It sees the result through one of two paths, and which one applies depends on your client:
Claude Desktop, Claude Code and Cursor pass tool-result images through to the model, so the preview that generate_image attaches (a JPEG up to 1024px) is genuinely visible to it and it corrects itself from what it sees. Pass return_image: false to skip the preview.
Cherry Studio (verified on 1.9.11) renders tool-result images to you but sends the model a text placeholder, so the model is blind to what it just made. Use review_image there: it sends the image and your brief to a vision model and returns the critique as text — what matches, what is wrong, and a revised prompt. Same loop, and it works in every client.
Reviews default to gpt-5.6-luna and cost well under $0.01 each; pass claude-sonnet-5 for a stricter read. The conversation model itself only needs tool-calling support — Claude, GPT-5.x, gpt-6-astra and Gemini all qualify. You never fill in aspect ratio or resolution: the assistant picks them from what you asked for, so saying "16:9" is enough.
image_url on generate_image and generate_video accepts four forms: a public https:// URL, a local file path (/Users/me/photo.png, ./ref.jpg, ~/Pictures/x.webp), a URL on your own machine (http://127.0.0.1:8000/photo.png), and a data:image/png;base64,… URI.
The last three are uploaded for you first, and the resulting public URL is what gets generated from. That step has to happen on your side: the file exists only on your machine, and 127.0.0.1 means our server when our server resolves it — which is why passing one straight to the REST API fails with "private/reserved IP addresses not allowed". Uploads land in your account storage and are deleted after 30 days.
Every generation on apimodels is an async task, and video is slow: a median of about 2.5 minutes, 9 in 10 within 8 minutes, on our production traffic for the week to 2026-09-22 (images take about 50 seconds). Meanwhile Codex aborts a tool call after 60 seconds by default, and the MCP SDK's own client timeout is 60 seconds too. A tool that blocks until the video is ready gets killed mid-wait: the task completes and is billed, but the assistant never sees the URL. That is what 0.2.x did.
Since 0.3.0 the generation tools wait at most wait_seconds (default 50) and then return the task id with a "still running" note; the assistant calls get_task, which waits up to another wait_seconds and returns the URL(s) — with the preview for image tasks — or "still running" again. Nothing is resubmitted and nothing is billed twice, and the assistant handles it by itself. Claude Code, Claude Desktop and Cursor have no 60-second limit, so wait_seconds: 600 on generate_video gets the URL in one call; APIMODELS_WAIT_SECONDS=600 in the server's env makes that the default.
| Env var | Default | Description |
|---|---|---|
| APIMODELS_API_KEY | required | Your sk_… key. |
| APIMODELS_BASE_URL | https://api.apimodels.app/v1 | API base URL. |
| APIMODELS_WAIT_SECONDS | 50 | Default wait_seconds for generate_image / generate_video / text_to_speech / get_task: how long a call waits before handing back a task id (seconds, max 900). |
| APIMODELS_TIMEOUT_MS | — | Deprecated (0.2.x): the same wait in milliseconds; still honoured if set. |
| Symptom | Cause / fix |
|---|---|
| The tools never show up in the client | Usually npx cannot start — no Node.js on the machine, or the client did not inherit your PATH. Run the stdio command above in a terminal first and see what it prints. |
| The model says it cannot see the image | Your client is one of the "shows the image only to you" kind (Cherry Studio, for one). Use review_image instead, or switch to Claude Desktop / Cursor. |
| The assistant just talks and never calls a tool | The conversation model has no tool-calling support, or the server is not enabled for this conversation. Switch to Claude / GPT-5.x / Gemini and check the server is ticked under the chat box. |
| The tool call gets aborted mid-video (common in Codex) | Upgrade to apimodels-mcp 0.3.0 or later: the generation tools wait at most wait_seconds (default 50) and then hand back a task id, and the assistant fetches the result with get_task — nothing is lost or billed twice. 0.2.x blocked for up to 5 minutes; when the client aborted, the URL was gone (the task still completed and was billed — find it under Console → Records). |
| private/reserved IP addresses not allowed | You passed a machine-local address straight to the REST API. Go through image_url on the MCP tools instead — they upload it for you first. |
Yes. Install apimodels-mcp, then ask for the image in plain words. In Claude Desktop, Claude Code and Cursor the generated image is passed to the model, so it sees its own output and regenerates with a corrected prompt. In clients that show tool images only to the user, such as Cherry Studio, the review_image tool does the same loop in text: it sends the image and your brief to a vision model and returns what is wrong plus a revised prompt.
Claude Desktop, Claude Code, Codex CLI, Cursor and Cherry Studio are documented, and any other MCP client works by running "npx -y apimodels-mcp" over stdio with APIMODELS_API_KEY in the environment. The conversation model needs tool-calling support: Claude, GPT-5.x, gpt-6-astra and Gemini all qualify.
Not since apimodels-mcp 0.3.0. generate_video waits at most wait_seconds (default 50, under Codex's 60-second tool limit) and then returns a task id; the assistant calls get_task to collect the URL, repeating if the video is still rendering. Nothing is resubmitted or billed twice. Production video generation takes a median of about 2.5 minutes and 9 in 10 finish within 8 minutes, so expect one or two get_task calls. In Claude Code or Claude Desktop, which have no 60-second limit, pass wait_seconds: 600 to get the URL in one call.
The server itself is free and open source. You pay the normal per-generation price of whichever model the assistant calls, and only for successful generations. A review_image call costs well under $0.01 on the default gpt-5.6-luna.