# Router One API 文档

由公开 OpenAPI schema 生成。

Router One 提供 **OpenAI 兼容**的统一模型调用接口。通过智能路由、自动 fallback 和成本优化，让团队安全、可控、低成本地在生产环境运行 LLM 工作负载。

> 直接调 LLM = 黑盒；通过 Router One 调 LLM = 有账本、有轨迹、有管控。



## 快速开始

只需 3 步即可开始使用 Router One API：

### 1. 获取 API Key

登录 [Router One 控制台](https://router.one) 创建项目并生成 API Key（格式 `sk-xxx`）。

### 2. 发送第一个请求

```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": "你好"}]
  }'
```

将 `model` 设为 `auto`，Router One 会根据路由策略自动选择最佳模型。你也可以指定具体模型如 `gpt-4o`、`claude-sonnet-4-20250514` 等。

### 3. 处理响应

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "你好！有什么可以帮你的？" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 }
}
```



## 认证方式

所有 API 请求需要在 `Authorization` Header 中携带 Bearer Token：

```
Authorization: Bearer sk-your-api-key
```

API Key 在 [Router One 控制台](https://router.one) 的项目设置中创建和管理。每个 Key 可绑定独立的预算和 QPS 限制。



## 基础 URL

| 环境 | 地址 |
|------|------|
| **生产环境** | `https://api.router.one` |
| **本地开发** | `http://localhost:8080` |



## 请求格式

- 所有请求使用 **JSON** 格式（`Content-Type: application/json`）
- API 完全兼容 **OpenAI Chat Completions** 格式，现有代码只需替换 `base_url` 即可接入
- 支持流式（SSE）和非流式两种响应模式



## 错误处理

API 返回标准 HTTP 状态码，错误响应包含结构化的错误信息：

```json
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

| 状态码 | 说明 | 处理建议 |
|--------|------|----------|
| `401` | API Key 无效或缺失 | 检查 Authorization Header |
| `402` | 余额不足 | 在控制台充值或调整预算 |
| `429` | 请求频率超限 | 降低请求频率或提升 QPS 限额 |
| `500` | 服务器内部错误 | 稍后重试，如持续出现请联系支持 |

## 基础 URL

- `https://api.router.one` — Production
- `http://localhost:8080` — Local Development
- OpenAI 兼容 API / Codex CLI base URL: `https://api.router.one/v1`
- Claude Code / Anthropic 兼容端点: `https://api.router.one`

## 接口参考

### POST `/v1/chat/completions`

**Create Chat Completion**

- Operation ID: `createChatCompletion`
- 标签: Chat

创建一个聊天补全请求。兼容 OpenAI Chat Completions API 格式，支持流式和非流式响应。

设置 `model` 为 `auto` 时，Router One 将根据路由策略自动选择最佳模型。

#### 请求体

- 必填: 是
- 内容类型: `application/json`

##### 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 模型 ID。设置为 `auto` 时由 Router One 智能路由选择最佳模型，也可指定具体模型如 `gpt-4o`、`claude-sonnet-4-20250514` 等。 Example: `auto` |
| `messages` | array<ChatMessage> | 是 | 聊天消息列表，按时间顺序排列。 |
| `stream` | boolean | 否 | 是否启用流式响应。启用后返回 SSE 事件流。 Default: `false` |
| `temperature` | number | 否 | 采样温度，范围 0-2。较高的值（如 0.8）使输出更随机，较低的值（如 0.2）使输出更确定。 Default: `1` |
| `max_tokens` | integer | 否 | 生成的最大 token 数量。 |
| `top_p` | number | 否 | 核采样参数。模型考虑概率质量前 top_p 的 token 结果。 Default: `1` |
| `stream_options` | object | 否 | 流式响应选项。仅在 `stream: true` 时有效。 |
| `stream_options.include_usage` | boolean | 否 | 是否在流式响应的最后一个 chunk 中包含 usage 信息。 Default: `false` |

##### 示例

**基础请求**

```json
{
  "model": "auto",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ]
}
```

**带系统提示词**

```json
{
  "model": "auto",
  "messages": [
    {
      "role": "system",
      "content": "你是一个有帮助的助手。"
    },
    {
      "role": "user",
      "content": "介绍一下 Router One"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 1024
}
```

