快速开始
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"}]
}'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"}]
}'5. 选择模型
model 填 "auto" 时，网关会在服务端维护的候选集内按延迟、标价成本和可靠性信号路由；也可以固定填具体模型 ID。ID 区分大小写——从模型目录复制最稳妥。
6. 处理错误
错误使用标准 HTTP 状态码 + JSON body。5xx/超时时网关会自动在同系列内重试与故障转移；客户端仍需处理以下情况：
| 状态码 | 含义 | 处理建议 |
|---|---|---|
| 401 | API Key 无效或缺失 | 检查 Authorization 头和 Key 是否复制完整。 |
| 402 | 余额不足 | 到 Dashboard 充值，或调高该 Key 的消费上限。 |
| 404 | 路径或 base URL 配错 | 对照第 2 步的 base URL 规则检查。 |
| 429 | 请求频率受限 | 先看 Dashboard → Logs，退避重试；需要更高限额联系支持。 |
| 5xx | 上游或网关错误 | 退避重试；网关已自动尝试过同系列故障转移。 |