三种 API 协议
Router 数据面同时提供三种协议入口，同一个 API Key 在三种协议下通用。按你的客户端或 SDK 所属生态选择其一即可，能力上没有高低之分。
协议与接入地址
| 协议 | 接入地址（base URL） | 实际端点 | 鉴权头 |
|---|---|---|---|
| Anthropic Messages | https://routerapi.<域名>/anthropic | POST /anthropic/v1/messages | x-api-key: <Key>（或 Authorization: Bearer） |
| OpenAI Chat Completions | https://routerapi.<域名>/v1 | POST /v1/chat/completions | Authorization: Bearer <Key>（或 x-api-key） |
| OpenAI Responses | https://routerapi.<域名>/v1 | POST /v1/responses | Authorization: Bearer <Key>（或 x-api-key） |
表中为地址格式示例，实际域名以控制台「快速接入」页展示为准。
怎么选
- Claude Code、Cline、Roo Code 等 Anthropic 生态编程工具 → Anthropic Messages 协议。这类工具通常只需要设置
ANTHROPIC_BASE_URL与ANTHROPIC_AUTH_TOKEN两个环境变量。 - OpenAI SDK、LangChain、绝大多数聊天客户端与应用平台（Cherry Studio、Dify 等）→ OpenAI Chat Completions 协议。这是最通用的选择。
- 使用 OpenAI 新一代 Responses API 的应用（如 Codex）→ OpenAI Responses 协议。
通道原生支持你所用的协议时请求原样透传，协议特有能力的保真度最好；不支持的协议由路由层自动翻译，基础对话能力不受影响。因此优先选与你客户端生态一致的协议即可。
跨协议兼容矩阵
模型实际命中的通道可能使用另一种协议。三种调用协议均可落到三种通道；同协议保持原样透传，跨协议按下表转换。模型池、单通道、会话粘性和故障重试遵循同一转换规则。
| 调用方协议 \ 通道协议 | Chat Completions | Responses | Anthropic Messages |
|---|---|---|---|
| Chat Completions | 原样透传 | 文本 / function tools 转换 | 文本 / function tools 转换 |
| Responses | 文本 / function tools 转换 | 原样透传 | 文本 / function tools 转换 |
| Anthropic Messages | 文本 / function tools 转换 | 文本 / function tools 转换 | 原样透传 |
跨协议支持：
- 普通文本、
system/instructions、temperature、top_p与输出 token 上限。 - function 工具声明、工具选择（自动 / 禁止 / 必须 / 指定函数）与并行调用。
- 历史工具调用、工具结果及其 call ID 的对应关系；第二轮请求请按所用协议回放这些字段。
- 非流式与 SSE 流式工具调用、参数分片、文本与工具混合；usage 按实际通道响应计量。
Anthropic 的 thinking 与 context_management 按目标通道区分处理：
- 落到 Chat 通道时，默认移除顶层
thinking、context_management以及历史消息中的thinking/redacted_thinking块，普通文本和 function tools 继续转换，不会仅因这些字段报错；移除的字段会记录在调用明细中。context_management移除后仅退化为不在上游启用服务端上下文编辑，正文与工具调用不受影响。 - 通道开启「严格透传模式」后，上述可携带字段和完整内容块会在必要的协议结构转换中保留，交由上游校验；上游不认识时可能返回其自身的 400 错误。严格模式不保证跨协议请求字节不变，也不保证上游接受这些字段。
- 原生 Anthropic 通道保留这些字段；跨到 Responses 时不支持
thinking与context_management，会明确报错。
以下能力需要同协议通道，跨协议时不能保证等价：
- Responses 的服务端会话状态（如
previous_response_id）、store、truncation与内建工具（如web_search、file_search）。 - Anthropic 的
context_management与thinking跨到 Responses。 - 供应商私有的内容块、内建工具输出或其他无通用中间表示的字段。多模态、推理字段等是否可用取决于具体通道；需要完整保真时应使用与通道相同的协议。
不能保真且不允许按上述规则降级的请求返回 501，错误类型为 unsupported_protocol_feature，并指出不支持的字段；这不是通道故障，不会为此切换通道重试。请移除该字段、改用同协议通道，或联系平台调整通道配置。网关不会把内建工具静默替换成普通函数，也不会伪造工具执行结果——工具由调用方应用执行。
消息字段兼容
多轮对话中，部分客户端会把模型返回的思考过程等附加字段回放进历史消息。网关对消息体内已识别的附加字段（如 reasoning_content）原样保留；无法识别的附加字段会被静默移除，不会因此报错——不同客户端生态的写法差异不影响接入。
被移除的字段名会记录在每次调用的观测数据中，运营侧可查询。若你在调试中需要网关严格暴露这类字段（让上游直接报错以便定位客户端行为），请联系运营方对该通道开启透传模式。
流式请求
三种协议都支持流式（SSE）：OpenAI 协议在请求体中带 "stream": true；Anthropic 协议带 "stream": true。网关注层面不做缓冲，token 逐块到达。
流式响应会携带本次调用的 token 用量：OpenAI 协议在流的末尾返回一个 usage 数据块（choices 为空数组的 data 行），Anthropic 协议在 message_delta 事件中携带。主流 SDK 会自动处理；自行解析 SSE 的客户端请注意跳过该数据块。用量数据同时用于计费与用量统计。
路由决策响应头
每次调用的响应头会携带本次的路由决策信息（x-veyra- 前缀），可用于排查与观测：
| 响应头 | 含义 |
|---|---|
x-veyra-routing-model | 实际落地执行本次请求的模型 |
x-veyra-routing-type | 路由形态（智能路由池 / 直调模型） |
x-veyra-routing-reason | 本次选路原因（如权重分配 / 健康切换 / 故障升级） |
x-veyra-routing-tier | 命中的路由档位 |
x-veyra-routing-score | 选路评分（4 位小数） |
x-veyra-routing-escalated | 是否因上游故障升级到备用通道（true/false） |
x-veyra-cls-type / x-veyra-cls-tier | 智能路由池调用的任务分类结果（任务类型 / 难度档，仅分类器介入时下发） |
x-veyra-cls-confidence / x-veyra-cls-mode | 分类置信度 / 分类模式（同上） |
不需要这些信息的客户端可以直接忽略，不影响任何功能。
错误处理
401：Key 缺失或无效——检查鉴权头与 Key 是否已删除429：超出 Key 限额——总额模式用完即止（可在控制台清空已用量复位）；周期模式（日/周/月）响应带Retry-After头，到窗口重置点自动恢复5xx：上游供应商故障——路由层已自动重试与切换备用通道，仍失败时请稍后重试或联系官方支持