# RouterPlex — complete documentation for LLMs

<instructions>
You are reading the full documentation of RouterPlex, an OpenAI-compatible AI gateway.
Use it to write code against the RouterPlex API or to configure IDEs, agents, and tools for a user.

Key facts:
- Base URL: https://api.routerplex.com/v1 (drop-in replacement for the OpenAI API).
- Authentication: "Authorization: Bearer <key>" — keys are created at https://routerplex.com/dashboard/keys.
- Model IDs are used verbatim (e.g. gpt-5.5, claude-opus-4-8, gemini-3.1-pro) — no provider prefix, except in tools that require an "openai/" prefix to select the wire format (Aider, OpenHands).
- The Anthropic-compatible /v1/messages format supports all 39 chat models. Set ANTHROPIC_BASE_URL=https://api.routerplex.com; the Anthropic SDK or Claude Code appends /v1/messages.
- Never hardcode API keys in code you produce; read them from an environment variable and ask the user to supply theirs.
- When configuring a tool for a user, prefer creating a dedicated key with a budget for that tool.
</instructions>


---

# Introduction
_Getting started — What RouterPlex is and how it fits into your stack._

RouterPlex is a multi-model API with both OpenAI-compatible and Anthropic-compatible request formats. One key, one balance — every model we serve, from GPT and Claude to Gemini, DeepSeek, Kimi and Qwen.

> **OpenAI base URL:** `https://api.routerplex.com/v1`
>
> **Anthropic base URL:** `https://api.routerplex.com` — the Anthropic SDK appends `/v1/messages`.

## How it works

