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.

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

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"

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​

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.