# RouteMux

> AI gateway: call models from many providers with one API key and one prepaid wallet,
> through OpenAI-, Anthropic- and Vertex-compatible protocols. Only successful requests are billed.

This file is an index for AI coding agents (Claude Code, Codex, Cursor and others).
Human-readable docs: https://routemux.com/docs
Append `.md` to any docs URL for raw Markdown, e.g. https://routemux.com/docs/getting-started.md

## Base URLs

All model calls go to the gateway, https://api.routemux.com. Point your SDK at:

- OpenAI-compatible: https://api.routemux.com/v1
- Anthropic-compatible: https://api.routemux.com/anthropic
- Google GenAI / Vertex: https://api.routemux.com/vertex-ai

## Authentication

Send `Authorization: Bearer <RouteMux API key>` (Anthropic SDKs may use `x-api-key`,
Google SDKs `x-goog-api-key`; send exactly one).
Create keys at https://routemux.com/console/keys. Keys start with `sk-`; legacy `rmx_live_` keys are still accepted.

## Quickstart

Swap the base URL in an existing OpenAI SDK; **nothing else changes**:

```python
from openai import OpenAI

client = OpenAI(base_url="https://api.routemux.com/v1", api_key="sk-...")
resp = client.chat.completions.create(
    model="openai/gpt-5.6-sol",
    messages=[{"role": "user", "content": "Hello"}],
)
```

```bash
curl https://api.routemux.com/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-5.6-sol","messages":[{"role":"user","content":"Hello"}]}'
```

## Coding agents

- Claude Code: https://routemux.com/docs/integrations/dev-tool/claude-code.md
- Codex CLI: https://routemux.com/docs/integrations/dev-tool/codex-cli.md
- Other tools (Cursor, Cline, OpenCode, Gemini CLI and more): see Integrations in https://routemux.com/docs

## Agent Skills

Ready-made skills that let an agent generate images and video, look up models and pricing,
and point itself at RouteMux.

- Any agent: `npx skills add https://routemux.com -g`
- Claude Code, inside a session: `/plugin marketplace add https://routemux.com/.well-known/agent-skills/marketplace.json` then `/plugin install routemux@routemux`
- No Node.js: `curl -fsSL https://routemux.com/.well-known/agent-skills/install.sh | sh`
- Discovery manifest: https://routemux.com/.well-known/agent-skills/index.json
- Guide: https://routemux.com/docs/integrations/agent-skills.md

## Endpoints

- POST /v1/chat/completions                 OpenAI Chat Completions compatible
- POST /v1/responses                        OpenAI Responses compatible
- POST /v1/messages                         Anthropic Messages compatible
- POST /vertex-ai/…:generateContent         Google Vertex compatible
- POST /vertex-ai/…:streamGenerateContent   Google Vertex, streaming
- POST /v1/images/generations               Text-to-image
- POST /v1/images/edits                     Image editing / image-to-image (multipart)
- POST /vertex-ai/…:generateImages          Vertex image generation
- POST /vertex-ai/…:editImage               Vertex image editing
- POST /vertex-ai/…:upscaleImage            Vertex image upscaling
- POST /v1/videos                           Async job; poll for the result
- POST /vertex-ai/…:generateVideos          Vertex video, async
- POST /v1/audio/speech                     Text-to-speech (TTS); returns audio bytes
- POST /v1/audio/transcriptions             Speech-to-text (STT); multipart audio upload
- GET  /v1/models                           Models your key can call

## Protocols supported by the example model

- OpenAI Chat Completions (`openai_chat`)
- OpenAI Responses (`openai_responses`)
- Anthropic Messages (`anthropic_messages`)

## Providers you can call

- openai
- anthropic
- minimax
- deepseek
- zhipu
- google
- xai
- moonshot
- meta
- qwen

**Providers not on this list cannot be called right now.** The public catalog and
`/v1/models` treat them as nonexistent, so do not generate code that calls them.
The list grows over time; the live response of `GET /v1/models` is authoritative.

## Machine-readable contract

OpenAPI 3.1 spec (endpoints, authentication, error envelope, billing semantics):
https://routemux.com/docs/openapi.json

## Models

