Skip to content
Skip to content
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:

  • OpenAI SDK, Chat Completions, Responses, images, videos, Codex CLI

    https://api.router.one/v1

    With /v1

  • Anthropic SDK, Messages API, Claude Code

    https://api.router.one

    Without /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 sort the request into a low, medium or high tier and serve it with a model from that tier's server-owned list, or pin an exact model ID; a request that names a model is served by that model. 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.6-sol 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:

6. Handle errors
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