OpenAI-Compatible Chat Completions

Applications that use the OpenAI Chat Completions format can send the same supported request shape to an AISIX gateway at POST /v1/chat/completions. The gateway authenticates the caller, resolves the model alias, applies gateway policy, and dispatches the request through the selected provider adapter.

The compatibility is client-facing: the upstream can be OpenAI or another supported provider. The gateway returns a supported OpenAI-compatible response shape while the adapter handles provider translation.

This guide describes the Chat Completions proxy behavior. For a runnable SDK setup, see OpenAI SDK.

What the Client Sends

The client sends three gateway-facing values:

• The base URL is the AISIX proxy API root, which is the gateway origin followed by /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, streaming options, and supported multimodal fields. Provider credentials, upstream model IDs, routing policy, rate limits, guardrails, and other gateway policy stay in AISIX. For audio content blocks and generated audio, see Audio Input and Output with Chat Completions.

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.

Export the gateway connection and request values used below:

# AISIX_PROXY has no trailing slash or endpoint path such as /v1.
# The local quickstarts use http://127.0.0.1:3000.
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-prod"

Send a 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 "${AISIX_PROXY}/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "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 every concrete model alias visible to the caller API key, including direct, routing, semantic, and ensemble aliases. Wildcard aliases are patterns rather than concrete model names, so they are not listed. A key that allows every model sees every concrete alias, while a restricted key sees only the aliases its allowlist permits.

List the model aliases visible to the caller API key:

curl -sS "${AISIX_PROXY}/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

Handle Errors

The Chat Completions route returns 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 Audio Input and Output with Chat Completions, Streaming, or Tool Calling.

Use OpenAI Client with Anthropic Upstream when the application should keep the OpenAI-compatible client shape while AISIX calls Anthropic upstream.