OpenAI-Compatible API

OpenAI-compatible proxy routes fit applications that already send OpenAI-style requests and need AISIX to manage gateway-side authentication, model aliases, routing, and policy.

The client keeps the supported OpenAI-compatible request and response format. AISIX becomes the endpoint the client calls, and the upstream provider can change behind the configured model alias.

This guide describes the proxy API behavior. For a runnable SDK setup, see OpenAI SDK Quickstart.

What the Client Sends

The client sends three AISIX-owned values:

• The base URL is the AISIX proxy API root, for example http://127.0.0.1:3000/v1.
• The API key is an AISIX caller API key.
• The model value is an AISIX model alias, such as gpt-4o-prod.

The request body keeps the OpenAI-compatible format, including messages, tools, and streaming options. Provider credentials, upstream model IDs, routing policy, rate limits, guardrails, and other gateway policy stay in AISIX.

Send the caller API key with the standard bearer token format:

Authorization: Bearer YOUR_CALLER_API_KEY

AISIX also accepts x-api-key: YOUR_CALLER_API_KEY for compatibility. Use the bearer token format for OpenAI-compatible clients when the client supports it.

Chat-Completions Request

Use POST /v1/chat/completions as the default route for OpenAI-compatible chat clients.

Send a chat-completions request through AISIX:

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-prod",
    "messages": [
      {"role": "user", "content": "Hello from AISIX."}
    ]
  }'

A successful response uses the OpenAI-compatible chat-completions format. The response keeps model set to the caller-facing alias from the request.

Discover Available Models

GET /v1/models returns the single-target model aliases visible to the caller API key. Wildcard keys can see every single-target model. Restricted keys see only the models explicitly allowed by the key. Multi-target aliases are not listed, even when callers can use them directly.

List the model aliases visible to the caller API key:

curl -sS "http://127.0.0.1:3000/v1/models" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY"

Use Other Proxy Routes

Use another route only when your application already depends on that API family:

• Use POST /v1/completions for existing prompt-based text-completions clients.
• Use Embeddings, Responses, Audio, Images, or Rerank for endpoint-specific behavior.
• Use Provider Passthrough for provider-native paths AISIX does not model directly.

Provider support can differ by route, especially for non-OpenAI upstreams. For complete route coverage and provider support, see Proxy API Reference and Provider Compatibility.

Handle Errors

OpenAI-compatible proxy routes return errors in an OpenAI-style envelope. Use the error type before the status code when you need to distinguish caller authentication, model access, policy blocks, rate limits, and upstream failures.

For the full error and header reference, see Headers and Error Codes.

Next Steps

You have now seen how OpenAI-compatible clients call AISIX. Continue with Streaming, Tool Calling, or Proxy Errors and Retries when your application depends on those behaviors.