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 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. Requires the resolved model to have provider: "openai".
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.
GET	/livez	Unauthenticated liveness probe. Confirms the proxy listener is up.

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 model aliases the caller API key is allowed to access. It does not expose multi-target aliases because they are routing constructs, not caller-facing models.

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, but it only uses OpenAI-backed targets. If no OpenAI target is available, the gateway rejects the request.

/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	Requires provider: "openai" on the resolved model.
/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.

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, Anthropic-style routes use an Anthropic-style envelope, and 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.