# Router One API 协议兼容性事实

Last updated: 2026-09-11

- 产品：Router One
- 类别：统一 LLM API 网关（LLM API Gateway / AI Model Router）
- 适用范围：网关在每个端点上接受哪些协议格式与请求特性、在调用任何模型之前会拒绝什么；逐模型的能力标记以目录为准，不在本页
- OpenAI 兼容 base URL：https://api.router.one/v1
- Anthropic 兼容 / Claude Code base URL：https://api.router.one
- API Key 格式：sk-rk-...；下列所有端点都以 Authorization: Bearer 方式传递——Anthropic SDK 为 api_key 发送的 x-api-key 头同样被接受（Claude Code 通过 ANTHROPIC_AUTH_TOKEN 以 Bearer 发送）

## 端点

- POST https://api.router.one/v1/chat/completions ：OpenAI Chat Completions 协议格式；服务目录中的全部对话模型
- POST https://api.router.one/v1/messages ：Anthropic Messages 协议格式（Claude Code 使用的路径）；服务当前目录中的 Claude 系列与 DeepSeek ID（deepseek-v4.1-flash 与 deepseek-v4-flash，2026-09-10 上架）
- POST https://api.router.one/v1/responses ：OpenAI Responses 协议格式（Codex CLI 使用的路径）；当前目录中的 GPT 系列与 DeepSeek ID 原生服务 —— 权威清单是「详情页列出 POST /v1/responses 的模型」
- POST https://api.router.one/v1/images/generations ：图像生成模型（按张计价，见定价事实）
- POST https://api.router.one/v1/images/edits ：图生图编辑，适用于目录中输入模态含 image 的图像模型；参考图以文件上传，所以请求是 multipart/form-data（多张就重复 image 字段，单张不超过 25 MB），响应结构与按张计价均与图像生成一致
- POST https://api.router.one/v1/videos/generations 与 GET https://api.router.one/v1/videos/generations/{task_id} ：视频生成模型；先提交，再按 task id 轮询——时长与分辨率按模型固定，不由单次请求指定
- 端点规则：从 https://router.one/zh/models 进入的每个模型详情页列出该模型实际服务的端点；https://router.one/zh/models.md 是机器可读的权威来源，优先于上面的系列简写
- 不承诺跨协议：模型只能在其详情页列出的端点上调用；Router One 不对外宣称任何协议格式之间的转换路径
- 端点用错时的拒绝：把模型 ID 发到不服务它的端点，会在调用任何模型之前收到 HTTP 400 invalid_request_error，消息里点明应该走哪条路径（"model '<id>' must be called via ..."）

## Responses API（POST /v1/responses）

- 该端点服务的所有模型均接受：文本与多部件输入、instructions、流式输出、function 工具
- 原生服务的 Responses 模型（当前目录中的 GPT 系列与 DeepSeek ID）额外接受并按该模型标准 token 费率计费：custom 工具；previous_response_id、conversation、prompt 引用；hosted 工具（file_search、code_interpreter、computer_use、mcp、web_search）；file_id 与 file_url 输入部件；全部 service_tier 取值
- hosted 工具边界：hosted 工具字段在端点上被接受并计量 —— Router One 自身不执行工具（见下方信任边界）
- 在调用任何模型之前以 HTTP 400 invalid_request_error 拒绝：image_generation 工具与 image_generation_call 输入项（请改用 POST /v1/images/generations），以及 background: true
- 同样在调用任何模型之前以 HTTP 400 invalid_request_error 拒绝：Claude 家族的模型 ID——该端点不服务它们（"model '<id>' must be called via /v1/messages or /v1/chat/completions"）

## Messages API（POST /v1/messages）

- 该端点服务的所有模型（当前目录中的 Claude 系列与 DeepSeek ID）均接受：文本与多部件输入、流式输出，以及 Claude Code 发送的客户端工具定义（带 input_schema 的 tools、tool_choice；tool_use / tool_result 块可完整往返）
- 被接受并按该模型标准 token 费率计量的 Anthropic 服务端工具：web_search，以及 code_execution（含 bash 与 text editor 子工具、跨轮次容器复用）—— Router One 自身不执行工具（见下方信任边界）
- 在调用任何模型之前以 HTTP 400 invalid_request_error 拒绝：web_fetch 服务端工具、mcp_toolset 与 mcp_servers 字段（MCP connector）
- 错误响应使用 Anthropic 外层结构 {"type":"error","error":{type,message,code},"request_id"}
- 请求头：anthropic-beta 头按原样透传，被接受的服务端工具都不要求它；被拒绝的服务端工具或 MCP 字段返回上述 400，错误信息会点名被拒绝的特性

## Chat Completions 上的托管搜索（google/gemini-3-flash）

