Skip to content
Router One
Router One

Quickstart

From zero to your first model response in about five minutes — with curl, the OpenAI SDK, or the Anthropic SDK.

1. Get an API key

2. Pick the right base URL

Router One exposes two protocol surfaces. Which base URL you use depends on the client — this is the single most common setup mistake:

Client / protocolBase URLNote
OpenAI SDK, Chat Completions, Responses, images, videos, Codex CLIhttps://api.router.one/v1With /v1
Anthropic SDK, Messages API, Claude Codehttps://api.router.oneWithout /v1 — the client appends /v1/messages itself
If you get a 404 (or an immediate 401) right after setup, check the base URL first: OpenAI-compatible clients need the /v1 suffix, Claude Code must not have it.

3. Send your first request

All endpoints authenticate with Authorization: Bearer <your key>. Pick your client:

bash
curl https://api.router.one/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.router.one/v1",
    api_key="sk-your-api-key",
)

completion = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello"}],
)
print(completion.choices[0].message.content)
typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.router.one/v1",
  apiKey: "sk-your-api-key",
});

const completion = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(completion.choices[0].message.content);
python
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.router.one",
    auth_token="sk-your-api-key",
)

message = client.messages.create(
    model="auto",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.content[0].text)
typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.router.one",
  authToken: "sk-your-api-key",
});

const message = await client.messages.create({
  model: "auto",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});
console.log(message.content[0].text);

4. Stream responses

Set stream: true to receive an SSE stream — same shape as the official APIs, ending with data: [DONE]. The clients below reuse the setup from step 3.

bash
curl -N https://api.router.one/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "stream": true,
    "messages": [{"role": "user", "content": "Write a short poem"}]
  }'
python
stream = client.chat.completions.create(
    model="auto",
    stream=True,
    messages=[{"role": "user", "content": "Write a short poem"}],
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
typescript
const stream = await client.chat.completions.create({
  model: "auto",
  stream: true,
  messages: [{ role: "user", content: "Write a short poem" }],
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

5. Choose a model

Use model: "auto" to let the gateway route within a server-owned candidate set (latency, posted cost, and reliability signals), or pin an exact model ID. IDs are case-sensitive — copy them from the model catalog. You can also call GET /v1/models with your key to list the IDs available to you. Most official bare names (for example gpt-5.5 or claude-sonnet-5) are accepted as aliases of the catalog ID; copy the catalog ID to be safe.

6. Handle errors

Errors use standard HTTP status codes with a JSON body. The gateway retries and, where another healthy route serves the same model, fails over automatically on 5xx/timeouts; your client still needs to handle these:

StatusMeaningWhat to do
401Invalid or missing API keyCheck the Authorization header and the key value.
402Insufficient balanceTop up in the dashboard, or raise the key's spend limit.
404Wrong path or base URLVerify the base URL rules from step 2.
429Rate limitedRead the Retry-After header and back off; the code says which limit you hit (RATE_LIMIT_EXCEEDED, TOKEN_QUOTA_EXCEEDED, SUBSCRIPTION_QUOTA_EXCEEDED). Contact support to raise limits.
5xxUpstream or gateway errorRetry with backoff; where another healthy route serves the same model, the gateway has already attempted a same-model failover.

Next steps