> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/reference/endpoints · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 端点 · 认证 · 协议互通

本章讲网关对外暴露哪些端点、调用方如何认证、网关的协议互译能力。这些都是**网关自己的事**，不涉及上游 API 的请求体字段规范。

## 端点清单 {#endpoint-list}

### 数据面端点（需访问密钥认证）

调用客户端请求这些端点，网关转发到上游。

| 方法 | 路径 | 用途 |
|------|------|------|
| POST | `/v1/chat/completions` | OpenAI Chat Completions |
| POST | `/v1/responses` | OpenAI Responses API |
| GET/DELETE | `/v1/responses/{id}` | 取回/删除网关存储中的 Responses 轮次（见 [store 参数与响应取回](/zh-CN/reference/clients-and-gateway-diffs.md#store-param)） |
| 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） |
| GET | `/v1/realtime` | 实时会话（WebSocket 升级，OpenAI Realtime 协议），见 [Realtime 实时会话](/zh-CN/reference/realtime.md) |
| 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-passthrough}

- **AWS Bedrock 是上游侧协议**：网关不暴露 Bedrock 形态的客户端端点。客户端用 OpenAI/Anthropic/Gemini 等协议端点（经翻译）或 `/v3/{model}/{*rest}`（透传）访问 Bedrock 模型。
- **`/v3/{model}/{*rest}` 是 identity 透传入口**：当客户端协议与该模型配置的目标协议相同时，请求体原样转发，不做协议转换。

## 认证 {#auth}

调用数据面端点时，网关按以下顺序尝试认证，命中即用：

| 顺序 | 请求头 | 适用客户端 |
|------|--------|-----------|
| 1 | `Authorization: Bearer <你的访问密钥>` | OpenAI SDK、通用 |
| 2 | `x-api-key: <你的访问密钥>` | Anthropic SDK |
| 3 | `x-goog-api-key: <你的访问密钥>` | Gemini SDK |
| 4 | （无以上头） | 匿名兜底：仅当配置了 `anonymous=true` 的访问密钥时匹配 |

要点：

- `Bearer` 前缀大小写不敏感。
- 访问密钥是你在控制台签发的那把（见 [访问密钥与密钥组字段](/zh-CN/reference/access-keys-groups-fields.md)），**不是**上游的 `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。

完整互通矩阵见 [协议互通矩阵](/zh-CN/reference/protocol-matrix.md)。要点：

- 大部分协议对都能双向互译。
- `passthrough` 协议直接转发不翻译。
- 如果某个「客户端协议 → 上游协议」组合没有翻译器，请求返回 **400**（unsupported_feature）。

## 网关特有端点

| 端点 | 说明 |
|------|------|
| `/v1/messages/count_tokens` | Anthropic 风格的 token 计数，不实际调用上游、不计入统计。 |
| `/v3/{model}/{*rest}` | identity 透传，请求体原样转发到模型配置的目标协议。 |
| `/mcp`、`/mcp/sse` | MCP 网关，聚合外部工具服务器，见 [MCP 配置](/zh-CN/reference/mcp-config.md)。 |

## 常见问题

**Q：我的客户端用 OpenAI SDK，但想调 Anthropic 的 Claude 模型，怎么填？**
把客户端 base_url 指向网关 `http://<host>:7890/v1`，`model` 填你在网关里配的模型名（其上游协议是 `anthropic`）。网关自动把 OpenAI 请求翻译成 Anthropic 格式发给上游。具体接法见 [客户端接入与网关差异](/zh-CN/reference/clients-and-gateway-diffs.md)。

**Q：`/v1/models` 返回的模型列表里没有我刚配的模型？**
检查模型是否「启用」、所属上游是否「启用」、模型是否设了 `hide_name`（设了的话不出现在列表，只能用别名访问）。另外，**身份作用域模型映射的源名不会出现在列表里**——列表只列配置中真实存在的模型，映射的 `from` 名（如 `claude-opus-5`）通常是虚构客户端名，不在其中；但客户端直接请求该名字仍能被映射并成功路由。详见 [配置身份作用域模型映射](/zh-CN/howto/configure-identity-model-mapping.md)。

**Q：为什么有些路径用 `/v1beta`，有些用 `/v1`？**
这是上游原生路径差异：Gemini 上游用 `/v1beta`，OpenAI 用 `/v1`。网关保持与上游一致的路径前缀，客户端 SDK 无需改动即可指向网关。

**下一步**：看 [客户端接入与网关差异](/zh-CN/reference/clients-and-gateway-diffs.md) 了解各客户端 SDK 具体怎么连，以及网关和原生 API 有哪些不同；看 [协议互通矩阵](/zh-CN/reference/protocol-matrix.md) 查协议对支持情况；看 [错误码](/zh-CN/reference/error-codes.md) 查状态码与错误体格式。