协议与端点选择
网关同时挂着五个对外端点。选哪一个只取决于你手上的 SDK 或客户端， 与目标模型是哪家厂商的无关——协议不匹配时由网关做转换。
一句话决策
| 你在用 | 用这个端点 | 协议标识 |
|---|---|---|
openai SDK / 大多数三方应用 | POST /v1/chat/completions | openai_chat |
| Codex CLI / Codex Desktop | POST /v1/responses | openai_responses |
anthropic SDK / Claude Code | POST /v1/messages | anthropic_messages |
google-genai SDK | POST /v1beta/models/{model}:generateContent | gemini_native |
| 图片生成 / 编辑 | POST /v1/images/generations POST /v1/images/edits | openai_images |
拿不准就用 /v1/chat/completions。
它的客户端生态最广，字段最稳定，也是覆盖模型最多的一个。
/v1beta/* 已在网关内注册，但边缘反向代理（nginx / APISIX）目前只放行
/v1/、/api/v1/ai/、/api/v1/user/ 等前缀，没有放行
/v1beta。也就是说从公网直连该路径暂时打不通。
需要调 Gemini 系模型时，请改用 /v1/chat/completions——网关会自动做协议转换。
协议是怎么被判定的
网关用四层检测确定客户端说的是哪种协议，命中即停：
URL 路径（置信度 1.0）
路径后缀 /chat/completions → openai_chat；
/responses → openai_responses；
/messages → anthropic_messages；
路径含 :generateContent / :streamGenerateContent → gemini_native。
HTTP 请求头
路径没命中时看特征头。若置信度不足 0.8，会再结合请求体二次确认（来源标记为 mixed）。
JSON 请求体结构
按字段特征识别，例如 messages + max_tokens 组合与 contents 数组的差别。
客户端指纹
以上都无法判定时，用 User-Agent 等客户端线索兜底。
上面五个端点都会命中第一层路径检测（置信度 1.0），协议直接锁死。 后三层只在非标准路径接入时才会用到。
跨协议转换
你用什么协议请求，就用什么协议拿到响应——这是网关对客户端的承诺。 如果目标模型的上游只讲另一种协议，转换在网关内部完成，客户端无感知：
| 你发的 | 上游是 | 网关行为 |
|---|---|---|
| openai_chat | openai_chat | 原样透传，零改写 |
| openai_chat | anthropic_messages | 请求与响应双向转换 |
| openai_chat | openai_responses | 双向转换 |
| anthropic_messages | openai_chat | 双向转换 |
| gemini_native | openai_chat | 双向转换 |
基础对话、多轮上下文、工具调用、流式增量都能无损映射。 但各厂商的专属扩展字段（如某家独有的推理预算、缓存控制、安全设置粒度） 在目标协议里没有对应位置时会被丢弃。对这类字段有硬依赖时，请直接用该厂商的原生协议端点。
平台原生端点
除了五个兼容端点，网关还有一个平台自用的原生端点。它把路由信息放在 Rc-* 请求头里，
适合需要显式指定转发模型、会话 ID、来源应用的场景：
| 请求头 | 说明 |
|---|---|
| Rc-Api-Key | API Key（此端点不读 Authorization） |
| Rc-Model-Id | 平台模型 ID |
| Rc-Forward-Model-Id | 显式指定转发给上游的模型名，覆盖配置映射 |
| Rc-Original-Protocol | 客户端原始协议 |
| Rc-Protocol | 期望的上游协议 |
| Rc-Original-Path | 客户端原始请求路径，供协议检测使用 |
| Rc-Stream | 是否流式 |
| Rc-Session-Id | 会话 ID，用于会话粒度的路由粘性 |
| Rc-App-Id | 来源应用标识，缺省由 User-Agent 推断 |
| Rc-Custom-Id | 自定义业务标识，会写入调用日志 |
/api/v1/ai/chat 是平台内部客户端使用的接口，头约定可能随版本调整。
第三方接入请用 /v1/*，那是对外的稳定契约。
请求体大小上限
所有端点共享同一个请求体上限：100 MiB。超出直接返回
413 / 41301 request body too large，
请求不会进入计费与路由流程。
实践中触碰这个上限的基本只有图片/文件编辑类请求。纯文本对话即使塞满上下文也远达不到—— 真正会先撞上的是模型自身的上下文窗口与输出长度限制，那由上游厂商裁定，网关只负责把上游的错误原样带回。