快速开始

5 分钟完成第一次模型调用——支持 curl、OpenAI SDK、Anthropic SDK 任意一种方式。

1. 获取 API Key

注册 Router One 账号去注册 →
在 Dashboard → API Keys 生成密钥（格式 sk-xxx）API Keys →

2. 选对 Base URL

Router One 提供两个协议面。用哪个 base URL 取决于客户端——这是接入时最常见的错误：

客户端 / 协议	Base URL	说明
OpenAI SDK、Chat Completions、Responses、图片、视频、Codex CLI	`https://api.router.one/v1`	带 /v1
Anthropic SDK、Messages API、Claude Code	`https://api.router.one`	不带 /v1——客户端会自己拼接 /v1/messages

刚配置完就遇到 404（或立刻 401），先检查 base URL：OpenAI 兼容客户端要带 /v1，Claude Code 一定不带。

3. 发送第一个请求

所有端点都用 Authorization: Bearer <你的 Key> 认证。选择你的客户端：

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: true 即可收到 SSE 流——与官方 API 形态一致，以 data: [DONE] 结束。下面的示例沿用第 3 步创建的 client。

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. 选择模型

model 填 "auto" 时，网关会在服务端维护的候选集内按延迟、标价成本和可靠性信号路由；也可以固定填具体模型 ID。ID 区分大小写——从模型目录复制最稳妥。也可以用你的 Key 调用 GET /v1/models 列出可用的模型 ID。大多数不带厂商前缀的官方模型名（如 gpt-5.5、claude-sonnet-5）可作为目录 ID 的别名使用；稳妥起见请复制目录 ID。

查看模型目录 →GET /v1/models 接口参考 →

6. 处理错误

错误使用标准 HTTP 状态码 + JSON body。遇到 5xx 或超时时，网关会自动重试，并在提供同一模型的健康线路间故障转移；客户端仍需处理以下情况：

状态码	含义	处理建议
401	`API Key 无效或缺失`	检查 Authorization 头和 Key 是否复制完整。
402	`余额不足`	到 Dashboard 充值，或调高该 Key 的消费上限。
404	`路径或 base URL 配错`	对照第 2 步的 base URL 规则检查。
429	`请求频率受限`	读 Retry-After 响应头退避重试；code 会指明命中的限额（RATE_LIMIT_EXCEEDED、TOKEN_QUOTA_EXCEEDED、SUBSCRIPTION_QUOTA_EXCEEDED）。需要更高限额联系支持。
5xx	`上游或网关错误`	退避重试；若有其他健康线路提供同一模型，网关已自动尝试过同模型线路故障转移。