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.

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 single-target and ensemble model aliases visible to the caller API key. Multi-target aliases are hidden.
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/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.
POST	/v1/rerank	Reranking. Supports openai, cohere, and jina provider labels only.
ANY	/passthrough/:provider/*rest	Provider-native forwarding with gateway authentication and limited gateway normalization.
ANY	/mcp and /mcp/	MCP gateway endpoint. Authenticates the caller API key, lists allowed tools, and routes tool calls to registered upstream MCP servers.
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, before the first config apply, or when the config watch is stale.

Authentication

Proxy requests use caller-facing API keys created through the Admin API or AISIX Cloud.

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.

Model Discovery

GET /v1/models returns the single-target and ensemble model aliases the caller API key is allowed to access. It does not expose multi-target aliases because they are routing constructs, not discovery-list entries.

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.

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 API key authentication as other proxy requests. Tool calls are allowed only when the 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.

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. 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.