代理 API 参考
代理 API 是 AISIX 在代理监听端口上暴露给调用方的 API 面。应用可以继续使用已有请求格式，AISIX 负责执行认证、模型解析、流量控制和服务提供方调度。
开源 AISIX 网关和连接到 AISIX Enterprise 或 AISIX Cloud 的 AISIX 网关使用相同的代理 API 面。运维人员配置资源的方式不同，但调用方使用的网关路由相同。AISIX Enterprise 和 AISIX Cloud 还提供预算等控制面功能。
本参考说明 AISIX 的路由行为、认证、模型发现、路由选择和端点约束。代理请求和响应体遵循各路由对应的 API 族；需要完整正文结构时，请参考对应上游 API 文档。
在 AISIX 中，面向客户端的路由路径由 AI API 形态决定，而不是为每个上游自定义路径。应用直接调用受支持的代理端点。请求中的 model 值会选择已配置的 AISIX 模型别名，进而决定请求背后的服务提供方密钥、上游模型、路由行为和流量控制。
代理路由
| 方法 | 路由 | 说明 |
|---|---|---|
GET | /v1/models | 列出该调用方 API Key 可以请求的模型别名，包括虚拟别名。通配符别名不会展示。 |
POST | /v1/chat/completions | OpenAI 兼容 Chat Completions，支持的服务提供方范围最广。 |
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/images/edits | Multipart 图像编辑。解析出的模型必须配置为 provider: "openai"；不支持流式传输。 |
POST | /v1/videos | 提交异步视频生成任务。支持 alibaba、zhipuai（或 zhipu）、volcengine、runwayml（或 runway）和 openai 服务提供方标签。 |
GET | /v1/videos/{video_id} | 轮询视频生成任务。 |
GET | /v1/videos/{video_id}/content | 下载已完成的视频结果。 |
POST | /v1/audio/transcriptions | 语音转文本。转发到上游 OpenAI 风格音频路由。 |
POST | /v1/audio/translations | 语音翻译。转发到上游 OpenAI 风格音频路由。 |
POST | /v1/audio/speech | 文本转语音。转发到上游 OpenAI 风格音频路由。 |
GET | /v1/realtime | OpenAI Realtime WebSocket 中继。要求使用直接模型，并在升级连接前完成身份认证。 |
POST | /v1/rerank | 重排序。仅支持 openai、cohere 和 jina 服务提供方标签。 |
POST | /v1/systemone | TypeSafe System One 格式的决策问题，不支持流式。详见决策模型。 |
POST | /v1/decisions | OpenAI Decisions 格式的决策问题，不支持流式。详见决策模型。 |
POST、GET | /v1/files | 上传文件或列出文件。 |
GET、DELETE | /v1/files/{id} | 获取或删除文件。 |
GET | /v1/files/{id}/content | 下载文件内容。 |
POST、GET | /v1/batches | 创建 Batch 或列出 Batch。 |
GET | /v1/batches/{id} | 获取 Batch。 |
POST | /v1/batches/{id}/cancel | 取消 Batch。 |
POST、GET | /v1/fine_tuning/jobs | 创建 Fine-tuning Job 或列出 Job。 |
GET | /v1/fine_tuning/jobs/{id} | 获取 Fine-tuning Job。 |
POST | /v1/fine_tuning/jobs/{id}/cancel | 取消 Fine-tuning Job。 |
ANY | 已配置的透传路由 | 在每条路由的路径前缀和/或入站 host 白名单上做原生转发，包含网关认证和有限的网关标准化处理。未匹配任何类型端点或显式透传路由的请求会按普通流程返回响应体为空的 404。 |
ANY | /mcp 和 /mcp/ | MCP 网关端点。认证调用方，列出允许访问的工具，并将工具调用路由到已注册的上游 MCP 服务器。 |
ANY | /mcp/{server} | 单服务器 MCP 端点。通常公开原始工具名称；需要避免命名冲突时保留当前服务器前缀。 |
GET、HEAD | /.well-known/oauth-protected-resource | MCP OAuth 受保护资源元数据。仅在 MCP OAuth 发现配置了至少一个启用的 OIDC 提供方时可用。 |
GET、HEAD | /.well-known/oauth-protected-resource/mcp | 同一 MCP OAuth 受保护资源元数据的路径插入形式。 |
POST | /a2a/{agent} | 一个已注册 Agent 的 A2A JSON-RPC 端点。转发前会执行调用方 Key 的 Agent 访问控制。 |
GET | /a2a/{agent}/.well-known/agent-card.json | 获取已注册 Agent 的 Agent Card，并把其服务 URL 重写为网关地址。要求调用方完成身份认证并具有 Agent 访问权限。 |
GET | /livez | 无需认证的 存活探针，用于确认代理监听端口已启动。优雅关闭期间保持返回 200——正在排空的实例是健康的、不应被重启；检测排空状态请使用 /readyz。 |
GET | /readyz | 无需认证的就绪探针。实例正在排空时返回 503。对于使用 etcd 或连接 AISIX Enterprise 或 AISIX Cloud 的网关，首次应用配置之前整个代理监听器都未绑定，因此在那之前该路由是被拒绝而不是返回响应；参见启动与第一个配置。 |
认证
代理请求接受调用方 API Key，或由已配置的 OpenID Connect（OIDC）提供方签发的 JWT。两种方法都会将请求解析到调用方 API Key 资源。解析出的 Key 决定应用哪些模型和工具允许列表、限流，以及其他访问和流量控制；使用 AISIX Enterprise 或 AISIX Cloud 时，还会应用匹配的预算。
调用方 API Key
通过控制面创建调用方 API Key，或在开源 AISIX 网关的 resources.yaml 文件中声明调用方 API Key。
推荐格式：
Authorization: Bearer <plaintext-caller-key>
备用格式：
x-api-key: <plaintext-caller-key>
调用方 API Key 是 AISIX 网关凭证，不是上游服务提供方密钥。
在 x-aisix-api-key 中发送网关 Key
有些调用方需要同时出示两份凭证：网关 Key，以及放在 Authorization 中、给需要认证终端用户的上游使用的自有令牌，例如配置了 auth_type: oauth_delegate 的 MCP 服务器。此时把网关 Key 放在 x-aisix-api-key 中，Authorization 就留给上游令牌：
x-aisix-api-key: <plaintext-caller-key>
Authorization: Bearer <caller-upstream-token>
AISIX 按以下顺序，从第一个出现的请求头中读取网关凭证：
x-aisix-api-keyAuthorization: Bearerx-api-key
由第一个出现的凭证请求头决定，无论其值是什么。AISIX 绝不会回落到下一个请求头：该请求头为空、纯空白或格式错误时，例如 Authorization: Basic … 或 Bearer 后没有 token，请求返回 401，错误信息会指明该请求头，例如 missing or malformed x-aisix-api-key header。即使后面的请求头带有有效的 Key，也是如此。三个请求头都没有出现的请求才算未提供凭证。这类请求同样返回 401，只有在允许匿名调用方的 MCP 入口上才可能走匿名路径。
只要请求带有 x-aisix-api-key，AISIX 就只用它做网关认证，不再读取 Authorization 和 x-api-key。它的值可以是 Key 本身，也可以是 Bearer <key>，校验方式与 Authorization 中的 Key 完全相同；因此当环境配置了 JWT 信任提供方时，它也可以携带 JWT。
Bearer 认证方案名不区分大小写，bearer <key> 和 BEARER <key> 都可以使用，凡是 AISIX 读取 Bearer 凭证的地方都是如此：Authorization、x-aisix-api-key，以及 auth_mode: header_key 透传路由的 auth_header_name。Key 本身区分大小写。
所有 /v1/* 端点、/v1/realtime WebSocket 握手、/mcp、/mcp/{server}、/a2a/{agent} 以及 auth_mode: gateway_key 的透传路由都接受 x-aisix-api-key。auth_mode: header_key 的透传路由只读取其配置的 auth_header_name。在允许匿名调用方的 MCP 入口上，带有 x-aisix-api-key 的请求会像其他带凭证的请求一样进行认证，即使该请求头为空，也绝不会按匿名请求处理。
该请求头属于网关的 x-aisix-* 命名空间，AISIX 永远不会把它转发给上游。1.7.1 及更早版本的网关不读取 x-aisix-api-key。
OIDC 签发的 JWT
以 Bearer Token 形式发送 OIDC 签发的 JWT：
Authorization: Bearer <jwt>
当环境启用了 OIDC 提供方时，AISIX 会验证 JWT 签名和声明，再将外部身份映射到与该信任提供方和主体绑定的调用方 API Key。AISIX 不会内省不透明的 OAuth Token。验证失败的 JWT 会被拒绝，不会被当作调用方 API Key。有关信任提供方配置、身份映射和支持的签名算法，请参阅 JWT 身份认证。
模型发现
GET /v1/models 会返回该调用方 API Key 允许请求的模型别名。直接模型和虚拟模型（多目标、语义和合议）都会展示，因为每一个都是调用方可在 model 中发送的名称。通配符别名不会展示：provider/* 是匹配模式，而不是调用方可以请求的名称。
列出的虚拟别名可以在支持虚拟分发的路由上解析。/v1/realtime 以及 Files、Batches 和 Fine-tuning 路由要求使用直接模型，并会拒绝虚拟别名。
列表遵循调用方 API Key 的模型允许列表。只允许某个多目标别名的 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/images/edits | 解析出的模型必须设置 provider: "openai"，且只接受非流式 multipart 请求。 |
/v1/rerank | 模型的 provider 标签必须为 openai、cohere 或 jina。 |
/v1/systemone、/v1/decisions | 目标所用服务提供方密钥的 provider 字段必须为 typesafe、azure（Microsoft Foundry）、openai 或 openrouter，支持直接模型、路由模型和通配符别名。请求格式与上游不同时会自动转换。 |
/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 用量事件。当批处理查询首次发现批处理已完成时，AISIX 会下载批处理输出文件，按行聚合 Token 用量，并发出带 Token 计数的用量事件。完整工作流请参见 Batch、Files 和 Fine-Tuning。
透传
透传路由会在完成网关认证和调用方 Key 的路由授权后转发原生请求。每条已配置路由服务于自己的路径前缀和/或入站 host 白名单；host 命中的请求在网关自身的路径路由之前分发，路径前缀匹配则在所有一等路由之后运行。上游的状态码和响应体原样返回，text/event-stream 响应增量中继。与一等模型化路由相比，这些路由有意减少网关标准化处理。
透传分发仅通过已配置的透传路由提供。未被任何路由认领的 /passthrough/* 路径会按普通流程返回响应体为空的 404。
MCP 网关
ANY /mcp 会让 AISIX 作为 MCP 服务器暴露给下游 Agent。网关会聚合已注册上游 MCP 服务器的工具，并以带服务器前缀的名称暴露每个工具。
MCP 请求使用与其它代理请求相同的调用方身份认证。只有当解析出的调用方 API Key 的工具访问权限允许请求的工具名称时，工具调用才会被允许。调用方 API Key 限流和安全护栏也可以治理工具调用。在 AISIX Enterprise 和 AISIX Cloud 中，覆盖该 Key 的预算也会生效。
握手和发现方法可以连接并列出调用方可用的工具。工具调用会产生包含 MCP 服务器和工具归因的用量事件，但不会携带 Token 用量。
启用 MCP OAuth 发现后，两个 /.well-known/oauth-protected-resource 路由会发布已配置的 /mcp 资源 URL、启用的 OIDC 签发方 URL、Bearer 请求头支持以及所需 Scope。这些路由无需身份认证，以便客户端发现登录方式。如果未配置 MCP 资源 URL，或没有启用的 OIDC 提供方，则两个路由均返回 404，MCP 身份认证失败也不会包含 OAuth 发现质询。配置方法和 WWW-Authenticate 行为参见 MCP 客户端身份认证。
MCP 端点支持 2025-03-26、2025-06-18、2025-11-25 和 2026-07-28 协议修订版，并为每个客户端分别协商：initialize 握手会回显请求中受支持的修订版；如果请求的版本不受支持，则响应 2025-11-25；2026-07-28 客户端也可以直接从 server/discover 开始。所有协议代际都以无状态方式提供服务，不会发出 Mcp-Session-Id。MCP 协议消息使用 POST；身份认证和指定服务器解析会先执行，二者通过后，GET 和 DELETE 返回 405。MCP-Protocol-Version 请求头是可选的（缺少时表示 2025-03-26）；如果请求头指定了不受支持的修订版，则返回 HTTP 400，并在 JSON-RPC 错误信封中列出受支持的修订版。上游会话的修订版按已注册服务器选择，并且与客户端无关；请参阅协议版本支持。
ANY /mcp/{server} 将网关限定到一台已注册服务器。它的工具列表通常保留上游服务器的原始名称，而不添加聚合端点使用的 <server>__ 前缀。如果原始名称与已注册服务器前缀存在歧义，AISIX 会保留当前服务器前缀，确保公布的名称仍可调用。访问控制仍会评估规范的带前缀工具标识，因此在聚合端点和按服务器划分的端点之间切换客户端不会绕过授权。
A2A 网关
POST /a2a/{agent} 会把 A2A JSON-RPC 请求转发到一台已注册的上游 Agent。AISIX 会验证调用方身份，确认调用方 API Key 允许访问该 Agent，对消息文本运行输入安全护栏，应用请求限流和并发限制，然后转发请求体，不会在不同 A2A 协议版本之间进行转换。网关连接到 AISIX Enterprise 或 AISIX Cloud 时还会应用预算。
GET /a2a/{agent}/.well-known/agent-card.json 会获取上游 Agent Card，并把其中公布的每一个服务 URL——顶层 url 以及 supportedInterfaces 和 additionalInterfaces 中的每一项——重写为网关上的 /a2a/{agent}。Agent Card 路由要求相同的调用方身份认证和 Agent 授权，但不受限流影响。
A2A 调用不会解析模型。其用量事件中的 Token 数由网关统计消息文本得出，并标记为 usage_estimated，成本为零。它们会发出带 A2A 归因的用量指标和请求指标。有关协议行为，请参阅 Agent 网关；有关官方 SDK 客户端示例，请参阅配置 Agent 网关。
请求头与错误
代理响应可能包含 AISIX 专属响应头，用于请求关联、路由、缓存状态、限流状态和重试时机。
错误信封取决于请求格式：OpenAI 兼容路由使用 OpenAI 风格错误信封，Anthropic 风格路由使用 Anthropic 风格信封。
MCP 路由使用 JSON-RPC 信封。A2A 调用会原样返回上游 JSON-RPC 响应，并在上游分发失败时使用 JSON-RPC 错误。身份认证、访问控制和流量控制失败可能会在 A2A 请求转发前返回普通网关 HTTP 错误。透传路由返回上游响应。