代理 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 | /v1/audio/transcriptions | 语音转文本。转发到上游 OpenAI 风格音频路由。 |
POST | /v1/audio/translations | 语音翻译。转发到上游 OpenAI 风格音频路由。 |
POST | /v1/audio/speech | 文本转语音。转发到上游 OpenAI 风格音频路由。 |
POST | /v1/rerank | 重排序。仅支持 openai、cohere 和 jina 服务提供方标签。 |
ANY | /passthrough/:provider/*rest | 服务提供方原生转发，包含网关认证和有限的网关标准化处理。 |
GET | /livez | 无需认证的存活探针，用于确认代理监听端口已启动。 |
认证
代理请求使用通过 Admin API 或 AISIX Cloud 创建的调用方 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 风格音频请求，不跨服务提供方协议族做转换。 |
透传
ANY /passthrough/:provider/*rest 会在完成网关认证和服务提供方解析后，转发服务提供方原生请求。上游服务提供方的状态码和响应体会原样返回。与一等模型化路由相比，该路由有意减少网关标准化处理。
请求头与错误
代理响应可能包含 AISIX 专属响应头，用于请求关联、路由、缓存状态、限流状态和重试时机。错误信封取决于请求格式：OpenAI 兼容路由使用 OpenAI 风格错误信封，Anthropic 风格路由使用 Anthropic 风格信封，透传路由返回上游服务提供方响应。