OpenAI

OpenAI provides hosted GPT models through its API. Applications call them through stable AISIX aliases while the gateway keeps the OpenAI credential out of client code.

Prerequisites

Before starting, prepare the following:

One AISIX setup:
- For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
- For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
An OpenAI API key from the OpenAI platform.
curl and jq.

Configure with AISIX Cloud

Export the AISIX Cloud connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Create a provider key, model alias, and caller API key for the OpenAI-backed route.

OpenAI is the gateway's native OpenAI-compatible upstream, and the integration uses the openai adapter. You can leave api_base unset for OpenAI's canonical endpoint or set it to target an OpenAI-compatible proxy that preserves bearer authentication and the OpenAI route shape.

Create a Provider Key

Create the provider key that stores the OpenAI credential:

# Replace with your values
export OPENAI_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "openai-prod",
    "provider": "openai",
    "api_key": "'"${OPENAI_API_KEY}"'",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

❶ provider is openai. This is the only provider value that lets AISIX fall back to the default base URL https://api.openai.com/v1.

❷ api_key stores the OpenAI API key. The value is encrypted before it is stored and is never returned by read endpoints. It follows the credential-handling behavior in Provider Keys.

❸ allowed_environments lists the environments that may reference this provider key when creating models.

The AISIX Cloud Admin API derives the adapter from the catalog provider; the adapter field is only accepted on BYO provider keys.

You can omit api_base for OpenAI. To target a compatible bearer-authenticated proxy or regional gateway, set api_base explicitly. Use the dedicated Azure OpenAI integration for the Azure OpenAI service itself. The command captures the returned provider key ID in PROVIDER_KEY_ID.

Create a Model

Create the model alias callers will send in requests:

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gpt-5.6-sol-prod",
    "model_name": "gpt-5.6-sol",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

❶ display_name is the alias callers send in model.

❷ model_name is the OpenAI model ID. This guide uses gpt-5.6-sol, the current flagship model in the OpenAI model catalog. Choose a different current model when its cost, latency, or modality better matches the workload.

❸ provider_key_id attaches the alias to the OpenAI provider key.

Create a Caller API Key

Create the caller API key resource that can access the model alias. The control plane generates the key value and returns the plaintext once in the create response:

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "openai-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

The allowed_models value references the model ID captured in the previous step.

Store the plaintext key securely. The control plane stores only a hash; the plaintext is not retrievable after this response.

After each write, the configuration projects to the attached gateways automatically.

Configure with the Open-Source AISIX Gateway

Export the upstream credential and choose the caller API key that applications will send to the gateway:

export OPENAI_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

Create a complete declarative resources file for this provider:

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "openai-prod"
    provider: "openai"
    adapter: "openai"
    api_key: ${OPENAI_API_KEY}

models:
  - display_name: "gpt-5.6-sol-prod"
    provider: "openai"
    model_name: "gpt-5.6-sol"
    provider_key: "openai-prod"

api_keys:
  - display_name: "openai-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "gpt-5.6-sol-prod"

If AISIX is installed locally, validate the file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands. After the resources load, prepare the shared verification request below:

export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection

Export the AISIX gateway origin:

# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

Send a chat-completions request through the AISIX proxy:

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from OpenAI."
      }
    ]
  }'

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias gpt-5.6-sol-prod. Confirm the request on the OpenAI usage dashboard. If the request fails with an upstream authentication error, check the provider key api_key.

For reasoning, tool-calling, and multi-turn workflows, OpenAI recommends the Responses API. Send a native Responses request through the same alias:

curl -sS -X POST "$AISIX_PROXY/v1/responses" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol-prod",
    "input": "Say hello from the OpenAI Responses API."
  }'

Because the model's configured provider is openai, AISIX rewrites the model alias and forwards this request to OpenAI's native Responses endpoint. It does not use the cross-provider Responses bridge.

Endpoint Coverage

OpenAI exposes several API families that use different model types. Configure a separate AISIX model alias for each upstream model an application needs.

Route	Behavior with an OpenAI-backed alias
`/v1/chat/completions`	Supported with the OpenAI request and response shape. Model-specific feature and parameter limits still apply.
`/v1/responses`	Forwarded to OpenAI's native Responses endpoint after model-alias rewriting. Stateful fields, hosted tools, reasoning controls, and upstream SSE remain on the native path.
`/v1/completions`	Forwarded to OpenAI, but this is a legacy endpoint and the selected model must support it.
`/v1/embeddings`	Supported with an alias for an OpenAI embedding model, such as `text-embedding-3-large`.
`/v1/images/generations`	Supported with an alias for a current OpenAI image model.
`/v1/videos` and its status and content routes	Supported with an alias for an OpenAI video model available to the account.
`/v1/audio/*`	Supported with an appropriate speech, transcription, or translation model alias.
`/v1/realtime`	Supported as a WebSocket relay with a direct Realtime model alias. See Realtime API.
`/v1/files`, `/v1/batches`, `/v1/fine_tuning/jobs`	Supported through the OpenAI adapter. These job-style routes select credentials differently from ordinary inference calls; see Files, Batch, and Fine-tuning.
`/v1/messages`	Translated through OpenAI chat; OpenAI does not expose a native Anthropic Messages endpoint.
`/v1/messages/count_tokens`	Rejected because token counting on this route requires an Anthropic-backed model.
`/v1/models`	Returns caller-accessible AISIX model aliases, not the OpenAI account's model inventory. Use `/passthrough/openai/v1/models` when the native list is required.
`/v1/rerank`	AISIX accepts the `openai` provider value, but the public OpenAI API does not expose `/v1/rerank`, so the upstream rejects the call.

Use provider passthrough for an OpenAI route that AISIX does not model, such as moderation or image edits. Passthrough uses OpenAI model IDs rather than AISIX aliases and has different streaming and usage-accounting behavior.

Use an OpenAI SDK

Set AISIX_BASE_URL to ${AISIX_PROXY}/v1 and use the caller key as the API key. See the OpenAI SDK guide.

Next Steps

You have now connected AISIX to OpenAI and verified the model alias. Continue with these guides:

Model Aliases: configure routing, retry behavior, or cost metadata for this alias.
Azure OpenAI: configure an Azure-hosted OpenAI deployment instead.
Provider Compatibility: review supported proxy endpoints and provider-specific boundaries.

Prerequisites​

Configure with AISIX Cloud​

Create a Provider Key​

Create a Model​

Create a Caller API Key​

Configure with the Open-Source AISIX Gateway​

Verify the Provider Connection​

Endpoint Coverage​

Use an OpenAI SDK​

Next Steps​