**流式响应**

```json
{
  "model": "auto",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "写一首诗"
    }
  ]
}
```

#### 响应

| 状态码 | 说明 | Schema |
|---|---|---|
| `200` | 成功返回聊天补全结果。当 `stream: false` 时返回 JSON 对象；当 `stream: true` 时返回 SSE 事件流。 | ChatCompletionResponse |
| `401` | 认证失败 — API Key 无效或缺失 | ErrorResponse |
| `402` | 余额不足 | ErrorResponse |
| `429` | 请求频率超限 | ErrorResponse |
| `500` | 服务器内部错误 | ErrorResponse |

##### 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 否 | 补全请求的唯一标识符 |
| `object` | chat.completion | 否 | 对象类型，始终为 `chat.completion` |
| `created` | integer | 否 | 创建时间的 Unix 时间戳 |
| `model` | string | 否 | 实际使用的模型 ID |
| `choices` | array<object> | 否 |  |
| `usage` | object | 否 |  |
| `usage.prompt_tokens` | integer | 否 | 输入消耗的 token 数 |
| `usage.completion_tokens` | integer | 否 | 输出消耗的 token 数 |
| `usage.total_tokens` | integer | 否 | 总消耗的 token 数 |

##### 示例

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！有什么我可以帮你的吗？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}
```

### POST `/v1/messages`

**Create Message**

- Operation ID: `createMessage`
- 标签: Chat

创建一个 Claude / Anthropic Messages 兼容请求。适用于 Claude Code 等按 Messages API 形态调用的客户端，支持流式和非流式响应。

#### 请求体

- 必填: 是
- 内容类型: `application/json`

##### 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 模型 ID。设为 `auto` 时由 Router One 自动选择，也可以指定具体模型。 Example: `auto` |
| `messages` | array<AnthropicMessage> | 是 | Claude / Anthropic Messages 格式的对话消息。 |
| `system` | string | 否 | 可选系统提示词。 |
| `max_tokens` | integer | 是 | 最大输出 token 数。 |
| `stream` | boolean | 否 | 是否启用流式响应。 Default: `false` |
| `temperature` | number | 否 | 采样温度，范围 0-2。 Default: `1` |

##### 示例

**基础请求**

```json
{
  "model": "auto",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ]
}
```

**流式响应**

```json
{
  "model": "auto",
  "max_tokens": 1024,
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "写一段产品介绍"
    }
  ]
}
```

#### 响应

| 状态码 | 说明 | Schema |
|---|---|---|
| `200` | 成功返回 Messages API 兼容响应。 | MessageResponse |
| `401` | 认证失败 — API Key 无效或缺失 | ErrorResponse |
| `402` | 余额不足 | ErrorResponse |
| `429` | 请求频率超限 | ErrorResponse |
| `500` | 服务器内部错误 | ErrorResponse |

##### 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 否 | 消息 ID。 |
| `type` | message | 否 | 对象类型。 |
| `role` | assistant | 否 | 回复角色。 |
| `model` | string | 否 | 实际调用的模型 ID。 |
| `content` | array<AnthropicContentBlock> | 否 |  |
| `stop_reason` | string | 否 | 停止原因。 |
| `usage` | object | 否 |  |
| `usage.input_tokens` | integer | 否 | 输入 token 数。 |
| `usage.output_tokens` | integer | 否 | 输出 token 数。 |

##### 示例

```json
{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-20250514",
  "content": [
    {
      "type": "text",
      "text": "你好！有什么我可以帮你的吗？"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 9,
    "output_tokens": 12
  }
}
```

### POST `/v1/responses`

**Create Response**

- Operation ID: `createResponse`
- 标签: Chat

创建一个 OpenAI Responses API 兼容请求。适用于使用 Responses API 的 OpenAI 兼容客户端，支持文本输入、指令和流式响应。

#### 请求体

- 必填: 是
- 内容类型: `application/json`

##### 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 模型 ID。设为 `auto` 时由 Router One 自动选择。 Example: `auto` |
| `input` | string \| array<ResponseInputItem> | 是 |  |
| `instructions` | string | 否 | 可选系统指令。 |
| `stream` | boolean | 否 | 是否启用流式响应。 Default: `false` |
| `temperature` | number | 否 | 采样温度，范围 0-2。 Default: `1` |
| `max_output_tokens` | integer | 否 | 最大输出 token 数。 |

##### 示例

**基础请求**

```json
{
  "model": "auto",
  "input": "用一句话介绍 Router One"
}
```

**带指令**

```json
{
  "model": "auto",
  "instructions": "你是一个简洁的技术文档助手。",
  "input": "解释智能路由。"
}
```

#### 响应

| 状态码 | 说明 | Schema |
|---|---|---|
| `200` | 成功返回 Responses API 兼容响应。 | ResponsesResponse |
| `401` | 认证失败 — API Key 无效或缺失 | ErrorResponse |
| `402` | 余额不足 | ErrorResponse |
| `429` | 请求频率超限 | ErrorResponse |
| `500` | 服务器内部错误 | ErrorResponse |

##### 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 否 | 响应 ID。 |
| `object` | response | 否 | 对象类型。 |
| `created_at` | integer | 否 | 创建时间戳。 |
| `status` | string | 否 | 响应状态。 |
| `model` | string | 否 | 实际调用的模型 ID。 |
| `output_text` | string | 否 | 聚合后的文本输出。 |
| `output` | array<ResponseInputItem> | 否 | 原始输出项。 |
| `usage` | object | 否 |  |
| `usage.input_tokens` | integer | 否 | 输入 token 数。 |
| `usage.output_tokens` | integer | 否 | 输出 token 数。 |
| `usage.total_tokens` | integer | 否 | 总 token 数。 |

##### 示例

```json
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1700000000,
  "status": "completed",
  "model": "gpt-4o",
  "output_text": "Router One 是统一的 LLM API 网关。",
  "output": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Router One 是统一的 LLM API 网关。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 10,
    "total_tokens": 22
  }
}
```

### POST `/v1/images/generations`

**Create Image Generation**

- Operation ID: `createImageGeneration`
- 标签: Images

根据文本提示词生成图片。该接口为同步接口，请求会在图片生成完成后返回；典型耗时 5-30 秒，建议客户端 HTTP 超时设置不少于 60 秒。

响应中的 `data` 数组长度等于实际生成的图片数量，按张数计费。当 `response_format` 为 `url` 时返回的图片链接具有有效期（通常 1 小时），如需长期保存请下载或转存到自有存储。

#### 请求体

- 必填: 是
- 内容类型: `application/json`

##### 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 模型 ID。需选择支持图片生成能力的模型，可在控制台模型市场查询。 Example: `image-default` |
| `prompt` | string | 是 | 图片生成的文本提示词。描述越具体、越富画面感，生成效果通常越好。建议长度不超过 4000 字符。 |
| `n` | integer | 否 | 本次请求生成的图片数量。按张数计费。 Default: `1` |
| `size` | string | 否 | 生成图片的尺寸，格式 `宽x高`（像素）。常用值：`1024x1024`、`512x512`、`1792x1024`、`1024x1792`。具体支持范围取决于所选模型。 Example: `1024x1024` |
| `quality` | standard \| hd | 否 | 图片质量。`hd` 通常分辨率更高、细节更丰富，但生成耗时与计费可能更高。 Default: `standard` |
| `response_format` | url \| b64_json | 否 | 响应中图片的返回方式。<br>- `url`（默认）：返回 CDN URL，有效期约 1 小时，需自行下载或转存<br>- `b64_json`：直接在响应中返回 base64 编码的图片字节，响应体较大但无需额外下载 Default: `url` |

##### 示例

**基础请求**

```json
{
  "model": "image-default",
  "prompt": "一只戴着宇航员头盔的橙色小猫，漂浮在星空背景中，电影感打光"
}
```

**指定尺寸与质量**

```json
{
  "model": "image-default",
  "prompt": "极简主义海报，黄色背景上的黑色咖啡杯",
  "n": 2,
  "size": "1024x1024",
  "quality": "hd",
  "response_format": "b64_json"
}
```

#### 响应

| 状态码 | 说明 | Schema |
|---|---|---|
| `200` | 生成成功 | ImageGenerationResponse |
| `400` | 请求参数错误 — 模型不存在、字段格式不合法或 prompt 缺失 | ErrorResponse |
| `401` | 认证失败 — API Key 无效或缺失 | ErrorResponse |
| `402` | 余额不足 | ErrorResponse |
| `429` | 请求频率超限或 API Key 支出上限已达 | ErrorResponse |
| `500` | 服务器内部错误 | ErrorResponse |
| `503` | 服务暂时不可用 | ErrorResponse |

##### 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `created` | integer | 否 | 生成完成时间的 Unix 时间戳（秒） |
| `data` | array<ImageData> | 否 | 生成的图片列表，长度等于实际生成张数。 |

##### 示例

```json
{
  "created": 1700000000,
  "data": [
    {
      "url": "https://cdn.router.one/img/abc123.png",
      "revised_prompt": "An orange kitten wearing an astronaut helmet, floating in starry space, cinematic lighting"
    }
  ]
}
```

### POST `/v1/videos/generations`

**Submit Video Generation**

- Operation ID: `submitVideoGeneration`
- 标签: Videos

提交视频生成任务。视频生成耗时较长（通常 30 秒到几分钟，取决于模型与时长），因此采用异步任务模式：

1. 调用本接口提交任务，成功响应 `202 Accepted`，返回 `task_id`。
2. 客户端使用 `task_id` 调用 `GET /v1/videos/generations/{task_id}` 轮询状态。
3. 当 `status` 变为 `completed` 时，从响应中读取视频 `url`。

**建议**：轮询间隔不少于 3 秒；不要为整个生成过程设置 HTTP 超时——仅对单次提交/轮询请求设置短超时（如 30 秒）。

**参考图说明**：`image_url` / `image_urls` 字段支持 HTTP(S) URL，单图不超过 20MB。提交后 Router One 会代为下载并安全转存，因此即使图片来自用户上传的临时 URL 也可使用。

#### 请求体

- 必填: 是
- 内容类型: `application/json`

##### 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 模型 ID。需选择支持视频生成能力的模型，可在控制台模型市场查询。 Example: `video-default` |
| `prompt` | string | 是 | 视频生成的文本提示词，描述画面内容、镜头运动、风格等。 |
| `duration` | integer | 否 | 视频时长（秒）。可选值取决于所选模型，常见为 4、5、6、8 秒。 |
| `size` | string | 否 | 视频分辨率。常用值：`720p`、`1080p`。具体支持范围取决于所选模型。 Example: `1080p` |
| `aspect_ratio` | 16:9 \| 9:16 \| 1:1 | 否 | 视频宽高比。`16:9` 适合横屏，`9:16` 适合竖屏短视频，`1:1` 适合社交方图。 |
| `negative_prompt` | string | 否 | 反向提示词，描述希望避免出现的元素。可选。 |
| `image_url` | string (uri) | 否 | 参考图 URL（图生视频场景）。必须为 HTTP(S) 可访问地址，单图不超过 20MB。Router One 会代为下载并安全转存。 |
| `image_urls` | array<string (uri)> | 否 | 多参考图 URL 列表，最多 3 张。每张约束同 `image_url`。 |
| `input_reference` | string | 否 | 模型特定的参考输入标识。仅当所选模型明确要求时使用。 |

##### 示例

**文生视频**

```json
{
  "model": "video-default",
  "prompt": "海浪轻拍沙滩，黄昏的阳光洒在水面上，慢镜头",
  "duration": 5,
  "size": "1080p",
  "aspect_ratio": "16:9"
}
```

**图生视频（单图）**

```json
{
  "model": "video-default",
  "prompt": "镜头缓慢推进，画面中的人物微微转头",
  "duration": 5,
  "image_url": "https://example.com/portrait.jpg"
}
```

**多参考图生视频**

```json
{
  "model": "video-default",
  "prompt": "从场景 A 平滑过渡到场景 B",
  "duration": 8,
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://example.com/scene-a.jpg",
    "https://example.com/scene-b.jpg"
  ]
}
```

#### 响应

| 状态码 | 说明 | Schema |
|---|---|---|
| `202` | 任务已接受，进入排队/生成流程 | VideoSubmitResponse |
| `400` | 请求参数错误 — 模型不存在、参考图下载失败、参数不在模型允许范围内 | ErrorResponse |
| `401` | 认证失败 — API Key 无效或缺失 | ErrorResponse |
| `402` | 余额不足 | ErrorResponse |
| `429` | 请求频率超限或 API Key 支出上限已达 | ErrorResponse |
| `502` | 上游服务异常 | ErrorResponse |

### GET `/v1/videos/generations/{task_id}`

**Get Video Generation Status**

- Operation ID: `getVideoGeneration`
- 标签: Videos

查询视频生成任务状态。`status` 字段取值：

- `pending` — 任务已接受，尚未开始处理
- `processing` — 正在生成，可读取 `progress`
- `completed` — 生成完成，读取 `url` 获取视频文件
- `failed` — 生成失败，读取 `error` 获取原因

建议轮询间隔不少于 3 秒。视频文件 URL 具有有效期（通常 24 小时），如需长期保存请下载或转存到自有存储。

#### 参数

| 字段 | In | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `task_id` | path | string | 是 | 提交接口返回的任务标识，作为不透明字符串原样回传即可，无需解析其内部结构。 |

#### 请求体

该接口未定义 JSON 请求体。

#### 响应

| 状态码 | 说明 | Schema |
|---|---|---|
| `200` | 查询成功 | VideoStatusResponse |
| `400` | task_id 格式无效 | ErrorResponse |
| `401` | 认证失败 — API Key 无效或缺失 | ErrorResponse |
| `404` | 任务不存在或已过期 | ErrorResponse |
| `502` | 上游服务异常 | ErrorResponse |

##### 字段

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `task_id` | string | 是 | 任务标识，与提交时返回的 `task_id` 一致。 |
| `status` | pending \| processing \| completed \| failed | 是 | 任务状态。<br>- `pending`：已接受，未开始处理<br>- `processing`：生成中，可读取 `progress`<br>- `completed`：已完成，读取 `url` 获取视频<br>- `failed`：失败，读取 `error` 获取原因 |
| `url` | string | 否 | 生成的视频 URL。仅当 `status=completed` 时返回。URL 有效期通常为 24 小时，请及时下载或转存。 |
| `error` | string | 否 | 失败原因的人类可读描述。仅当 `status=failed` 时返回。 |
| `progress` | integer | 否 | 生成进度百分比（0-100），部分模型可能不返回。 |

##### 示例

**生成中**

```json
{
  "task_id": "v_8f3a92c1d4e74b6ea0b5f1d29c7e8a01",
  "status": "processing",
  "progress": 45
}
```

**已完成**

```json
{
  "task_id": "v_8f3a92c1d4e74b6ea0b5f1d29c7e8a01",
  "status": "completed",
  "url": "https://cdn.router.one/video/abc123.mp4",
  "progress": 100
}
```

**失败**

```json
{
  "task_id": "v_8f3a92c1d4e74b6ea0b5f1d29c7e8a01",
  "status": "failed",
  "error": "Content policy violation"
}
```

## Trust 与方法说明

- [方法说明](https://router.one/zh/methodology) — 全站公开数字的测量口径。
- [智能路由方法](https://router.one/zh/routing-methodology) — EWMA 延迟、fallback 规则、provider 评分与失败处理。
- [价格方法](https://router.one/zh/pricing-methodology) — 按量 token 账单行不隐藏加价；FX/通道费用在结账时展示。
- [数据留存](https://router.one/zh/data-retention) — Router One 存什么、不存什么、日志保留多久。
- [安全](https://router.one/zh/security) — 传输安全、API Key 处理和上游隔离。
- [可用性与 SLA](https://router.one/zh/sla) — 可用性表述、fallback 行为与企业合同范围。
- [中国延迟实测](https://router.one/zh/benchmarks/china-latency) — 公开 p50 与 timeout 中国访问快照。

## 长版本参考

- https://router.one/llms-full.txt

本页按请求动态生成。Markdown 页面与 HTML 文档不一致时，以 OpenAPI schema 和 HTML 文档为准。