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
- Create a Router One accountSign up →
- Generate a key in Dashboard → API Keys (format sk-xxx)API Keys →
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 / protocol | Base URL | Note |
|---|---|---|
| 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 |
3. Send your first request
All endpoints authenticate with Authorization: Bearer <your key>. Pick your client:
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"}]
}'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)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);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)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.
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"}]
}'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)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:
| Status | Meaning | What to do |
|---|---|---|
| 401 | Invalid or missing API key | Check the Authorization header and the key value. |
| 402 | Insufficient balance | Top up in the dashboard, or raise the key's spend limit. |
| 404 | Wrong path or base URL | Verify the base URL rules from step 2. |
| 429 | Rate limited | Read 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. |
| 5xx | Upstream or gateway error | Retry with backoff; where another healthy route serves the same model, the gateway has already attempted a same-model failover. |
Next steps
One-click CLI setup
Connect Claude Code or Codex with a single command.
API reference
Full request/response schemas for every endpoint.
Streaming responses
SSE chunk format, timeouts and cancellation for long generations.
Tool calling
Declare tools once in the OpenAI-compatible shape and follow the call loop across models.
Structured outputs
JSON mode and JSON Schema via response_format on the same endpoint, and what the gateway rejects before a model is called.
Pricing
Wallet pay-as-you-go plus Pro / Max / Ultra plans, up to 90% off official prices on select models — see what each call costs before you send it.
Model catalog
Model IDs, pricing, context windows, capabilities.
Usage & logs
Per-request model, tokens, cost, latency, and routing.