- 适用范围：仅 google/gemini-3-flash 这一个 ID，且仅在 POST /v1/chat/completions 上；其他 ID 不做此处理——tools 数组按原样转发，模型不接受的托管搜索工具类型会被该模型的路由以 400 拒绝
- 请求写法：tools: [{"type": "google_search"}] 加 tool_choice: "auto"（由模型决定是否搜索），或 web_search_options: {}；tool_choice: "none" 关闭搜索；流式与非流式均可用，stream_options: {"include_usage": true} 有效
- 响应：模型实际引用的来源以 OpenAI 风格的 url_citation annotations 返回——非流式在 choices[0].message.annotations，流式在 choices[0].delta.annotations；重复与无效 URL 会被去掉，来源页面的 HTML 不会注入回答正文
- 计费：按该模型公示的 token 单价——搜索上下文计入输入 token，模型推理计入输出 token；没有单独的搜索计价行，也不承诺每次 tool_choice: "auto" 的请求都会真的发起搜索
- 2026-09-09 上线；请求示例见工具调用指南（https://router.one/zh/llm-tool-calling）与 Gemini 国内接入页（https://router.one/zh/gemini-api-china）

## 流式、工具调用、视觉

- 流式（stream: true）、工具调用与视觉输入是目录中公开的逐模型能力标记；https://router.one/zh/models.md 是权威来源，本页不逐个列出模型
- 流式指南：https://router.one/zh/llm-streaming
- 工具调用指南：https://router.one/zh/llm-tool-calling

## 结构化输出（POST /v1/chat/completions）

- response_format.type = json_object 与 response_format.type = json_schema 均接受
- 信封校验在网关完成、早于任何模型调用：json_schema 请求在缺少 response_format.json_schema（"response_format.json_schema is required when response_format.type is json_schema"）、缺少 json_schema.name（"response_format.json_schema.name is required"）或缺少 json_schema.schema（"response_format.json_schema.schema is required"）时返回 HTTP 400 invalid_request_error；strict 与 description 可选
- 合法的 response_format 对象原样转发给模型；schema 是否被强制执行由模型决定、以模型支持为前提 —— Router One 不会按 schema 校验响应正文
- schema 方言故障转移：当某条模型线路因 $defs 或 $ref 拒绝 schema 时，网关把它视为该线路特有的 400，并故障转移到同一模型的下一条候选线路
- 指南：https://router.one/zh/llm-structured-outputs

## -thinking 模型 ID 的思考默认值

- 适用范围：以 -thinking 结尾的目录 ID——当前为 anthropic/claude-opus-4.6-thinking、anthropic/claude-opus-4.7-thinking 与 anthropic/claude-sonnet-4.6-thinking；哪些 ID 带该后缀以 https://router.one/zh/models.md 为准
- 默认行为：请求这类 ID 时若未带 thinking 字段，模型会以思考开启的方式被调用——需要网关自行补字段时，补的是 thinking: {"type": "adaptive"}（由模型决定思考量）——调用方不加字段也能拿到思考输出；规则只看 -thinking 后缀，不带后缀的 ID（anthropic/claude-opus-4.6、anthropic/claude-sonnet-4.6 等）不会被加上任何 thinking 设置
- 显式值优先：请求已带 thinking 值时网关不再补充任何 thinking 设置，{"type": "disabled"} 原样转发。Opus 4.7 这一代的 ID（当前为 anthropic/claude-opus-4.7-thinking）只接受自适应思考：旧式 {"type": "enabled", "budget_tokens": N} 会在调用前被改写为 {"type": "adaptive"}，并去掉 temperature / top_p / top_k；其他 -thinking ID 的值原样转发，模型是否接受由模型决定
- 两个端点同一规则：POST /v1/messages 上作用于按原样发送的 Anthropic 请求体，流式与非流式相同；POST /v1/chat/completions 上作用于 JSON 请求体顶层的 thinking 字段，对象结构相同；OpenAI 风格的 reasoning_effort 字段不会被转换为 Claude 系列的 thinking 设置
- 输出位置：模型返回的 thinking 块在 POST /v1/messages 上以 thinking 内容块原样返回，在 POST /v1/chat/completions 上位于消息的 reasoning_content 字段；按该模型的输出单价计费（见下方 token 计量）

## token 计量

- 推理 / 思考 token：思考类 / 推理类模型（例如 claude-*-thinking 变体）产生的推理输出按该模型公示的输出单价计费，并计入该请求的总 token 数；不存在单独的推理计价行（见定价事实）
- 空正文但有计量的回复：回复里没有 content、没有工具调用、也没有 refusal，但 usage 不为零时，按 HTTP 200 原样返回，结算依据是该响应报告的 usage——不重试也不换候选，因此客户端应读取 finish_reason、refusal 与 usage，而不是自动重试；完全没有 usage 的空响应按上游故障处理（HTTP 502，尝试下一个候选）

## 不包含

- 网关侧响应缓存，以及上述端点行之外的任何协议格式转换。直接 API 调用与 Playground 历史的数据处理边界见 https://router.one/zh/data-retention
- 信任边界：Router One 负责模型调用、路由、计费与可观测；它不是 agent 编排运行时、工作流引擎、工具执行器、向量数据库或应用框架

## 规范页面

- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- Codex CLI 与 Responses API：https://router.one/zh/codex-responses-api
- 工具调用：https://router.one/zh/llm-tool-calling
- 流式输出：https://router.one/zh/llm-streaming
- 结构化输出：https://router.one/zh/llm-structured-outputs
- 文档：https://router.one/zh/docs （markdown：https://router.one/zh/docs.md ）
- 模型目录：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 集成事实：https://router.one/zh/facts/integrations.md
- 定价事实：https://router.one/zh/facts/pricing.md
- 公司事实：https://router.one/zh/facts/company.md