Proxy API Reference
The proxy API is the caller-facing surface AISIX exposes on the proxy listener. Applications send requests in the format they already use, and AISIX applies authentication, model resolution, traffic controls, and provider dispatch.
The same proxy surface is served by an open-source AISIX gateway and by an AISIX gateway connected to AISIX Cloud. How operators configure resources differs, but the gateway routes callers use do not. AISIX Cloud additionally supplies control-plane features such as budgets.
This reference covers AISIX route behavior, authentication, model discovery, routing, and endpoint constraints. Proxy request and response bodies follow the API family used by each route, so use the upstream API reference when you need the full body schema.
In AISIX, client-facing route paths are fixed by the AI API shape rather than custom-defined for each upstream. Applications call the supported proxy endpoints directly. The request model value selects the configured AISIX model alias, which decides the provider key, upstream model, routing behavior, and traffic controls behind the request.
Proxy Routes
| Method | Route | Description |
|---|---|---|
GET | /v1/models | List the model aliases the caller API key may request, virtual aliases included. Wildcard aliases are excluded. |
POST | /v1/chat/completions | OpenAI-compatible chat completions. Broadest provider support. |
POST | /v1/completions | OpenAI-compatible text completions. |
POST | /v1/messages | Anthropic-style messages. Native for Anthropic upstreams; translated for non-Anthropic upstreams. |
POST | /v1/messages/count_tokens | Anthropic-style token counting. Only Anthropic-backed targets are supported. |
POST | /v1/embeddings | Vector embeddings. OpenAI-family adapter support only. |
POST | /v1/responses | OpenAI Responses API. OpenAI upstreams are forwarded directly, and non-OpenAI upstreams are bridged through the provider adapter. |
POST | /v1/images/generations | Image generation. Requires the resolved model to have provider: "openai". |
POST | /v1/videos | Submit an asynchronous video-generation task. Supports the alibaba, zhipuai (or zhipu), volcengine, runwayml (or runway), and openai provider labels. |
GET | /v1/videos/{video_id} | Poll a video-generation task. |
GET | /v1/videos/{video_id}/content | Download a completed video result. |
POST | /v1/audio/transcriptions | Speech-to-text transcription. Forwards to upstream OpenAI-style audio routes. |
POST | /v1/audio/translations | Speech translation. Forwards to upstream OpenAI-style audio routes. |
POST | /v1/audio/speech | Text-to-speech. Forwards to upstream OpenAI-style audio routes. |
GET | /v1/realtime | OpenAI Realtime WebSocket relay. Requires a direct model and authenticates before upgrading the connection. |
POST | /v1/rerank | Reranking. Supports openai, cohere, and jina provider labels only. |
POST, GET | /v1/files | Upload a file or list files. |
GET, DELETE | /v1/files/{id} | Retrieve or delete a file. |
GET | /v1/files/{id}/content | Download file content. |
POST, GET | /v1/batches | Create a batch or list batches. |
GET | /v1/batches/{id} | Retrieve a batch. |
POST | /v1/batches/{id}/cancel | Cancel a batch. |
POST, GET | /v1/fine_tuning/jobs | Create a fine-tuning job or list jobs. |
GET | /v1/fine_tuning/jobs/{id} | Retrieve a fine-tuning job. |
POST | /v1/fine_tuning/jobs/{id}/cancel | Cancel a fine-tuning job. |
ANY | /passthrough/:provider/*rest | Provider-native forwarding with gateway authentication and limited gateway normalization. |
ANY | /mcp and /mcp/ | MCP gateway endpoint. Authenticates the caller, lists allowed tools, and routes tool calls to registered upstream MCP servers. |
ANY | /mcp/{server} | Single-server MCP endpoint. Normally exposes original tool names; retains the current server prefix when needed to avoid a naming collision. |
POST | /a2a/{agent} | A2A JSON-RPC endpoint for one registered agent. Enforces the caller key's agent access before forwarding. |
GET | /a2a/{agent}/.well-known/agent-card.json | Fetch the registered agent's card with its service URL rewritten to the gateway. Requires caller authentication and agent access. |
GET | /livez | Unauthenticated liveness probe. Confirms the proxy listener is up. Returns 503 during graceful shutdown. |
GET | /readyz | Unauthenticated readiness probe. Returns 503 while draining or before the first configuration apply. |
Authentication
Proxy requests accept either a caller API key or a JWT issued by a configured OpenID Connect (OIDC) provider. Both methods resolve the request to a caller API key resource. The resolved key determines which model and tool allowlists, rate limits, and other access and traffic controls apply. In AISIX Cloud, matching budgets also apply.
Caller API Key
Create caller API keys through the AISIX Cloud control plane or declare them in an open-source AISIX gateway's resources.yaml file.
Preferred form:
Authorization: Bearer <plaintext-caller-key>
Fallback form:
x-api-key: <plaintext-caller-key>
The caller API key is an AISIX gateway credential. It is not an upstream provider key.
OIDC-Issued JWT
Send an OIDC-issued JWT as a bearer token:
Authorization: Bearer <jwt>
When the environment has an enabled OIDC provider, AISIX verifies JWT signatures and claims, then maps the external identity to the caller API key bound to that provider and subject. AISIX does not introspect opaque OAuth tokens. A JWT that fails validation is rejected and is not treated as a caller API key. See JWT Authentication for trust-provider configuration, identity mapping, and supported signing algorithms.
Model Discovery
GET /v1/models returns the model aliases the caller API key is allowed to request. Direct models and virtual models — multi-target, semantic, and ensemble — all appear, because each one is a name a caller can send as model. Wildcard aliases are excluded: provider/* is a pattern rather than a name a caller can request.
A listed virtual alias resolves on the routes that support virtual dispatch. /v1/realtime and the files, batches, and fine-tuning routes require a direct model and reject a virtual alias.
The listing follows the caller API key's allowed models. A key scoped to a multi-target alias alone returns that alias and none of its targets. Publish the alias as the entry point callers discover and keep its targets internal.
Routing Behavior
Multi-target aliases resolve to one or more target models at request time. They apply to /v1/chat/completions, /v1/messages, /v1/messages/count_tokens, and /v1/responses.
Streaming requests use the first selected eligible target and do not fail over mid-stream. Non-streaming requests can fail over to the next eligible target on retryable upstream failures.
/v1/responses can resolve a multi-target alias. OpenAI-backed targets use direct Responses forwarding, while non-OpenAI targets use the Responses bridge.
/v1/messages/count_tokens can resolve a multi-target alias, but it only uses Anthropic-backed targets. If no Anthropic target is available, the gateway rejects the request.
Endpoint Constraints
Some routes impose provider-specific gates beyond adapter-family compatibility.
| Route | Gate |
|---|---|
/v1/responses | Uses direct forwarding for OpenAI-backed targets and bridge translation for other provider targets. |
/v1/images/generations | Requires provider: "openai" on the resolved model. |
/v1/rerank | Requires the model's provider label to be openai, cohere, or jina. |
/v1/embeddings | Returns 501 not_implemented when the resolved adapter does not support embeddings. |
/v1/audio/* | Forwards OpenAI-style audio requests. Does not translate across provider families. |
/v1/files, /v1/batches, /v1/fine_tuning/jobs | Supports OpenAI-compatible providers and Azure OpenAI. Vertex AI, AWS Bedrock, and Anthropic-native batch flows use different wire and storage models and are not served by these routes. |
Files, Batches, and Fine-Tuning
Files, batches, and fine-tuning jobs use OpenAI-compatible route shapes. Because some follow-up calls reference only a file or job id, AISIX encodes routing information into ids it creates. Gateway-created ids start with aisix- and route later file, batch, and fine-tuning calls without another model hint.
When uploading a file, provide the routing model once by using a model multipart field, a model query parameter, or the x-aisix-model header. Raw provider ids can still be used, but pass an explicit model query parameter or header for deterministic routing.
File and job management calls record zero-token usage events. When a batch retrieve first observes a completed batch, AISIX downloads the batch output file, aggregates per-line token usage, and emits usage events with token counts. For the workflow guide, see Batch, Files, and Fine-Tuning.
Passthrough
ANY /passthrough/:provider/*rest forwards provider-native requests after gateway authentication and provider resolution. The upstream provider's status code and response body are returned unchanged. This route intentionally applies less gateway normalization than first-class modeled routes.
MCP Gateway
ANY /mcp exposes AISIX as an MCP server to downstream agents. The gateway aggregates tools from registered upstream MCP servers and exposes each tool under a server-prefixed name.
MCP requests use the same caller authentication as other proxy requests. Tool calls are allowed only when the resolved caller API key's tool access permits the requested tool name. Tool-call requests can also be governed by caller API key rate limits, budgets, and guardrails.
Handshake and discovery methods can connect and list the tools available to the caller. Tool calls emit usage events with MCP server and tool attribution, but they do not carry token usage.
ANY /mcp/{server} scopes the gateway to one registered server. Its tool list normally keeps the upstream server's original names instead of adding the <server>__ prefix used by the aggregate endpoint. If an original name would be ambiguous with a registered server prefix, AISIX keeps the current server's prefix so the advertised name remains callable. Access control still evaluates the canonical prefixed tool identity, so moving a client between the aggregate and per-server endpoints does not bypass its grants.
A2A Gateway
POST /a2a/{agent} forwards an A2A JSON-RPC request to one registered upstream agent. AISIX authenticates the caller, verifies that the caller API key allows the agent, applies request-rate and concurrency limits, and then forwards the body without translating between A2A protocol versions. Budgets also apply when the gateway is connected to AISIX Cloud.
GET /a2a/{agent}/.well-known/agent-card.json fetches the upstream agent card and rewrites every service URL it advertises — the top-level url and each entry under supportedInterfaces and additionalInterfaces — to /a2a/{agent} on the gateway. The card route requires the same caller authentication and agent grant, but is not rate-limited.
A2A calls resolve no model. Their usage events carry token counts the gateway produced by counting the message text, flagged usage_estimated, and a zero cost. They emit usage and request metrics with A2A attribution. See Agent Gateway for protocol behavior and Set Up Agent Gateway for a complete request example.
Headers and Errors
Proxy responses can include AISIX-specific headers for request correlation, routing, cache status, rate-limit state, and retry timing.
Error envelopes depend on the request format. OpenAI-compatible routes use an OpenAI-style error envelope, and Anthropic-style routes use an Anthropic-style envelope.
MCP routes use JSON-RPC envelopes. A2A calls return upstream JSON-RPC responses unchanged and use a JSON-RPC error for upstream dispatch failures. Authentication, access, and traffic-control failures can return ordinary gateway HTTP errors before the A2A request is forwarded. Passthrough routes return the upstream provider response.
For the complete header list, error envelopes, and status-code guidance, see Headers and Error Codes. For endpoint-by-endpoint provider support, see Provider Compatibility.