- For machines: `GET https://api.routemux.com/v1/models` (requires a key; returns exactly the models you can call)
- For humans: https://routemux.com/models
- **Plain-text fact sheet for one model: append `.md` to its page URL**
  e.g. https://routemux.com/anthropic/claude-opus-5.md
  Specs, pricing (with units), supported protocols, aliases and sibling variants; no navigation or styling.
  Localized versions add the locale prefix, e.g. https://routemux.com/zh/anthropic/claude-opus-5.md

## Billing

- Prepaid wallet, priced per token or per request. **Failed requests are not billed**;
  every error response states its billing outcome in `billing.status`.
- One bill, no subscription, no seat fees.
- Unused purchased credit is refundable on request. A refund fee applies and bonus credit
  is not refundable; see https://routemux.com/refund
- Usage and billing: https://routemux.com/console/logs and https://routemux.com/console/billing

## Errors

Branch on the error **code**, never on `message` (messages are localized and may change).
The protocol family you called keeps its own envelope; the code sits at:

- OpenAI-compatible endpoints: `error.code` (`error.type` keeps OpenAI's values)
- Anthropic Messages: `error.code` (next to the standard `error.type`)
- Google GenAI / Vertex: `error.status`
- Every HTTP error: the `X-RouteMux-Error-Code` header
- Streams: if the error happens after headers were sent, the HTTP status may already be 200;
  read the code from the `event: error` frame

Every error also carries:

- `retry.retryable` and `retry.strategy`, plus `retry.retry_after_seconds` and a `Retry-After`
  header when a minimum wait applies
- `billing.status`:
  - `NOT_BILLED`: nothing was charged
  - `BILLED`: the request was charged
  - `PENDING`: settlement has not finished; check the request log
  - `UNKNOWN`: outcome not known yet; the request log is authoritative
- `reference` (stable, `RMX-…`) and `request_id`; quote both when contacting support

What each `retry.strategy` means:

- `AUTHENTICATE`: the API key is missing or invalid; fix the key, do not retry as-is
- `FIX_REQUEST`: change the request; sending it again unchanged fails again
- `TOP_UP`: the wallet needs credit; ask the user to top up at https://routemux.com/console/billing
- `BACKOFF`: wait `Retry-After` seconds (or back off exponentially with jitter), then retry
- `RETRY`: safe to retry the same request
- `SWITCH_MODEL`: pick another model from `GET /v1/models`
- `CONTACT_SUPPORT`: retrying will not help; contact support with `reference` and `request_id`
- `NONE`: do not retry automatically; read `message`

Codes you are most likely to hit:

- 401 `AUTH_INVALID_API_KEY` (`AUTHENTICATE`): Check the key value or create a new key in Console.
- 422 `BILLING_INSUFFICIENT_CREDITS` (`TOP_UP`): Top up the wallet, then submit the request again.
- 403 `MODEL_REQUIRES_TOPUP` (`SWITCH_MODEL`): Top up any amount to unlock this model immediately — bonus credits can pay for it too. Other models stay available in the meantime.
- 429 `LIMIT_RATE_EXCEEDED` (`BACKOFF`): Wait for the number of seconds in the Retry-After header before retrying. Without that header, wait a few seconds, then double the wait after each failure and add a small random delay so clients do not all retry at once.
- 429 `LIMIT_API_KEY_DAILY_QUOTA_EXHAUSTED` (`NONE`): The allowance resets at 00:00 in the timezone configured on the key. To use it sooner, raise or clear the daily limit on the key, or reset its used quota — both in Console → API Keys.
- 404 `MODEL_NOT_FOUND` (`SWITCH_MODEL`): Choose a model ID returned by the models endpoint.
- 400 `MODEL_CONTEXT_EXCEEDED` (`FIX_REQUEST`): Shorten or compact the conversation history, or switch to a model with a larger context window. Retrying the same request will fail again.
- 503 `MODEL_BUSY` (`BACKOFF`): Wait a few seconds and retry, lengthening the wait after each failure. Switch models if you need a result sooner.
- 503 `MODEL_NOT_PROVISIONED` (`SWITCH_MODEL`): Choose another model or contact support; unchanged retries will not help.
- 503 `MODEL_UNAVAILABLE` (`SWITCH_MODEL`): Try another model or retry later; contact support if it persists.

Full catalog: https://routemux.com/docs/errors.md
Support: support@routemux.com

## More

- Model catalog: https://routemux.com/models
- About: https://routemux.com/about
- Terms: https://routemux.com/terms · Privacy: https://routemux.com/privacy · Refunds: https://routemux.com/refund