1. You create an account and verify your email.
2. You can run one bounded live route proof from the [dashboard](https://routerplex.com/dashboard/evaluate) before paying. It uses a fixed server-side prompt; no card, API key, or balance is required.
3. Top up from $5, create an API key in the [dashboard](https://routerplex.com/dashboard/keys), and point any OpenAI-compatible SDK, IDE, or agent at `https://api.routerplex.com/v1`.
4. You pick a model by its ID (for example `gpt-5.5`, `claude-opus-4-8`, `gemini-3.1-pro`) — same request shape for all of them.
5. Every paid request deducts its exact token cost from your prepaid balance. No subscription required.

## What's supported

| Capability | Status |
| --- | --- |
| Chat completions (`/v1/chat/completions`) | All 39 chat models |
| Streaming (SSE) | Supported |
| Function calling / tools | Supported, model-dependent |
| Vision (image inputs) | Supported, model-dependent |
| JSON mode / structured output | Supported, model-dependent |
| Image generation (`/v1/images/generations`) | Supported — `gpt-image-2` |
| Responses API (`/v1/responses`) | Supported for Codex custom providers |
| Model list (`/v1/models`) | Supported |
| Anthropic-compatible `/v1/messages` format | All 39 chat models — use the Anthropic SDK or point [Claude Code](/claude-code) straight at RouterPlex |

## Where to go next

- [Quickstart](/quickstart) — first request in under a minute.
- [Anthropic Messages](/anthropic-messages) — call any chat model with the Anthropic SDK and wire format.
- [IDEs & editors](/cursor) and [Agents & CLIs](/claude-code) — use RouterPlex inside Cursor, VS Code, Zed, OpenClaw, OpenCode, Codex CLI, Aider and more.
- [Models](/models) — the live catalog with per-token pricing.

---

# Quickstart
_Getting started — Verify the route, create a key, and send your first request._

1. [Create an account](https://routerplex.com/sign-up) and verify your email.
2. Optional: run the one bounded live route proof in the [dashboard](https://routerplex.com/dashboard/evaluate). It uses a fixed prompt and does not require a card, API key, or balance.
3. Top up your balance — pay-as-you-go starts at $5, by card or crypto. No subscription required.
4. In the dashboard, open [API Keys](https://routerplex.com/dashboard/keys) and create a key. Copy it immediately — it's shown only once.
5. Store the key in your shell:

```bash
export ROUTERPLEX_API_KEY="sk-..."
```

6. Make your first request:

```bash
curl https://api.routerplex.com/v1/chat/completions \
  -H "Authorization: Bearer $ROUTERPLEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

Swap `"gpt-5.5"` for any ID in the [model catalog](/models) — same endpoint, same request shape.

## With the OpenAI SDK

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.routerplex.com/v1",
    api_key=os.environ["ROUTERPLEX_API_KEY"],
)

response = client.chat.completions.create(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Explain HTTP in one line"}],
)
print(response.choices[0].message.content)
```

No code at all? Try models in the [playground](https://routerplex.com/dashboard/playground) first.

---

# Authentication
_Getting started — API keys, headers, and key hygiene._

Every request needs your RouterPlex API key. OpenAI-compatible clients normally send it as a bearer token:

```text
Authorization: Bearer sk-...
```

Anthropic-compatible clients normally send the same key in `x-api-key`:

```text
x-api-key: sk-...
```

Both authentication styles work on `/v1/messages`. Use the default header produced by your SDK.

Keys are created and managed in the [dashboard](https://routerplex.com/dashboard/keys).

## Key hygiene

- Treat keys like passwords: server-side only, never in browser code or public repos.
- Give each app, IDE, or agent its **own key** with its own [budget and model allowlist](/keys-budgets) — an agent gone wild can't drain your whole balance.
- If a key leaks, delete it in the dashboard. Revocation is immediate.
- Prefer environment variables (`ROUTERPLEX_API_KEY`) over hardcoding.

---

# Chat completions
_API reference — OpenAI-compatible chat completions for every chat model._

`POST https://api.routerplex.com/v1/chat/completions`

The endpoint uses the OpenAI Chat Completions request and response shape, so the
official SDKs work by changing the base URL and API key.

For the protocol boundary, portability limits, and provider-switching checklist, read [What is an OpenAI-compatible API?](https://routerplex.com/blog/openai-compatible-api).

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.routerplex.com/v1",
    api_key=os.environ["ROUTERPLEX_API_KEY"],
)

response = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{"role": "user", "content": "Explain HTTP in one line"}],
)
print(response.choices[0].message.content)
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.routerplex.com/v1",
  apiKey: process.env.ROUTERPLEX_API_KEY,
});

const response = await client.chat.completions.create({
  model: "deepseek-v4-pro",
  messages: [{ role: "user", content: "Explain HTTP in one line" }],
});
console.log(response.choices[0].message.content);
```

## Advanced parameters

Function calling, tool use, JSON mode, and vision inputs work the same way as with OpenAI — pass `tools`, `response_format`, or image content parts as usual:

```python
response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
)
```

Support for tools/vision/JSON mode varies by model — frontier models (GPT, Claude, Gemini) support all three.

---

# Anthropic Messages
_API reference — Use Anthropic's SDK and /v1/messages format with every chat model._

`POST https://api.routerplex.com/v1/messages`

RouterPlex accepts Anthropic's Messages API request format and returns Anthropic-format responses for every chat model in the catalog — Claude, GPT, Gemini, DeepSeek, Kimi, Qwen, and more. The same RouterPlex key and prepaid balance work across both API formats.

> **Anthropic SDK base URL:** `https://api.routerplex.com` — do not append `/v1`; the SDK adds `/v1/messages` itself.

## curl

```bash
curl https://api.routerplex.com/v1/messages \
  -H "x-api-key: $ROUTERPLEX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Explain HTTP in one line"}]
  }'
```

`Authorization: Bearer $ROUTERPLEX_API_KEY` also works if your HTTP client already uses bearer authentication.

## Python SDK

```python
import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.routerplex.com",
    api_key=os.environ["ROUTERPLEX_API_KEY"],
)

message = client.messages.create(
    model="gemini-3.5-flash",
    max_tokens=256,
    messages=[{"role": "user", "content": "Explain HTTP in one line"}],
)
print(message.content[0].text)
```

## TypeScript SDK

```typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.routerplex.com",
  apiKey: process.env.ROUTERPLEX_API_KEY,
});

const message = await client.messages.create({
  model: "deepseek-v4-pro",
  max_tokens: 256,
  messages: [{ role: "user", content: "Explain HTTP in one line" }],
});
console.log(message.content);
```

## Streaming

Set `stream: true` or use the Anthropic SDK's streaming helper. RouterPlex returns Anthropic SSE events such as `message_start`, `content_block_delta`, and `message_stop`, including when the selected model is not a Claude model.

## Which format should I use?

| Client | Base URL | Format |
| --- | --- | --- |
| OpenAI SDKs and OpenAI-compatible tools | `https://api.routerplex.com/v1` | `/v1/chat/completions` |
| Anthropic SDK and Claude Code | `https://api.routerplex.com` | `/v1/messages` |

Both formats reach the same 39 chat models and deduct from the same balance. `gpt-image-2` is image-generation only and uses [`/v1/images/generations`](/images), not a chat endpoint. Tool use, vision, thinking, and structured-output support still depend on the selected model.

---

# Streaming
_API reference — Server-sent events, token by token._

Set `stream: true` to receive tokens as server-sent events, exactly like the OpenAI API:

```python
stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Write a haiku"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
```

```typescript
const stream = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Write a haiku" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

Streams stay open for up to 10 minutes — enough for long reasoning-model outputs.

---

# Image generation
_API reference — OpenAI-compatible image generation with gpt-image-2._

`POST https://api.routerplex.com/v1/images/generations`

OpenAI-compatible image generation. Images are returned base64-encoded and billed by token (prompt text in, image tokens out).

```python
import base64
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.routerplex.com/v1",
    api_key=os.environ["ROUTERPLEX_API_KEY"],
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="A lighthouse on a cliff at dusk, watercolor",
    size="1024x1024",
    quality="medium",  # low | medium | high
)
with open("lighthouse.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
```

- Sizes: `1024x1024`, `1536x1024`, `1024x1536`.
- Higher quality uses more output tokens.
- Try it without code in the [playground](https://routerplex.com/dashboard/playground).

## Response and storage

The generated image arrives in the response as base64 data rather than a permanent hosted URL. Decode it and store the resulting file in your own application or object store. RouterPlex does not turn generation responses into a public media library.

## Cost and failure checks

Image cost depends on the output tokens used by the requested size and quality, so test the smallest acceptable settings before running a batch. Give image jobs a dedicated [key budget](/keys-budgets) to cap retries or loops. A 401 means the key is missing or invalid; a 400 usually points to an unsupported size, quality, or malformed prompt payload; a 429 should be retried with backoff.

---

# Models
_API reference — Listing models and picking IDs._

`GET https://api.routerplex.com/v1/models`

List the models your key can use (also OpenAI-compatible):

```bash
curl https://api.routerplex.com/v1/models \
  -H "Authorization: Bearer $ROUTERPLEX_API_KEY"
```

The [live catalog](https://routerplex.com/models) shows current per-token pricing and context windows for all 40 models. It and `GET /v1/models` are the source of truth if the snapshot below differs.

## Model IDs

Model IDs are used verbatim in the `model` field — case-sensitive, no `openai/`-style prefix. The full list:

| Model ID | Provider | Context | Type |
| --- | --- | --- | --- |
| `claude-fable-5` | Anthropic | 1M | chat |
| `claude-opus-5` | Anthropic | 1M | chat |
| `claude-sonnet-5` | Anthropic | 1M | chat |
| `claude-opus-4-8` | Anthropic | 1M | chat |
| `claude-opus-4-7` | Anthropic | 1M | chat |
| `claude-opus-4-6` | Anthropic | 1M | chat |
| `claude-sonnet-4-6` | Anthropic | 1M | chat |
| `claude-haiku-4-5` | Anthropic | 256K | chat |
| `gpt-5.5` | OpenAI | 256K | chat |
| `gpt-5.6-sol` | OpenAI | 258K | chat |
| `gpt-5.6-terra` | OpenAI | 258K | chat |
| `gpt-5.6-luna` | OpenAI | 258K | chat |
| `gpt-5.4` | OpenAI | 1M | chat |
| `gpt-image-2` | OpenAI | — | image generation |
| `gemini-3.1-pro` | Google | 1M | chat |
| `gemini-3.5-flash` | Google | 1M | chat |
| `deepseek-v4-pro` | DeepSeek | 1M | chat |
| `deepseek-v4-flash` | DeepSeek | 1M | chat |
| `kimi-k2.7` | Moonshot | 256K | chat |
| `kimi-k2.6` | Moonshot | 256K | chat |
| `kimi-k3` | Moonshot | 1M | chat |
| `qwen3.8-max` | Alibaba | 1M | chat |
| `qwen3.7-max` | Alibaba | 1M | chat |
| `qwen3.7-plus` | Alibaba | 1M | chat |
| `qwen3.6-plus` | Alibaba | 1M | chat |
| `glm-5.2` | Zhipu | 1M | chat |
| `glm-5.1` | Zhipu | 256K | chat |
| `MiniMax-M3` | MiniMax | 1M | chat |
| `MiniMax-M3-highspeed` | MiniMax | 1M | chat |
| `MiniMax-M2.7` | MiniMax | 196K | chat |
| `MiniMax-M2.7-highspeed` | MiniMax | 196K | chat |
| `doubao-seed-2.0-pro` | ByteDance | 128K | chat |
| `doubao-seed-2.0-code` | ByteDance | 200K | chat |
| `mimo-v2.5-pro` | Xiaomi | 1M | chat |
| `mimo-v2.5` | Xiaomi | 1M | chat |
| `step-3.7-flash` | StepFun | 256K | chat |
| `LongCat-2.0` | LongCat | 1M | chat |
| `hy3` | Tencent Hunyuan | 256K | chat |
| `grok-4.5` | xAI | 500K | chat |
| `grok-4.6` | xAI | 500K | chat |

Note the MiniMax IDs are capitalized exactly as shown. Current per-token pricing for every model is in the [live catalog](https://routerplex.com/models).

---

# Errors & limits
_API reference — Status codes, retry guidance, and platform limits._

Standard OpenAI-style error responses:

| Status | Meaning | Retry? |
| --- | --- | --- |
| `401` | Missing or invalid API key | no — fix the key |
| `400` | Malformed request, unsupported parameter, or insufficient prepaid balance | no — fix the request or top up |
| `429` | Edge, per-key, or provider rate limit; some gateway spend-limit failures may also use this status | yes for rate limits, no for a reached spend limit |
| `5xx` | Upstream provider issue | yes |

Error bodies follow the OpenAI shape:

```json
{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "code": "..."
  }
}
```

When a request is rejected by a key budget or your available balance, read the
returned `error.message` and `error.code` before retrying. A retry cannot
raise a hard budget or restore a zero balance; create a new key budget or top up
first.

## Platform limits

- Requests are limited to **60/s per IP** at the edge. This is separate from optional per-key RPM/TPM limits and the tighter limits on promotional accounts.
- Request bodies up to **50 MB** (plenty for base64 vision payloads).
- Streams stay open for up to **10 minutes**.

---

# OpenAI SDKs
_SDKs & frameworks — Python and JavaScript/TypeScript official SDKs._

The official OpenAI SDKs work unmodified — set `base_url` and your RouterPlex key.

## Python

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.routerplex.com/v1",
    api_key=os.environ["ROUTERPLEX_API_KEY"],
)

response = client.chat.completions.create(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

## JavaScript / TypeScript

```bash
npm install openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.routerplex.com/v1",
  apiKey: process.env.ROUTERPLEX_API_KEY,
});
```

## Environment-variable only

Both SDKs also honor environment variables, so existing code can switch to RouterPlex with zero changes:

```bash
export OPENAI_BASE_URL="https://api.routerplex.com/v1"
export OPENAI_API_KEY="sk-..."   # your RouterPlex key
```

---

# LangChain, LlamaIndex & AI SDK
_SDKs & frameworks — Use RouterPlex from the popular LLM frameworks._

Frameworks that let you set a custom OpenAI-compatible base URL can use RouterPlex. Point them at `https://api.routerplex.com/v1`.

## LangChain (Python)

```python
import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="claude-sonnet-4-6",
    base_url="https://api.routerplex.com/v1",
    api_key=os.environ["ROUTERPLEX_API_KEY"],
)
print(llm.invoke("Hello!").content)
```

## LlamaIndex

```python
import os
from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    model="deepseek-v4-pro",
    api_base="https://api.routerplex.com/v1",
    api_key=os.environ["ROUTERPLEX_API_KEY"],
    is_chat_model=True,
)
```

## Vercel AI SDK

```typescript
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText } from "ai";

const routerplex = createOpenAICompatible({
  name: "routerplex",
  baseURL: "https://api.routerplex.com/v1",
  apiKey: process.env.ROUTERPLEX_API_KEY,
});

const { text } = await generateText({
  model: routerplex("gpt-5.5"),
  prompt: "Hello!",
});
```

---

# Cursor
_IDEs & editors — Use any RouterPlex model inside Cursor._

Cursor can route its chat models through RouterPlex via the OpenAI key override.

1. Open **Cursor Settings → Models → API Keys**.
2. Paste your RouterPlex key into the **OpenAI API Key** field.
3. Enable **Override OpenAI Base URL** and set it to:

```text
https://api.routerplex.com/v1
```

4. Click **Add model** and enter a model ID from the [catalog](/models) verbatim — e.g. `claude-opus-4-8` or `gpt-5.5`.
5. Enable only your custom models, then pick them from the model dropdown in chat.

> **Tip:** create a dedicated key with a [budget](/keys-budgets) for Cursor, so editor usage is capped and shows up separately in your logs.

---

# VS Code — Cline, Roo, Continue
_IDEs & editors — The three big VS Code AI extensions._

All three major VS Code AI extensions have first-class OpenAI-compatible providers. The extension settings are identical on macOS, Linux, and Windows — only the config file paths and keyboard shortcuts differ, noted below.

Install any of them from the Extensions panel (`Cmd+Shift+X` on macOS, `Ctrl+Shift+X` on Windows/Linux).

## Cline

Open Cline's settings (gear icon in the Cline panel), and under **API Configuration** choose the **OpenAI Compatible** provider:

```text
Base URL:   https://api.routerplex.com/v1
API Key:    sk-...        # your RouterPlex key
Model ID:   claude-opus-4-8
```

Cline can't fetch capability metadata from custom endpoints, so if it asks for model info, set the context window to match the [catalog](/models) (e.g. 1,000,000 for `claude-opus-4-8`) and enable image support for vision models.

Cline supports separate **Plan** and **Act** models — a common setup is `claude-opus-4-8` for Plan and `claude-sonnet-4-6` for Act.

## Roo Code

Open Roo Code's settings and pick the **OpenAI Compatible** API provider — same fields as Cline:

```text
Base URL:   https://api.routerplex.com/v1
API Key:    sk-...
Model ID:   claude-opus-4-8
```

Roo Code routes different modes to different configuration profiles — create one profile per model and assign e.g. `claude-opus-4-8` to Architect, `claude-sonnet-4-6` to Code, and `claude-haiku-4-5` to Ask to keep costs down.

## Continue

Continue is configured through a YAML file rather than the UI:

- macOS / Linux: `~/.continue/config.yaml`
- Windows: `%USERPROFILE%\.continue\config.yaml`

```yaml
models:
  - name: Claude Opus 4.8 (RouterPlex)
    provider: openai
    model: claude-opus-4-8
    apiBase: https://api.routerplex.com/v1
    apiKey: sk-...
    roles: [chat, edit, apply]
  - name: Gemini Flash (RouterPlex)
    provider: openai
    model: gemini-3.5-flash
    apiBase: https://api.routerplex.com/v1
    apiKey: sk-...
    roles: [chat]
```

Reload the Continue panel after saving and the models appear in its picker.

> **Tip:** create one RouterPlex key per extension with its own [budget](/keys-budgets), so each tool's spend is capped and attributable in your logs.

---

# VS Code — built-in Chat
_IDEs & editors — Add RouterPlex models to VS Code's built-in Chat via a custom endpoint._

VS Code's built-in **Chat** view can bring your own models through a *custom endpoint*. Add RouterPlex once and every model below shows up in the Chat model picker. The steps are the same on macOS, Windows, and Linux.

> This is for VS Code's native Chat. For the Cline, Roo Code, and Continue extensions, see [VS Code — Cline, Roo, Continue](/vscode).

## Add RouterPlex as a custom endpoint

**1. Open the Chat view, click the model dropdown, and choose "Manage Models…".**

![The Chat model picker, with "Manage Models…" at the bottom.](/vscode-chat/1.png)

**2. Click "Add Models", then choose "Custom Endpoint".**

![Add Models then Custom Endpoint in the Language Models panel.](/vscode-chat/2.png)

**3. Name the group "RouterPlex" and press Enter.**

![Naming the model group RouterPlex.](/vscode-chat/3.png)

**4. Paste your RouterPlex API key and press Enter.**

![Pasting your RouterPlex API key.](/vscode-chat/4.png)

**5. Choose "Chat Completions" as the API type.**

![Selecting the Chat Completions API type.](/vscode-chat/5.png)

**6. VS Code opens `chatLanguageModels.json` — add one entry per model, then save.**

![Editing chatLanguageModels.json: id is the model ID, url is the RouterPlex API, and the token limits depend on the model.](/vscode-chat/6.png)

That file lives at:

- macOS: `~/Library/Application Support/Code/User/chatLanguageModels.json`
- Windows: `%APPDATA%\Code\User\chatLanguageModels.json`
- Linux: `~/.config/Code/User/chatLanguageModels.json`

**7. Added the provider by editing the JSON directly?** If you created the RouterPlex group by hand instead of the wizard above, VS Code doesn't have your key yet. Right-click the group in the **Language Models** list, choose **Update API Key**, and paste your RouterPlex key.

![Right-click the model group and choose "Update API Key" to set your key.](/vscode-chat/7.png)

## Example configuration

Every model points `url` at RouterPlex (`https://api.routerplex.com/v1`). Add as many entries to `models` as you like:

```json
[
  {
    "name": "RouterPlex",
    "vendor": "customendpoint",
    "apiKey": "${input:chat.lm.secret.-8cc97ea}",
    "apiType": "chat-completions",
    "models": [
      {
        "id": "claude-opus-4-8",
        "name": "Claude Opus 4.8",
        "url": "https://api.routerplex.com/v1",
        "toolCalling": true,
        "vision": true,
        "maxInputTokens": 1000000,
        "maxOutputTokens": 64000
      },
      {
        "id": "qwen3.7-plus",
        "name": "Qwen3.7 Plus",
        "url": "https://api.routerplex.com/v1",
        "toolCalling": true,
        "vision": true,
        "maxInputTokens": 1000000,
        "maxOutputTokens": 128000
      }
    ]
  }
]
```

Leave `apiKey` as the `${input:…}` placeholder VS Code generated in step 4 — it references the key you pasted, so you never store the raw key in the file.

```vscode-copy-all
```

## Models

Every entry uses `"url": "https://api.routerplex.com/v1"`. Copy the `id`, `maxInputTokens`, and `maxOutputTokens` for each model you want:

| Model ID | Max input tokens | Max output tokens |
| --- | --- | --- |
| `claude-opus-5` | 1000000 | 128000 |
| `claude-opus-4-8` | 1000000 | 64000 |
| `claude-fable-5` | 1000000 | 128000 |
| `claude-sonnet-5` | 1000000 | 128000 |
| `claude-opus-4-7` | 1000000 | 64000 |
| `claude-opus-4-6` | 1000000 | 64000 |
| `claude-sonnet-4-6` | 1000000 | 64000 |
| `claude-haiku-4-5` | 256000 | 64000 |
| `gpt-5.5` | 256000 | 64000 |
| `gpt-5.6-sol` | 258000 | 128000 |
| `gpt-5.6-terra` | 258000 | 128000 |
| `gpt-5.6-luna` | 258000 | 128000 |
| `gpt-5.4` | 1000000 | 128000 |
| `gemini-3.1-pro` | 1000000 | 128000 |
| `gemini-3.5-flash` | 1000000 | 128000 |
| `deepseek-v4-pro` | 1000000 | 128000 |
| `deepseek-v4-flash` | 1000000 | 128000 |
| `kimi-k2.7` | 256000 | 64000 |
| `kimi-k2.6` | 256000 | 64000 |
| `kimi-k3` | 1048576 | 128000 |
| `qwen3.8-max` | 1000000 | 128000 |
| `qwen3.7-max` | 1000000 | 128000 |
| `qwen3.7-plus` | 1000000 | 128000 |
| `qwen3.6-plus` | 1000000 | 128000 |
| `glm-5.2` | 1000000 | 128000 |
| `glm-5.1` | 256000 | 64000 |
| `MiniMax-M3` | 1000000 | 128000 |
| `MiniMax-M3-highspeed` | 1000000 | 128000 |
| `MiniMax-M2.7` | 196000 | 64000 |
| `MiniMax-M2.7-highspeed` | 196000 | 64000 |
| `doubao-seed-2.0-pro` | 128000 | 32000 |
| `doubao-seed-2.0-code` | 200000 | 64000 |
| `mimo-v2.5-pro` | 1000000 | 128000 |
| `mimo-v2.5` | 1000000 | 128000 |
| `step-3.7-flash` | 256000 | 64000 |
| `LongCat-2.0` | 1000000 | 128000 |
| `hy3` | 256000 | 131072 |
| `grok-4.5` | 500000 | 128000 |
| `grok-4.6` | 500000 | 128000 |

The **Copy all** button sets `"vision"` on the models that accept image input and `"toolCalling": true` on all of them — adjust either per model if you like. Give this key its own [budget](/keys-budgets) so editor usage is capped and shows up separately in your logs.

---

# Codex — VS Code extension
_IDEs & editors — Configure OpenAI's Codex extension for VS Code with RouterPlex._

The Codex extension for VS Code reads the same `~/.codex/config.toml` file as the [Codex CLI](/codex-cli) — you just edit it from the extension's settings UI instead of a terminal.

> Using the terminal instead? The [Codex CLI](/codex-cli) guide covers the same config file plus profiles for switching models.

## Open config.toml from the extension

**1. In the Codex panel, click the gear icon in the top-right corner and choose "Codex settings".**

![Codex panel gear icon menu with "Codex settings" highlighted.](/codex-vscode/1.png)

**2. In the left sidebar, click "Configuration".**

![Codex Settings sidebar with Configuration selected.](/codex-vscode/2.png)

**3. Under "Custom config.toml settings", click "Open config.toml".**

![The "Open config.toml" button under Custom config.toml settings.](/codex-vscode/3.png)

**4. Add the RouterPlex provider block above the `[desktop]` table, then save.**

![config.toml with the RouterPlex provider block added above the desktop table.](/codex-vscode/4.png)

```toml
# ~/.codex/config.toml
model_provider = "routerplex"
model = "gpt-5.6-terra" # Or any other RouterPlex-supported model
model_reasoning_effort = "low"

[desktop]
followUpQueueMode = "queue"

[model_providers.routerplex]
name = "RouterPlex"
base_url = "https://api.routerplex.com/v1"
wire_api = "responses"
env_key = "ROUTERPLEX_API_KEY"
env_key_instructions = "Set ROUTERPLEX_API_KEY before starting Codex."
```

`model_provider`, `model`, and `model_reasoning_effort` must go **above** `[desktop]` (or any other bracketed table). TOML keys belong to whichever table header precedes them — paste them below `[desktop]` and Codex reads them as `desktop.model_provider` instead of the top-level setting, so the provider silently never applies.

The extension may have already generated other keys in the file — `notify`, `[desktop]`, `[marketplaces.openai-bundled]`. Leave those as they are; only the two blocks above are RouterPlex-specific.

## Set the API key

Create a dedicated, budget-capped RouterPlex key in the [dashboard](https://routerplex.com/dashboard/keys). `env_key` tells Codex to read it from `ROUTERPLEX_API_KEY` in your OS environment — not from `config.toml` — so set it where VS Code's process can see it.

**macOS / Linux** — add it to your shell profile so it persists, then reload the shell:

```bash
echo 'export ROUTERPLEX_API_KEY="sk-..."' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc
```

![Setting ROUTERPLEX_API_KEY in the integrated terminal.](/codex-vscode/5.png)

If you normally launch VS Code from the Dock or Spotlight rather than a terminal, note that GUI apps don't inherit variables that only live in a shell profile. Either launch VS Code with `code .` from a terminal that has sourced the profile, or set it machine-wide with `launchctl setenv ROUTERPLEX_API_KEY "sk-..."` before opening VS Code.

**Windows (PowerShell)** — `setx` persists the variable for future sessions, but not for windows already open:

```powershell
setx ROUTERPLEX_API_KEY "sk-..."
```

You can also add it under **System Properties → Environment Variables → User variables**, which has the same effect and doesn't require a terminal.

## Restart VS Code

Environment variables are read once, at process start — fully quit VS Code (not just "Reload Window") and reopen it so the Codex extension picks up `ROUTERPLEX_API_KEY`. Then open the Codex panel and send a test prompt; it should show up under the dedicated key in the RouterPlex dashboard.

If Codex reports an unsupported API format, make sure `wire_api = "responses"` is present. If a model is rejected, copy its case-sensitive ID from the [live catalog](/models) and update the `model` value.

> **Tip:** to try a different model, change only the `model` value — the `[model_providers.routerplex]` block stays the same for every RouterPlex model.

---

# Zed
_IDEs & editors — Configure Zed's agent panel with RouterPlex models._

In `settings.json` point the OpenAI provider at RouterPlex and declare the models you want in the picker:

```json
{
  "language_models": {
    "openai": {
      "api_url": "https://api.routerplex.com/v1",
      "available_models": [
        {
          "name": "claude-opus-4-8",
          "display_name": "Claude Opus 4.8 (RouterPlex)",
          "max_tokens": 1000000
        },
        {
          "name": "deepseek-v4-pro",
          "display_name": "DeepSeek V4 Pro (RouterPlex)",
          "max_tokens": 1000000
        }
      ]
    }
  }
}
```

Then open the **Agent Panel settings** and paste your RouterPlex key as the OpenAI API key.

---

# Claude Code with RouterPlex
_Agents & CLIs — Route Claude Code to any RouterPlex chat model — no translation proxy needed. One base URL change adds a prepaid balance with per-key budgets._

Claude Code speaks Anthropic's Messages API, and RouterPlex exposes that format for every chat model — so you can point Claude Code straight at Claude, GPT, Gemini, DeepSeek, and the rest of the chat catalog. No bridge or router required.

Works on macOS, Linux, and Windows.

## 1. Install Claude Code

```bash
npm install -g @anthropic-ai/claude-code
```

## 2. Point it at RouterPlex

Create or edit Claude Code's settings file and set the base URL and your RouterPlex key under `env`:

- macOS / Linux: `~/.claude/settings.json`
- Windows: `%USERPROFILE%\.claude\settings.json`

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.routerplex.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-...",
    "ANTHROPIC_MODEL": "claude-opus-4-8",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5"
  }
}
```

- `ANTHROPIC_AUTH_TOKEN` — your RouterPlex API key (create one under [API keys & budgets](/keys-budgets)).
- `ANTHROPIC_MODEL` — the model for normal turns. Use any chat ID from the [catalog](/models), e.g. `claude-opus-4-8`, `gpt-5.4`, or `gemini-3.5-flash`.
- `ANTHROPIC_SMALL_FAST_MODEL` — the cheaper model Claude Code uses for background chores, e.g. `claude-haiku-4-5` or `deepseek-v4-flash`.

Prefer to set it per shell session instead? macOS/Linux:

```bash
export ANTHROPIC_BASE_URL=https://api.routerplex.com
export ANTHROPIC_AUTH_TOKEN=sk-...
export ANTHROPIC_MODEL=claude-opus-4-8
claude
```

Windows (PowerShell):

```powershell
$env:ANTHROPIC_BASE_URL = "https://api.routerplex.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-..."
$env:ANTHROPIC_MODEL = "claude-opus-4-8"
claude
```

## 3. Verify

Start `claude`, then run `/status` — it should show the RouterPlex base URL and your model. Switch models any time with `/model gpt-5.4` or another chat model ID.

> Every chat model accepts the Messages format, but capabilities still vary. Claude-family models are the safest default for Claude Code's full tool-use behavior. Give this key its own [budget](/keys-budgets); coding agents burn tokens fast.

## Do you need Claude Code Router?

Usually not. [Claude Code Router](https://routerplex.com/blog/claude-code-router-setup) (CCR) is a separate community proxy that runs a local gateway in front of Claude Code. RouterPlex already translates Anthropic Messages for every chat model, including non-Claude ones, so the base URL above is all you need to change model families — no local proxy involved.

Reach for CCR when you actually want its local routing policy: several upstream providers at once, conditional routes, or local fallbacks. RouterPlex works as an OpenAI-compatible provider inside it, using base URL `https://api.routerplex.com/v1` and a RouterPlex key.

Current CCR releases configure providers through their management UI and store live settings in SQLite — a `config.json` is only read once as a migration source, so the older config-file walkthroughs no longer apply. The current setup is covered in [Claude Code Router: route Claude Code to any model](https://routerplex.com/blog/claude-code-router-setup).

---

# OpenClaw
_Agents & CLIs — Add RouterPlex as a model provider in OpenClaw._

[OpenClaw](https://openclaw.ai) supports custom OpenAI-compatible providers. Add RouterPlex under `models.providers` in `~/.openclaw/openclaw.json`:

```json
{
  "models": {
    "providers": {
      "routerplex": {
        "baseUrl": "https://api.routerplex.com/v1",
        "apiKey": "${ROUTERPLEX_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-4-8",
            "name": "Claude Opus 4.8",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 32000
          },
          {
            "id": "gemini-3.5-flash",
            "name": "Gemini 3.5 Flash",
            "reasoning": false,
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 16000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "routerplex/claude-opus-4-8" },
      "models": {
        "routerplex/claude-opus-4-8": { "alias": "Opus" },
        "routerplex/gemini-3.5-flash": { "alias": "Flash" }
      }
    }
  }
}
```

Then export the key and verify connectivity:

```bash
export ROUTERPLEX_API_KEY="sk-..."
openclaw models status --probe
```

Notes:

- `api: "openai-completions"` is the right mode — RouterPlex serves `/v1/chat/completions` (not `/v1/responses`).
- Models must appear in the `agents.defaults.models` allowlist or OpenClaw will reject them.
- Model references use the `provider/model-id` form, e.g. `routerplex/claude-opus-4-8`.

---

# OpenCode
_Agents & CLIs — Add RouterPlex as a custom provider in OpenCode._

Add RouterPlex as a custom provider in `~/.config/opencode/opencode.json` (or a per-project `opencode.json`):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "routerplex": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "RouterPlex",
      "options": {
        "baseURL": "https://api.routerplex.com/v1",
        "apiKey": "{env:ROUTERPLEX_API_KEY}"
      },
      "models": {
        "claude-opus-4-8": { "name": "Claude Opus 4.8" },
        "gpt-5.5": { "name": "GPT-5.5" },
        "kimi-k2.7": { "name": "Kimi K2.7" }
      }
    }
  }
}
```

Then pick the model inside OpenCode with `/models`.

## Verify the provider

Start OpenCode, open the model picker, and confirm the RouterPlex models from the configuration appear under the RouterPlex provider. Run one small repository question before changing a production workflow. A 401 response means the environment variable is missing or the key is invalid; a model-not-found response usually means the configured model ID does not exactly match the [RouterPlex model catalog](/models).

## Control agent spend

Use a dedicated RouterPlex key for OpenCode instead of sharing a production key. Set a hard budget and, if appropriate, allowlist only the models included in the OpenCode configuration. This keeps project usage attributable and limits the cost of an accidental agent loop. Add or remove models in the configuration as your workflow changes; the base URL and authentication remain the same.

---

# Codex CLI
_Agents & CLIs — Point OpenAI's Codex CLI at RouterPlex._

Codex uses the Responses API for custom model providers. RouterPlex supports that route for Codex; other OpenAI-compatible tools in these docs use `/v1/chat/completions` when their client expects Chat Completions. Configure RouterPlex in your user-level Codex configuration at `~/.codex/config.toml` (the leading dot is required):

> Using the Codex extension for VS Code instead of the terminal? See [Codex — VS Code extension](/codex-vscode) — same config file, edited from the settings UI.

```toml
# ~/.codex/config.toml
model_provider = "routerplex"
model = "gpt-5.6-sol"

[model_providers.routerplex]
name = "RouterPlex"
base_url = "https://api.routerplex.com/v1"
wire_api = "responses"
env_key = "ROUTERPLEX_API_KEY"
env_key_instructions = "Set ROUTERPLEX_API_KEY before starting Codex."
```

## Set the API key

Create a dedicated, budget-capped RouterPlex key in the [dashboard](https://routerplex.com/dashboard/keys), then set it in the terminal session that starts Codex:

```bash
export ROUTERPLEX_API_KEY="sk-..."
codex
```

`env_key` tells Codex to read the key from `ROUTERPLEX_API_KEY` and send it as bearer authentication. Keep the key out of `config.toml`, source control, and shared shell history. Restart Codex after changing either the configuration or the variable.

`gpt-5.6-sol` is a practical starting model for coding work. To switch models, replace the `model` value with an exact ID from the [catalog](/models), restart Codex, and try a small task first.

## Add multiple models

Codex runs one active model per session, but the same RouterPlex provider can serve any RouterPlex model ID. Keep the shared provider block once in `~/.codex/config.toml`, then switch models with `--model`:

```bash
codex --model claude-opus-4-8
codex exec --model gemini-3.5-flash "summarize this repository"
```

For repeatable presets, create profile files next to `config.toml`. Each profile only needs the settings that differ from the base RouterPlex provider:

```toml
# ~/.codex/routerplex-opus.config.toml
model = "claude-opus-4-8"
model_reasoning_effort = "high"
```

```toml
# ~/.codex/routerplex-flash.config.toml
model = "gemini-3.5-flash"
model_reasoning_effort = "low"
```

Run a preset with:

```bash
codex --profile routerplex-opus
codex exec --profile routerplex-flash "check this diff"
```

Do not add separate `[model_providers.routerplex-*]` blocks for each model unless the base URL or authentication method changes. The model ID changes; the RouterPlex provider, base URL, and `ROUTERPLEX_API_KEY` stay the same.

## Verify the configuration

Start Codex with a small prompt and confirm the request appears under the dedicated key in the RouterPlex dashboard. If authentication fails, run `printenv ROUTERPLEX_API_KEY` in the same shell before starting Codex; it should show that the variable exists, but do not paste the value into logs or support messages.

If Codex reports an unsupported API format, make sure `wire_api = "responses"` is present. If a model is rejected, copy its case-sensitive ID from the [live catalog](/models) and update the `model` value in the configuration.

## Use a separate budget

Coding agents can make many tool and follow-up calls from one instruction. Create a Codex-specific RouterPlex key with a hard budget rather than reusing a key that also serves an application. The limit is enforced by RouterPlex, so a local configuration mistake or runaway loop cannot spend beyond that key's cap.

---

# Aider
_Agents & CLIs — AI pair programming in your terminal, billed through RouterPlex._

Aider treats any OpenAI-compatible endpoint as an `openai/`-prefixed model:

```bash
export OPENAI_API_BASE="https://api.routerplex.com/v1"
export OPENAI_API_KEY="sk-..."   # your RouterPlex key

aider --model openai/claude-opus-4-8
```

Or persist it in `~/.aider.conf.yml`:

```yaml
openai-api-base: https://api.routerplex.com/v1
openai-api-key: sk-...
model: openai/claude-opus-4-8
weak-model: openai/claude-haiku-4-5
```

> **Note:** the `openai/` prefix tells Aider which wire format to use — the part after the slash must be a RouterPlex model ID verbatim.

## Verify the connection

Open a small test repository and ask Aider a read-only question before allowing edits. Check the RouterPlex key logs to confirm the intended model handled the request. A 401 response usually means Aider cannot see OPENAI_API_KEY; a model-not-found response means the value after the openai/ prefix does not match a current [model ID](/models).

## Choose keys and models deliberately

Give Aider its own RouterPlex key with a hard budget so its usage stays separate from production traffic. A cheaper weak model can handle repository summaries while the main model handles edits, but test the pair on your codebase rather than assuming every model follows tool instructions equally well. Both model IDs use the same RouterPlex balance and endpoint.

---

# OpenHands
_Agents & CLIs — Run the OpenHands agent on RouterPlex models._

OpenHands (formerly OpenDevin) uses LiteLLM under the hood, so it understands `openai/`-prefixed custom endpoints.

In the OpenHands UI: **Settings → LLM → Advanced**:

```text
Custom Model:  openai/claude-sonnet-4-6
Base URL:      https://api.routerplex.com/v1
API Key:       sk-...        # your RouterPlex key
```

Or with environment variables when self-hosting:

```bash
export LLM_MODEL="openai/claude-sonnet-4-6"
export LLM_BASE_URL="https://api.routerplex.com/v1"
export LLM_API_KEY="sk-..."
```

The `openai/` prefix selects the OpenAI wire format; the part after the slash is the RouterPlex model ID verbatim.

## Verify before a long task

Start OpenHands with a small read-only task and confirm the request appears in RouterPlex key logs under the expected model. If authentication fails, verify the environment variables are available inside the OpenHands container or process, not only in the host shell. If the model is rejected, use the exact case-sensitive ID from the [model catalog](/models).

## Cap autonomous usage

OpenHands can continue planning, coding, and retrying without another human message. Create a dedicated key, set a hard budget, and allowlist only the models you have tested with its tool loop. RouterPlex enforces the cap server-side, so the agent cannot spend beyond it even if the local process keeps retrying. Increase the cap only after reviewing a representative task's token use and logs.

---

# Keys & budgets
_Platform — Per-key budgets, model allowlists, and promotional-account limits._

Each key can have its own guardrails. The dashboard exposes budgets and model allowlists when you create a key:

- **Budget** — a hard spend cap for the key. Requests fail once it's reached.
- **Allowed models** — restrict a key to specific models (e.g. only cheap ones for a side project).
- **Promotional-account limits** — accounts using only promotional credit are automatically capped at 10 RPM and 50,000 TPM per key until the first paid top-up. Funded PAYG keys have no RouterPlex product-level RPM or TPM default.

Per-request logs (time, model, tokens, cost) are available per key in the dashboard under [API Keys → Logs](https://routerplex.com/dashboard/keys).

## Recommended setup for agents

Coding agents and autonomous tools can burn tokens quickly. For each agent:

1. Create a dedicated key named after the tool (`cursor`, `claude-code`, `openclaw`…).
2. Set a budget you're comfortable losing to a runaway loop.
3. Optionally allowlist only the models that tool should use.

That way one misbehaving tool can never spend more than its own cap, and your usage logs stay attributable per tool.

---

# Billing & credits
_Platform — Prepaid balance, top-ups, and how costs are computed._

Pay-as-you-go by default: you top up a balance (card or crypto), and every request deducts its exact token cost — the same prices shown in the [catalog](https://routerplex.com/models). No subscription is required, and there is no minimum usage commitment; top-ups start at $5. Funded PAYG has no RouterPlex RPM, TPM, or usage-window cap. Optional monthly plans ([Plex Lite, Pro, Max](https://routerplex.com/pricing)) bundle bonus credits worth more than their price with account-wide 4-hour, weekly, and monthly spend windows — per-token prices stay identical.

Available RouterPlex balance — including voucher or earned bonus credit — can fund one non-renewing 30-day plan cycle per account. Recurring plans require card checkout. A balance-funded plan is not a real-money payment and never qualifies a referral payment reward.

- **Account access:** creating an account is free, but there is no universal signup credit. Named partner bonuses unlock only after a genuine qualifying payment and remain subject to campaign limits.
- **Top-ups:** card (min $5) or USDT (min $12) from the [billing page](https://routerplex.com/dashboard/billing).
- **When your balance runs out**, requests stop with a budget error; they resume the moment you top up.
- **Pricing** is per token, per model — input and output are priced separately, exactly as listed in the catalog.

Your live balance, total spend, and per-model breakdown are on the [dashboard](https://routerplex.com/dashboard).