Skip to main content
Glama
README.md
# apimodels-mcp

MCP server for [apimodels.app](https://apimodels.app) — call **image, video, LLM chat, text-to-speech and speech-to-text** models with one API key, from Claude Desktop, Cursor, or any MCP client.

One key unlocks GPT-6.1, Claude, Gemini, GLM, DeepSeek, Qwen, Seedance, Veo, Kling, gpt-image-2, Gemini Image, MiniMax speech and more — billed in USD, you only pay for successful generations.

## Fastest setup: the Codex / Claude Code plugin

Coding agents are good at planning — scripts, shot lists, prompts, editing with ffmpeg. The **apimodels plugin** gives them the part they cannot do: rendering the video, images and voice-over. It bundles this MCP server plus a skill that teaches the agent when to use it, how to pick a model, how to wait for long renders and when to ask before spending.

1. **Sign in once** (needs [Node.js](https://nodejs.org/en/download) 18+):
   ```bash
   npx -y apimodels-mcp login
   ```
   Your browser opens apimodels.app; click **Authorize**. A key named `CLI · <date>` is created for this machine and stored in `~/.apimodels/credentials.json`, where every client finds it — including desktop apps that do not see your shell's environment variables. Nothing to copy or paste, and the agent can run this step for you. On a machine without a browser use `--no-browser` (prints the link) or `--paste` (paste a key from <https://apimodels.app/console/api-keys>).
2. **Install the plugin.**
   - Claude Code (2.1.275 or later):
     ```
     /plugin install apimodels --marketplace stimQQ/apimodels-mcp
     ```
     Older versions: `/plugin marketplace add stimQQ/apimodels-mcp`, then `/plugin install apimodels@apimodels`.
   - Codex:
     ```bash
     codex plugin marketplace add stimQQ/apimodels-mcp
     codex plugin add apimodels@apimodels
     ```
     Only have the Codex desktop app and no `codex` command? Use `npx -y @openai/codex` in place of `codex` — it runs the official CLI on the fly and shares the app's config.
     Then restart Codex. Codex asks you to approve each call that spends credits or changes something (the generation tools, `transcribe_audio`, `chat`, `review_image`, `embed`, `extract_media`, `jev_decide`, `upload_asset`, `delete_asset`, `clone_voice`, `delete_voice`, `write_lyrics`); checking progress, the model list, voices, assets and the balance never asks.
3. **Ask in plain words**, e.g. *"make a 5-second 16:9 video of a kitten slowly raising its head in morning light"* or *"plan a 20-second product video for this repo and render it shot by shot"*.

No Node.js yet? Install the plugin anyway and ask for a video: the skill has the agent check for Node.js and, with your OK, install the official LTS for you (`winget` on Windows, Apple's installer on macOS).

## Hosted server: no Node.js, sign in with OAuth

The same tools run at **`https://api.apimodels.app/mcp`** (Streamable HTTP). Nothing to install and no key to copy: add the URL to your client and it asks you to sign in to apimodels.app and click **Authorize**. The access token it gets is a dedicated API key named `MCP · <app> · <date>`; delete that key in the console to disconnect.

- **Codex** — add to `~/.codex/config.toml`, then run `codex mcp login apimodels`:
  ```toml
  [mcp_servers.apimodels]
  url = "https://api.apimodels.app/mcp"
  ```
- **Claude Code** — `claude mcp add --transport http apimodels https://api.apimodels.app/mcp`, then `/mcp` → apimodels → Authenticate.
- **Cline** — `cline mcp install apimodels --transport http https://api.apimodels.app/mcp`, or in VS Code add `{"type": "streamableHttp", "url": "https://api.apimodels.app/mcp"}` under `mcpServers.apimodels` in `cline_mcp_settings.json` and authorize. Step-by-step guide for agents: [llms-install.md](llms-install.md).
- **ChatGPT, Claude.ai, Cursor and other clients that take a remote MCP URL** — add it as a custom connector with this URL and sign in when asked.

Differences from the local server: the hosted one cannot read files on your machine — the agent calls `get_upload_url`, uploads the file with `curl -T` and passes the returned URL instead (local paths are refused with that hint) — and each call waits at most 50 seconds before handing back a task id for `get_task`. Signed in with a plain API key instead? Send it as `Authorization: Bearer sk_…`.

## Tools

| Tool | What it does |
|------|--------------|
| `get_balance` | Your apimodels balance in USD — the agent checks it before a batch. |
| `list_models` | Every model id, grouped by endpoint, with the tool that calls it. |
| `chat` | Chat / text completion with any LLM (`gpt-6.1-sol`, `claude-opus-5-5`, `gemini-3-pro-preview`, …). |
| `generate_image` | Text-to-image and edits, with up to 16 reference images (`image_urls`), masks and markup images, exact `size`, `n`, `quality` and `output_format` — including animated GIF (`frame_count`, `frame_duration_ms`) and SVG on `gpt-image-2.6-flare` / `-sunburst`. Returns the URL(s) plus a preview the model can look at. With `doubao-seedream-5-0-flash` it can keep a transparent background or split an image into named transparent layers. |
| `review_image` | A vision model critiques an image against your brief and proposes a revised prompt. |
| `generate_video` | Text-to-video, image-to-video, first + last frame, reference images / videos / audio (Seedance), talking avatars and lip sync (image or video + `audio_url`), motion transfer (image + driving video), upscaling and subtitle removal. |
| `get_task` | Wait for / check on any image, video, audio or transcription task that came back as still running. |
| `text_to_speech` | Speech from MiniMax, ElevenLabs (`eleven-tts-v3`, `v4`, flash, turbo, multilingual), Fish and Kling voices; returns the audio URL (ElevenLabs can also be saved to a local file). |
| `list_voices` | Search 12,000+ MiniMax, ElevenLabs and Fish voices by language, gender or keyword, the Kling voices for `kling-tts`, or your own clones (`mine: true`). Free. |
| `clone_voice` · `delete_voice` | Clone a voice from an audio sample — MiniMax ($1.41), ElevenLabs (free, kept 24 hours) or Fish (first 20 free) — and delete clones you no longer need. |
| `generate_audio` | Music with `suno-v5` (from a description or your own lyrics), sound effects, a soundtrack for a video, multi-speaker dialogue, dubbing into another language, and voice isolation. |
| `transcribe_audio` | Speech to text with `nemotron-3.5-transcribe`: the full text of an audio file or a video's audio track, plus a `transcript_url` to the complete JSON. Optional word-level timestamps with speaker labels (`timestamps`), or translation (`target_language`). $0.0025 per audio minute. |
| `write_lyrics` | Draft lyrics, a title and style tags for `suno-v5`. Free. |
| `embed` | Embedding vectors (`text-embedding-3-small` / `-large`). |
| `extract_media` | Direct video / image / audio links, captions and subtitles from YouTube, TikTok, Instagram, X, Bilibili, Douyin, Xiaohongshu and 1000+ other sites; whole profiles and playlists page by page. |
| `jev_decide` | Jev (TypeSafe System One): typed questions about a state, answered with calibrated probabilities. |
| `upload_asset` | Register an image, video or audio file in your asset library and get an `asset://` reference to reuse a person or product across video tasks ($0.01). |
| `list_assets` · `get_asset` · `delete_asset` | Browse, check and delete library assets. |
| `get_upload_url` | Hosted server only: a 15-minute link to `curl -T` a local file to; returns its public URL. |

Not exposed: the realtime voice model (`grok-voice-3.0`, a WebSocket session) — MCP tool calls cannot carry a live audio stream.

### Long generations do not get lost

Every generation is asynchronous on apimodels, and video is slow: a median of about 2.5 minutes, 9 in 10 within 8 minutes (production, week to 2026-09-22). Images take about 50 seconds. Meanwhile Codex aborts an MCP 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 therefore gets killed mid-wait — the task keeps running, the account is billed when it finishes, and the assistant never sees the URL. Versions up to 0.2.x did exactly that.

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 image preview for image tasks — or "still running" again. Nothing is resubmitted and nothing is billed twice. The assistant does this on its own; you just ask for the video.

- **Codex**: keep the default. Or raise `tool_timeout_sec` for this server in `config.toml` and pass a larger `wait_seconds`.
- **Claude Code / Claude Desktop / Cursor**: 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.

### The model can check its own work

Ask for an image and let the assistant iterate until it is right — "make a 16:9 banner that says SAVE 10%, check the spelling, fix it if needed":

1. `generate_image` returns the URL **and a preview of the image itself** (max 1024px JPEG). Clients that pass tool-result images to the model — Claude Desktop, Claude Code, Cursor — let it see what it made. Pass `return_image: false` to skip the preview.
2. `review_image` works everywhere, including clients that show tool-result images to you but not to the model (Cherry Studio is one). It sends the image and your brief to a vision model and returns what matches, what is wrong (garbled text, composition, aspect ratio, artifacts) and a revised prompt. One review costs well under $0.01 on the default `gpt-5.6-luna`.

The assistant picks `aspect_ratio` and `resolution` itself from what you ask for, so "make it 16:9" in plain words is enough.

### Speech to text

`transcribe_audio` turns a recording into text — "transcribe ~/Downloads/interview.m4a and list the action items":

- The answer is the text itself, with the audio duration and a `transcript_url`: the complete result as JSON, kept 30 days.
- `timestamps: true` adds word-level start / end times and speaker labels (up to 8 speakers) to that JSON: `words[]`, `diarization[]` and `text_with_speakers`.
- `target_language` translates the speech instead (32 language codes; only translation to or from English is guaranteed). It cannot be combined with `timestamps: true` — the tool refuses that pair before sending anything.
- $0.0025 per audio minute ($0.15 per hour), billed by the second. Timestamps, speaker labels and translation cost nothing extra; failed jobs are not billed.
- Up to 60 minutes and 200 MB per file: mp3, wav, m4a, aac, flac, ogg, opus, webm, or mp4 / mov with an audio track. Whole-file, offline transcription — not realtime.
- A local file is uploaded first, and that upload takes audio up to 10 MB and video up to 100 MB. For a larger recording, put it at a public URL and pass the URL.

A long recording that is still being processed comes back as a task id; `get_task` then returns the same text.

### Local files just work

Every input that takes a file — `image_url`, `image_urls`, `video_url`, `audio_url`, reference lists, `source` on `upload_asset` — takes any of these (images and audio up to 10 MB, video up to 100 MB):

- a public `https://…` URL — passed through untouched
- **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`, `http://localhost:3000/…`
- a `data:image/png;base64,…` URI
- an `asset://…` reference from `upload_asset` — passed through untouched

The last three are uploaded for you first, and the resulting public URL is what gets
generated from. This has to happen here rather than server-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 to the REST API directly fails with `private/reserved IP addresses not allowed`.
This MCP server runs next to your files, so it can do what our servers cannot.

Uploads land in your account's R2 space and are auto-deleted after 30 days.

## Setup

1. Run `npx -y apimodels-mcp login` and click **Authorize** in the browser — or create a key at <https://apimodels.app/console/api-keys> (it looks like `sk_…`) and put it in the server's environment as `APIMODELS_API_KEY`, as the examples below do.
2. Add the server to your MCP client. `npx -y apimodels-mcp status` shows which key is in use and your balance.

### Claude Desktop

Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):

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

Restart Claude Desktop. You can now ask it to "generate an image of …" or "make a 5-second video of …".

### Cursor

`Settings → MCP → Add new MCP server`, or add to `~/.cursor/mcp.json`:

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

### Codex CLI

Add to `~/.codex/config.toml`:

```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
```

Two things to know in Codex:

- **Approvals.** Codex asks you to approve any tool call that is not marked read-only. Since 0.4.3, `list_models` and `get_task` are marked read-only, so waiting on a video no longer prompts on every check (0.8.0 adds `list_voices`, `list_assets` and `get_asset`); the tools that bill your account or change your asset library still ask once per call. To skip those prompts as well, add `default_tools_approval_mode = "approve"` under `[mcp_servers.apimodels]`.
- **Name the tool.** Codex loads MCP tools on demand rather than listing them all up front, so say which one you want — e.g. *"use apimodels generate_video to make a 5-second 16:9 clip of …"*. A bare "make me a video" may not make it look.

### Cherry Studio

In `Settings → MCP Servers`, add a new server of type **stdio**:

- Command: `npx`
- Arguments: `-y apimodels-mcp`
- Environment variables: `APIMODELS_API_KEY=sk_your_key_here`

Enable the server, then select it for your conversation from the MCP control under the chat box. Use a chat model that supports tool calls (Claude, GPT, Gemini …) as the conversation model — it calls the image model for you. Cherry Studio needs Node.js installed for `npx`; on Windows install it from <https://nodejs.org>.

Any other MCP client works the same way — run `npx -y apimodels-mcp` over stdio with `APIMODELS_API_KEY` in the environment.

## Models, docs and pricing

Everything the tools call is documented on apimodels.app:

- [API documentation](https://apimodels.app/docs) · [pricing](https://apimodels.app/pricing) · [full model catalog](https://apimodels.app/models)
- Image: [GPT Image 2.5 API](https://apimodels.app/docs/gpt-image-2-5) ([model page](https://apimodels.app/models/gpt-image-2.5-flare)), [GPT Image 2 API](https://apimodels.app/docs/gpt-image-2), [Nano Banana 2.1 API](https://apimodels.app/docs/nano-banana-2-1) ([model page](https://apimodels.app/models/nano-banana-2-1)), [all image models](https://apimodels.app/docs/image)
- Video: [Seedance 2.5 API](https://apimodels.app/docs/seedance-2-5), [Kling 4.0 and Kling 4.0 Flash API](https://apimodels.app/docs/kling-4-0) (`kling-4.0-flash`: 720p, 3–20 s, $0.094 per second, same fields as `kling-4.0`), [Google Veo API](https://apimodels.app/docs/google-veo), [MiniMax H3 API](https://apimodels.app/docs/minimax-h3), [FlashVSR video upscaling](https://apimodels.app/docs/flashvsr)
- Chat and speech: [LLM API (GPT, Claude, Gemini, DeepSeek, GLM, Qwen)](https://apimodels.app/docs/llm), [Claude Sonnet 5.5](https://apimodels.app/models/claude-sonnet-5-5), [audio and text-to-speech](https://apimodels.app/docs/audio), [Nemotron 3.5 Transcribe (speech to text)](https://apimodels.app/docs/nemotron-3-5-transcribe)
- Other ways in: [Claude Code setup](https://apimodels.app/docs/claude-code), [chat clients](https://apimodels.app/docs/clients), [Agent Skills](https://apimodels.app/docs/skills), [free calculators and tools](https://apimodels.app/tools)
- Prompt libraries with example outputs: [GPT Image 2.5 prompts](https://apimodels.app/gpt-image-2-5-prompts), [GPT Image 2 prompts](https://apimodels.app/gpt-image-2-prompts), [Seedance 2.5 prompts](https://apimodels.app/seedance-2-5-prompts), [MiniMax H3 prompts](https://apimodels.app/minimax-h3-prompts)

## Configuration

| Env var | Default | Description |
|---------|---------|-------------|
| `APIMODELS_API_KEY` | — | Your `sk_…` key. Optional when you have run `apimodels-mcp login`; if both exist, this one wins. |
| `APIMODELS_CREDENTIALS_FILE` | `~/.apimodels/credentials.json` | Where `apimodels-mcp login` saves the key and where the server looks for it. |
| `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`, `generate_audio`, `transcribe_audio` and `get_task`: how long a call waits before handing back a task id. Max 900. |
| `APIMODELS_TIMEOUT_MS` | — | Deprecated (0.2.x): the same wait in milliseconds. Still honoured if set. |

## Local development

```bash
pnpm install
pnpm build
pnpm test                                     # offline self-test: mocked API, no network, no cost
APIMODELS_API_KEY=sk_... node dist/index.js   # runs over stdio
```

## Changelog

- **0.9.0** — `transcribe_audio`: speech to text with `nemotron-3.5-transcribe` (word-level timestamps, speaker labels, translation); `get_task` prints the text of a transcription task. `kling-4.0-flash` listed for `generate_video`.
- **0.8.0** — every `/v1` endpoint as a tool (music, sound effects, dubbing, embeddings, media extraction, Jev), the asset library, voice cloning.

## License

MIT

TDQS

A4.2/5.0

Scored across 6 tools

Disambiguation5/5

Each tool maps to a clearly distinct modality or action: model listing, text chat, image generation, image critique, video generation, and speech synthesis. There is no meaningful overlap between tool purposes, so an agent should be able to select correctly.

Naming Consistency4/5

Most tools follow a snake_case verb_noun pattern (list_models, generate_image, review_image, generate_video). text_to_speech is a descriptive noun phrase and chat is a single verb, which are minor deviations from the dominant pattern.

Tool Count5/5

Six tools is a well-scoped set for a multimodal model gateway covering chat, image, video, and audio. Each tool is independently useful and there are no redundant additions.

Completeness4/5

The tool surface covers the main generation workflows for all four advertised modalities and includes a helpful image-review loop. Minor gaps exist, such as no video review or audio transcription, but agents can complete core tasks without dead ends.

Maintenance

ActivityActive
ResponsivenessNo recent community issues