Skip to main content
API7.ai Logo
Version: 1.0.0

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.

This guide covers both GPT chat traffic and Sora video tasks through a single OpenAI provider key.

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"

For a new gateway, use this complete resources file. For an existing gateway, merge the entries into its current file, preserving its other resources:

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.

Generate Videos with Sora​

caution

OpenAI deprecated the Videos API and the Sora 2 models on March 24, 2026 and will remove them from the API on September 24, 2026. Aliases backed by sora-2 or sora-2-pro stop working on that date, and OpenAI lists no replacement model on this API.

The same provider key drives the gateway's modeled video routes. Create a second alias that points at a Sora model — sora-2 or sora-2-pro:

In AISIX Cloud, create the video alias and a caller key scoped to it:

VIDEO_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": "sora-video-prod",
    "model_name": "sora-2",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$VIDEO_MODEL_ID"

VIDEO_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-video-caller",
    "allowed_models": ["'"${VIDEO_MODEL_ID}"'"]
  }' | jq -r '.plaintext')

For the open-source AISIX gateway, add sora-video-prod to the existing models collection. Replace the existing openai-caller entry with the updated entry below so it allows both model aliases. Preserve unrelated entries and collections:

resources.yaml (video model access)
models:
  - display_name: "sora-video-prod"
    provider: "openai"
    model_name: "sora-2"
    provider_key: "openai-prod"

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

Validate and reload or restart the declarative resources file as described above, then use the existing caller key for the video request:

export VIDEO_API_KEY="$CALLER_API_KEY"

Submit a task:

curl -sS -X POST "$AISIX_PROXY/v1/videos" \
  -H "Authorization: Bearer ${VIDEO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-video-prod",
    "prompt": "A paper boat drifts down a rain-soaked street at dusk.",
    "seconds": 4,
    "size": "1280x720"
  }'

Five provider-specific behaviors are worth knowing before you script around this route:

  • OpenAI is the only video provider with a default base URL. An OpenAI-backed video alias works with api_base unset, exactly like the chat alias on this page. Every other video provider requires api_base on the provider key.
  • Sora validates seconds and size itself. OpenAI's create-video schema accepts 4, 8, or 12 for seconds and lists 720x1280, 1280x720, 1024x1792, and 1792x1024 for size, but the per-model pages publish narrower resolution sets — check the page for the model your alias names. AISIX forwards seconds as a string and checks that size has the WIDTHxHEIGHT shape before forwarding it verbatim, so a well-formed value the model does not accept is rejected by the provider, not by the gateway.
  • Finished videos stream through the gateway. Sora serves the finished file from an authenticated content endpoint rather than a signed URL, so GET /v1/videos/{id}/content returns 200 with the MP4 bytes instead of a 302. AISIX fetches the file with the provider credential and relays it chunk by chunk, so the credential never reaches the caller and a large file does not grow the gateway's memory use. Size the gateway's egress for this traffic: those bytes transit the gateway and do not count against the model's rate limits.
  • progress is a real percentage. Sora reports task progress, so poll responses carry the provider's own completion percentage. Providers that report none stay at 0 until the task completes.
  • Image-to-video requires a passthrough route. The normalized request models only prompt, seconds, and size; extra fields, including input_reference, are ignored rather than rejected, so a remix or image-guided request would silently generate from the prompt alone. Call /passthrough/openai/v1/videos with the native multipart body for those, and use the native remix route the same way. An OpenAI SDK client reaches this path too, but it needs its own client: point its base URL at ${AISIX_PROXY}/passthrough/openai/v1 rather than the ${AISIX_PROXY}/v1 client used elsewhere on this page, and grant the route name in the caller key's allowed_routes. The video create helper always sends multipart/form-data, which the modeled route does not accept. Passthrough does not return the unified AISIX video object or gateway-encoded task ID.

For the full submit, poll, and download workflow, including status semantics and rate-limit behavior on polling, see Video Generation.

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.

RouteBehavior with an OpenAI-backed alias
/v1/chat/completionsSupported with the OpenAI request and response shape. Model-specific feature and parameter limits still apply.
/v1/responsesForwarded 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/completionsForwarded to OpenAI, but this is a legacy endpoint and the selected model must support it.
/v1/embeddingsSupported with an alias for an OpenAI embedding model, such as text-embedding-3-large.
/v1/images/generationsSupported with an alias for a current OpenAI image model.
/v1/images/editsSupported with an alias for an OpenAI image-editing model such as gpt-image-2. Requests are multipart/form-data; see Image Editing.
/v1/videos and its status and content routesSupported with an alias for a Sora model, sora-2 or sora-2-pro. The content route streams the MP4 through the gateway instead of redirecting, because OpenAI serves finished files from an authenticated endpoint. See Generate Videos with Sora.
/v1/audio/*Supported with an appropriate speech, transcription, or translation model alias.
/v1/realtimeSupported as a WebSocket relay with a direct Realtime model alias. See Realtime API.
/v1/files, /v1/batches, /v1/fine_tuning/jobsSupported through the OpenAI adapter. These job-style routes select credentials differently from ordinary inference calls; see Files, Batch, and Fine-tuning.
/v1/messagesTranslated through OpenAI chat; OpenAI does not expose a native Anthropic Messages endpoint.
/v1/messages/count_tokensRejected because token counting on this route requires an Anthropic-backed model.
/v1/modelsReturns caller-accessible AISIX model aliases, not the OpenAI account's model inventory. Use /passthrough/openai/v1/models when the native list is required.
/v1/rerankAISIX accepts the openai provider value, but the public OpenAI API does not expose /v1/rerank, so the upstream rejects the call.

Use a passthrough route for an OpenAI route that AISIX does not model, such as moderation or image variations. The /passthrough/openai paths on this page assume a route claiming that prefix with OpenAI's API root as its target_url; grant the route on the caller key's allowed_routes. 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: