代理 API 参考
代理 API 是 AISIX 在代理监听端口上暴露给调用方的 API 面。应用可以继续使用已有请求格式，AISIX 负责执行认证、模型解析、流量控制和服务提供方调度。
本参考说明 AISIX 的路由行为、认证、模型发现、路由选择和端点约束。代理请求和响应体遵循各路由对应的 API 族；需要完整 body 结构时，请参考对应上游 API 文档。
在 AISIX 中，面向客户端的路由路径由 AI API 形态决定，而不是为每个上游自定义路径。应用直接调用受支持的代理端点。请求中的 model 值会选择已配置的 AISIX 模型别名，进而决定请求背后的服务提供方密钥、上游模型、路由行为和流量控制。
代理路由
| 方法 | 路由 | 说明 |
|---|---|---|
GET | /v1/models | 列出该调用方 API Key 可见的单目标和合议模型别名。多目标别名不会展示。 |
POST | /v1/chat/completions | OpenAI 兼容聊天补全，支持的服务提供方范围最广。 |
POST | /v1/completions | OpenAI 兼容文本补全。 |
POST | /v1/messages | Anthropic 风格 messages。Anthropic 上游使用原生格式，非 Anthropic 上游通过转换支持。 |
POST | /v1/messages/count_tokens | Anthropic 风格 Token 计数，仅支持 Anthropic 上游目标。 |
POST | /v1/embeddings | 向量嵌入，仅支持 OpenAI 协议族适配器。 |
POST | /v1/responses | OpenAI Responses API。OpenAI 上游直接转发，非 OpenAI 上游通过服务提供方适配器桥接。 |
POST | /v1/images/generations | 图片生成。解析出的模型必须配置为 provider: "openai"。 |
POST、GET | /v1/videos 和 /v1/videos/{video_id} | 异步视频生成：提交任务和轮询状态，并通过 /v1/videos/{video_id}/content 下载结果。支持 alibaba、zhipuai（或 zhipu）、volcengine、runwayml（或 runway）和 openai 服务提供方标签。 |
POST | /v1/audio/transcriptions | 语音转文本。转发到上游 OpenAI 风格音频路由。 |
POST | /v1/audio/translations | 语音翻译。转发到上游 OpenAI 风格音频路由。 |
POST | /v1/audio/speech | 文本转语音。转发到上游 OpenAI 风格音频路由。 |
POST | /v1/rerank | 重排序。仅支持 openai、cohere 和 jina 服务提供方标签。 |
POST、GET、DELETE | /v1/files 和 /v1/files/{id} | OpenAI 兼容文件管理，包括通过 /v1/files/{id}/content 下载文件内容。 |
POST、GET | /v1/batches 和 /v1/batches/{id} | OpenAI 兼容 batch 创建、列表、获取，以及通过 /v1/batches/{id}/cancel 取消 batch。 |
POST、GET | /v1/fine_tuning/jobs 和 /v1/fine_tuning/jobs/{id} | OpenAI 兼容 fine-tuning job 创建、列表、获取，以及通过 /v1/fine_tuning/jobs/{id}/cancel 取消 job。 |
ANY | /passthrough/:provider/*rest | 服务提供方原生转发，包含网关认证和有限的网关标准化处理。 |
ANY | /mcp 和 /mcp/ | MCP 网关端点。认证调用方 API Key，列出允许访问的工具，并将工具调用路由到已注册的上游 MCP 服务器。 |
GET | /livez | 无需认证的存活探针，用于确认代理监听端口已启动。优雅关闭期间返回 503。 |
GET | /readyz | 无需认证的就绪探针。处于 draining、首次配置尚未应用或配置 watch 不新鲜时返回 503。 |
认证
代理请求使用通过 Admin API 或 AISIX 托管控制面创建的调用方 API Key。
推荐格式：
Authorization: Bearer <plaintext-caller-key>
备用格式：
x-api-key: <plaintext-caller-key>
调用方 API Key 是 AISIX 网关凭证，不是上游服务提供方密钥。
模型发现
GET /v1/models 会返回该调用方 API Key 允许访问的单目标和合议模型别名。多目标别名是路由构造，不属于发现列表条目，因此不会暴露。
路由行为
多目标别名会在请求时解析为一个或多个目标模型，适用于 /v1/chat/completions、/v1/messages、/v1/messages/count_tokens 和 /v1/responses。
流式请求会使用第一个被选中的可用目标，不会在流式传输过程中切换目标。非流式请求在遇到可重试的上游失败时，可以故障转移到下一个可用目标。
/v1/responses 可以解析多目标别名。OpenAI 上游目标会直接转发 Responses 请求，非 OpenAI 目标会使用 Responses 桥接。
/v1/messages/count_tokens 可以解析多目标别名，但只会使用 Anthropic 上游目标。如果没有可用的 Anthropic 目标，网关会拒绝该请求。
端点约束
有些路由除了适配器协议族兼容性外，还会施加服务提供方专属约束。
| 路由 | 约束 |
|---|---|
/v1/responses | 对 OpenAI 上游目标使用直接转发，对其它服务提供方目标使用桥接转换。 |
/v1/images/generations | 解析出的模型必须设置 provider: "openai"。 |
/v1/rerank | 模型的 provider 标签必须为 openai、cohere 或 jina。 |
/v1/embeddings | 当解析出的适配器不支持 embeddings 时，返回 501 not_implemented。 |
/v1/audio/* | 转发 OpenAI 风格音频请求，不跨服务提供方协议族做转换。 |
/v1/files、/v1/batches、/v1/fine_tuning/jobs | 支持 OpenAI 兼容服务提供方和 Azure OpenAI。Vertex AI、AWS Bedrock 和 Anthropic 原生 batch 流程使用不同的传输格式和存储模型，因此不由这些路由提供。 |
Files、Batches 和 Fine-Tuning
Files、batches 和 fine-tuning jobs 使用 OpenAI 兼容路由形态。由于部分后续调用只引用 file 或 job ID，AISIX 会在它创建的 ID 中编码路由信息。网关创建的 ID 以 aisix- 开头，后续 file、batch 和 fine-tuning 调用无需再次提供模型提示即可完成路由。
上传文件时，请通过 model multipart 字段、model 查询参数或 x-aisix-model 请求头提供一次路由模型。仍可使用原始服务提供方 ID，但为了确定性路由，请显式传入 model 查询参数或请求头。
文件和 job 管理调用会记录零 Token 用量事件。当 batch retrieve 第一次观察到 batch 完成时，AISIX 会下载 batch 输出文件，按行聚合 Token 用量，并发出带 Token 计数的用量事件。完整工作流请参见 Batch、Files 和 Fine-Tuning。
透传
ANY /passthrough/:provider/*rest 会在完成网关认证和服务提供方解析后，转发服务提供方原生请求。上游服务提供方的状态码和响应体会原样返回。与一等模型化路由相比，该路由有意减少网关标准化处理。
MCP 网关
ANY /mcp 会让 AISIX 作为 MCP 服务器暴露 给下游 Agent。网关会聚合已注册上游 MCP 服务器的工具，并以带服务器前缀的名称暴露每个工具。
MCP 请求使用与其它代理请求相同的调用方 API Key 认证。只有当该 Key 的工具访问权限允许请求的工具名称时，工具调用才会被允许。工具调用请求也可以受调用方 API Key 限流、预算和安全护栏治理。
握手和发现方法可以连接并列出调用方可用的工具。工具调用会产生包含 MCP 服务器和工具归因的用量事件，但不会携带 Token 用量。
请求头与错误
代理响应可能包含 AISIX 专属响应头，用于请求关联、路由、缓存状态、限流状态和重试时机。错误信封取决于请求格式：OpenAI 兼容路由使用 OpenAI 风格错误信封，Anthropic 风格路由使用 Anthropic 风格信封。
MCP 路由使用 JSON-RPC 信封。透传路由返回上游服务提供方响应。