端点 · 认证 · 协议互通
本章讲网关对外暴露哪些端点、调用方如何认证、网关的协议互译能力。这些都是网关自己的事，不涉及上游 API 的请求体字段规范。
端点清单
数据面端点（需访问密钥认证）
调用客户端请求这些端点，网关转发到上游。
| 方法 | 路径 | 用途 |
|---|---|---|
| POST | /v1/chat/completions | OpenAI Chat Completions |
| POST | /v1/responses | OpenAI Responses API |
| POST | /v1/messages | Anthropic Messages |
| POST | /v1/messages/count_tokens | Anthropic token 计数 |
| POST | /v1beta/models/{*rest} | Gemini :generateContent / :streamGenerateContent / :countTokens |
| POST | /v1/models/{*rest} | Gemini v1 稳定别名（上游仍按 v1beta 构造） |
| POST/GET | /v1beta/cachedContents、/v1beta/cachedContents/{id} | Google 上下文缓存（创建/列表/读/改/删） |
| POST | /v1/images/generations | 图像生成 |
| POST | /v1/images/edits | 图像编辑（multipart 上传） |
| POST | /v1/embeddings | 文本向量 |
| POST | /v1/rerank、/v2/rerank | 重排序（兼容 Jina/Cohere/vLLM） |
| POST | /v1/audio/transcriptions | 语音转文本（ASR） |
| POST | /v1/audio/translations | 语音转英文 |
| POST | /v1/audio/speech | 文本转语音（TTS） |
| POST/GET | /v1/services/{*rest} | DashScope 统一服务（文本/多模态/图像/视频/向量/重排/ASR）；GET 轮询异步任务 /v1/services/{model}/tasks/{task_id} |
| POST/GET | /v3/{model}/{*rest} | identity 透传：客户端协议 == 目标协议，请求体原样转发 |
| POST | /mcp | MCP JSON-RPC 2.0（Streamable HTTP） |
| GET | /mcp/sse | MCP SSE 传输 |
| GET | /v1/models | 模型列表（OpenAI 风格） |
| GET | /v1beta/models | 模型列表（Gemini 风格） |
路径里的
{*rest}表示匹配后续任意路径段。例如/v1beta/models/gemini-2.0-flash:generateContent。
公共端点（无需访问密钥）
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | / | 模型列表页（HTML） |
| GET | /health、/healthz | 存活探针，恒 200 |
| GET | /ready | 就绪探针，不健康/排空时 503 |
| GET | /metrics | Prometheus 指标，需配置 metrics_auth_token 后用 Bearer 访问，未配置则 403 |
关于 AWS Bedrock 与透传
- AWS Bedrock 是上游侧协议：网关不暴露 Bedrock 形态的客户端端点。客户端用 OpenAI/Anthropic/Gemini 等协议端点（经翻译）或
/v3/{model}/{*rest}（透传）访问 Bedrock 模型。 /v3/{model}/{*rest}是 identity 透传入口：当客户端协议与该模型配置的目标协议相同时，请求体原样转发，不做协议转换。
认证
调用数据面端点时，网关按以下顺序尝试认证，命中即用：
| 顺序 | 请求头 | 适用客户端 |
|---|---|---|
| 1 | Authorization: Bearer <你的访问密钥> | OpenAI SDK、通用 |
| 2 | x-api-key: <你的访问密钥> | Anthropic SDK |
| 3 | x-goog-api-key: <你的访问密钥> | Gemini SDK |
| 4 | （无以上头） | 匿名兜底：仅当配置了 anonymous=true 的访问密钥时匹配 |
要点：
Bearer前缀大小写不敏感。- 访问密钥是你在控制台签发的那把（见 访问密钥与密钥组字段），不是上游的
sk-...。 - 密钥格式无强制前缀，任意字符串均可。
- 带了一个无效密钥、且配置了匿名密钥时，请求会落到匿名分支（等同没带密钥）。
- 没有有效密钥、也没有匿名密钥 → 401 Unauthorized。
- 未匹配的代理路径也返回 401（而非 404），避免未认证请求探测路由。
协议互通能力
网关的核心能力之一：客户端用的协议和上游用的协议可以不同。
例如：
- 你的客户端用 Anthropic SDK（请求
/v1/messages），但上游是 OpenAI——网关把 Anthropic 请求体翻译成 OpenAI 格式发给上游，再把 OpenAI 响应翻译回 Anthropic 格式。 - 你的客户端用 OpenAI SDK，但上游是 Gemini 或 AWS Bedrock——同理互译。
支持的协议有 12 种：OpenAI Chat、OpenAI Response、OpenAI Images、OpenAI Embeddings、OpenAI Audio、OpenAI Rerank、Anthropic、Google、AWS Bedrock Converse、AWS Bedrock InvokeModel、Alibaba DashScope、Passthrough。
完整互通矩阵见 协议互通矩阵。要点：
- 大部分协议对都能双向互译。
passthrough协议直接转发不翻译。- 如果某个「客户端协议 → 上游协议」组合没有翻译器，请求返回 400（unsupported_feature）。
网关特有端点
| 端点 | 说明 |
|---|---|
/v1/messages/count_tokens | Anthropic 风格的 token 计数，不实际调用上游、不计入统计。 |
/v3/{model}/{*rest} | identity 透传，请求体原样转发到模型配置的目标协议。 |
/mcp、/mcp/sse | MCP 网关，聚合外部工具服务器，见 MCP 配置。 |
常见问题
Q：我的客户端用 OpenAI SDK，但想调 Anthropic 的 Claude 模型，怎么填？ 把客户端 base_url 指向网关 http://<host>:7890/v1，model 填你在网关里配的模型名（其上游协议是 anthropic）。网关自动把 OpenAI 请求翻译成 Anthropic 格式发给上游。具体接法见 客户端接入与网关差异。
Q：/v1/models 返回的模型列表里没有我刚配的模型？ 检查模型是否「启用」、所属上游是否「启用」、模型是否设了 hide_name（设了的话不出现在列表，只能用别名访问）。另外，身份作用域模型映射的源名不会出现在列表里——列表只列配置中真实存在的模型，映射的 from 名（如 claude-opus-5）通常是虚构客户端名，不在其中；但客户端直接请求该名字仍能被映射并成功路由。详见 配置身份作用域模型映射。
Q：为什么有些路径用 /v1beta，有些用 /v1？ 这是上游原生路径差异：Gemini 上游用 /v1beta，OpenAI 用 /v1。网关保持与上游一致的路径前缀，客户端 SDK 无需改动即可指向网关。
下一步：看 客户端接入与网关差异 了解各客户端 SDK 具体怎么连，以及网关和原生 API 有哪些不同；看 协议互通矩阵 查协议对支持情况；看 错误码 查状态码与错误体格式。