API Reference

Authentication

All requests require an API key. Create one in Settings → API Keys and send it as a bearer token (or an x-api-key header). Credits are the spend cap — each image costs credits by model, resolution, and quality.

Authorization: Bearer <your-api-key>
# or
x-api-key: <your-api-key>

Base URL: https://modelmux.dev

Generate an image

Enqueues a generation and returns immediately with status: "pending" and an historyId. Credits are charged when the job runs and refunded automatically if it fails. The request body is selected by Content-Type.

curl -X POST https://modelmux.dev/api/v1/generations \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a red fox in fresh snow, golden hour",
    "model": "nano-banana-pro",
    "resolution": "2k",
    "aspectRatio": "16:9"
  }'

Response (202-style, pending)

{
  "historyId": "V1StGXR8_Z5jdHi6B-myT",
  "status": "pending",
  "model": "nano-banana-pro",
  "aspectRatio": "16:9",
  "resolution": "2k",
  "creditsCharged": 10,
  "provider": "fal",
  "createdAt": 1733011200000
}

Poll status

Poll with the historyId every few seconds until status is completed (or failed). Most images finish in seconds; large/4K jobs take longer.

curl https://modelmux.dev/api/v1/generations/V1StGXR8_Z5jdHi6B-myT \
  -H 'Authorization: Bearer <your-api-key>'

{
  "historyId": "V1StGXR8_Z5jdHi6B-myT",
  "status": "completed",
  "provider": "fal",
  "outputUrl": "/api/storage/file?key=generated/…",
  "creditsUsed": 10,
  "model": "nano-banana-pro",
  "resolution": "2k",
  "aspectRatio": "16:9",
  "completedAt": 1733011230000
}

Statuses: pending → processing → completed | failed (with errorMessage).

Fetch the image

Once completed, stream the raw image bytes (key-authenticated). Save it to a file or pipe it onward.

curl https://modelmux.dev/api/v1/generations/V1StGXR8_Z5jdHi6B-myT/image \
  -H 'Authorization: Bearer <your-api-key>' \
  -o output.png

Models & pricing

Cost is charged in credits. Pass the model id below; quality tiers apply to GPT Image only.

GPT Image 2 credits: 1K = 2/10/18, 2K = 5/20/40, 4K = 10/32/80 (standard / medium / high). Aspect ratios: 1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9.

Errors & status codes

Errors are JSON: { "error": string, "code": string }.

If a generation failed, the credit is refunded automatically — check errorMessage on the status response.

MCP server

Use ModelMux from any MCP client (Claude Desktop, Cursor, …) via the modelmux-mcp server — it generates an image, polls until ready, and returns it.

{
  "mcpServers": {
    "modelmux": {
      "command": "npx",
      "args": ["-y", "modelmux-mcp"],
      "env": { "MODELMUX_API_KEY": "<your-api-key>" }
    }
  }
}

Agent skill (Claude Code)

Install the modelmux skill to generate and edit images from Claude Code (and other agents) with bundled recipes.

# project scope → .claude/skills/modelmux/
npx skills add modelmux/skills -a claude-code

# or global → ~/.claude/skills/modelmux/
npx skills add modelmux/skills -a claude-code -g

Export MODELMUX_API_KEY where the agent runs, then ask it to “generate an image of …”.