Skip to main content
API7.ai Logo

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 gateway-facing 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 direct, ensemble, and semantic model aliases visible to the caller API key. Direct models include models with embedding metadata. Wildcard keys can see every listed alias, while restricted keys see only the aliases explicitly allowed by the key.

Routing 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"

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 OpenAI Client with Anthropic Upstream when your application should keep the OpenAI-compatible client shape while AISIX calls Anthropic upstream.