OpenAI-Compatible Vendor Upstream

In this guide, you will connect AISIX AI Gateway to a public model vendor that exposes an OpenAI-compatible API, such as DeepSeek, Groq, Mistral, Together.ai, Fireworks, or Perplexity.

Use this configuration when your applications should call AISIX with the OpenAI-compatible API while AISIX handles the vendor credential, upstream host, and model mapping.

For private or self-hosted OpenAI-compatible servers, use Bring Your Own Endpoint instead.

Prerequisites

Before starting, prepare the following:

• A gateway with the admin API on :3001 and the proxy API on :3000.
• The admin key from the gateway config.yaml.
• The vendor API key, model ID, and OpenAI-compatible API root from the vendor's API reference. The examples below use DeepSeek with https://api.deepseek.com.

Configure the Vendor Upstream

Create a provider key, model alias, and caller API key for the vendor-backed route. The examples use DeepSeek, but the same shape applies to other OpenAI-compatible vendors after you replace the vendor label, API root, credential, and model ID.

Create a Provider Key

Create the provider key for the OpenAI-compatible vendor endpoint:

export AISIX_ADMIN_KEY="admin-local-only-change-me"
export VENDOR_API_KEY="YOUR_PROVIDER_API_KEY"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "deepseek-prod",
    "provider": "deepseek",
    "adapter": "openai",
    "secret": "'"${VENDOR_API_KEY}"'",
    "api_base": "https://api.deepseek.com"
  }'

❶ provider identifies the public vendor.

❷ adapter selects the OpenAI-compatible upstream format.

❸ secret stores the vendor API key.

❹ api_base points to the vendor's OpenAI-compatible API root.

Copy the returned provider key ID. AISIX appends the endpoint path to api_base, so include vendor-specific prefixes such as /v1 or /openai/v1 when the vendor requires them. Do not rely on AISIX to guess a public vendor URL.

Provider key secrets follow the credential-handling behavior described in Provider Keys.

Create a Model

Map a caller-facing alias to the vendor's model ID:

export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "deepseek-flash-prod",
    "provider": "deepseek",
    "model_name": "deepseek-v4-flash",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }'

❶ display_name is the alias callers send in model.

❷ model_name is the model ID expected by the vendor.

❸ provider_key_id attaches the model alias to the provider key you created.

Add a cost block only when you need budget accounting or usage reports to calculate token cost for this alias. See Models.

Create a Caller API Key

Choose the plaintext caller API key that the application will send to AISIX, then hash it for the admin resource:

export AISIX_API_KEY="sk-deepseek-caller"

CALLER_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

Create the API key resource with access to the vendor-backed model alias:

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${CALLER_KEY_HASH}"'",
    "allowed_models": ["deepseek-flash-prod"]
  }'

❶ allowed_models must match the model alias you created.

Verify the Upstream

Send a chat-completions request through the AISIX proxy:

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash-prod",
    "messages": [
      {"role": "user", "content": "Say hello from DeepSeek."}
    ]
  }'

The response should be an OpenAI-compatible chat-completions response that echoes the caller-facing alias. If your vendor exposes logs, metrics, request IDs, or usage records, use them to confirm that the request reached the intended upstream account and model.

If the gateway returns an upstream authentication error, check the provider key's secret. If it returns an upstream route error, check api_base and the vendor model ID in model_name.

Behavior and Limits

This guide supports vendors that accept OpenAI chat-completions requests. A vendor with a different request format needs a native adapter. See Adapter Protocol Families.

Vendor-specific response extensions beyond the OpenAI envelope are not normalized by default. If a vendor returns reasoning content in a custom field, use the response.reasoning_field override on the provider key.

Next Steps

You have now configured an OpenAI-compatible vendor as an upstream provider. Use the same pattern for other public vendors by changing the vendor label, API root, credential, and model ID.