Skip to main content
API7.ai Logo
Version: 1.0.0

DeepSeek

DeepSeek provides its language and reasoning models through a hosted API. Applications call them through stable AISIX aliases while the gateway keeps the DeepSeek 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.
  • A DeepSeek API key from the DeepSeek 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 DeepSeek-backed chat-completions route.

Because DeepSeek exposes an OpenAI-compatible API, AISIX connects through the openai adapter and uses the DeepSeek API root as api_base.

Create a Provider Key​

Create the provider key that stores the DeepSeek credential and API root, and allow it into the environment:

# Replace with your values
export DEEPSEEK_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": "deepseek-prod",
    "provider": "deepseek",
    "api_key": "'"${DEEPSEEK_API_KEY}"'",
    "api_base": "https://api.deepseek.com",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

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

❷ api_key stores the DeepSeek API key. It follows the credential-handling behavior in Provider Keys.

❸ api_base is optional for this catalog provider, because the AISIX Cloud Admin API fills in this same root when you omit it. Set it explicitly so the upstream root stays visible on the resource. AISIX appends the endpoint path to api_base, so use the vendor root https://api.deepseek.com without a trailing /chat/completions. The value must never reach the gateway empty: for an openai-adapter provider other than openai, AISIX refuses to fall back to api.openai.com and returns an upstream configuration error instead.

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": "deepseek-v4-flash-prod",
    "model_name": "deepseek-v4-flash",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name is the alias callers send in model.

❷ model_name is the DeepSeek model ID, for example deepseek-v4-flash or deepseek-v4-pro.

❸ provider_key_id attaches the alias to the DeepSeek provider key.

Create a Caller API Key​

Create the caller API key resource that can access the model alias. The gateway generates the key value; the plaintext is returned once in the create response, so capture it now:

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

echo "$AISIX_API_KEY"

The allowed_models value references the model by its ID, so the key can only access the alias you created. After the write, the configuration projects to 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 DEEPSEEK_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: "deepseek-prod"
    provider: "deepseek"
    adapter: "openai"
    api_key: ${DEEPSEEK_API_KEY}
    api_base: "https://api.deepseek.com"

models:
  - display_name: "deepseek-v4-flash-prod"
    provider: "deepseek"
    model_name: "deepseek-v4-flash"
    provider_key: "deepseek-prod"

api_keys:
  - display_name: "deepseek-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "deepseek-v4-flash-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": "deepseek-v4-flash-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from DeepSeek."
      }
    ]
  }'

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias deepseek-v4-flash-prod. Confirm the request on the DeepSeek platform usage page. If the request fails, check the provider key api_key, api_base, and the DeepSeek model ID in model_name.

Use Thinking Mode​

DeepSeek V4 uses thinking mode by default. Regular requests use high effort, while DeepSeek can automatically use max for some complex agent requests. To disable thinking for a chat-completions request, add the following field to the request body:

{
  "thinking": {
    "type": "disabled"
  }
}

When thinking is enabled, use the top-level reasoning_effort field to request high or max. For client compatibility, DeepSeek maps low and medium to high, and xhigh to max. Sampling fields such as temperature and top_p have no effect in thinking mode. See Thinking Mode for details.

AISIX forwards these controls to DeepSeek and preserves returned reasoning in the reasoning_content field for streaming and non-streaming responses. If the model makes a tool call, DeepSeek requires the assistant message's reasoning_content to be included in all subsequent requests. AISIX preserves the field, but the application is responsible for retaining and replaying the assistant message; omitting it causes DeepSeek to return HTTP 400.

Reach DeepSeek-Native API Formats​

DeepSeek publishes a native Responses API and an Anthropic-compatible API, and AISIX Cloud reaches both without any configuration: the DeepSeek catalog entry ships the declaration below, so /v1/responses and /v1/messages on a DeepSeek alias go to DeepSeek's own routes rather than being translated to chat completions.

{
  "apis": {
    "responses": {},
    "messages": { "base": "https://api.deepseek.com/anthropic" }
  }
}

responses carries no base because DeepSeek serves it at the same API root the key already points at. The declaration applies while the key points at that root. If you repoint api_base at a private endpoint it drops away, because it describes DeepSeek's paths rather than yours. Set it yourself, on the key, if you front DeepSeek through your own gateway and it serves the same routes. See Declare the API Surfaces.

The open-source AISIX gateway has no catalog, so declare it on the provider key entry in resources.yaml.

Without this declaration on the provider key, AISIX falls back as follows:

AISIX setup or routeUpstream behavior
/v1/responsesUses the AISIX Responses bridge over DeepSeek chat completions. It does not call DeepSeek's native /responses route, and Responses-only fields without a chat equivalent are ignored.
/passthrough/deepseek/responsesCalls DeepSeek's native Responses route. Send the upstream model ID in model, not the AISIX alias. Declaring apis.responses reaches the same route under an AISIX alias, which is usually what you want instead.
/v1/messagesTranslates the Anthropic-shaped caller request to DeepSeek chat completions. It does not call DeepSeek's /anthropic/v1/messages route.
Separate BYO provider key with adapter: anthropic and api_base: https://api.deepseek.com/anthropicUses the Anthropic adapter to call DeepSeek's Anthropic-compatible Messages route, at the cost of a second key and a second model alias. Declaring apis.messages on the catalog key reaches the same route under one alias.
/v1/completionsDoes not reach DeepSeek's FIM Completion (Beta) route, which is served only under the /beta API root.
/passthrough/deepseek/beta/completionsCalls FIM Completion (Beta). Send deepseek-v4-pro in model; AISIX does not rewrite an alias on passthrough routes.

The /passthrough/deepseek paths on this page assume a passthrough route claiming that prefix with DeepSeek's API root as its target_url; grant the route name on the caller key's allowed_routes. The route relays the native Responses request and response without rewriting an AISIX alias. AISIX detects the Responses envelope from input and records every supported token dimension the response carries, including input, output, cache, and reasoning details. These counts are telemetry only: passthrough does not advance tpm or tpd counters, resolve a model cost, or add budget spend. If the response omits all supported token fields, the recorded token counts remain zero.

Endpoint Coverage​

RouteBehavior with a DeepSeek catalog alias
/v1/chat/completionsSupported, including stream: true.
/v1/responsesReaches DeepSeek's native Responses API, which the catalog entry declares. Reasoning output items survive, where the chat-completions translation cannot carry them.
/v1/messagesReaches DeepSeek's Anthropic-compatible route, which the catalog entry declares, so prompt-cache breakpoints and thinking blocks survive. /v1/messages/count_tokens is available on the same route.
/v1/completionsDoes not reach DeepSeek FIM. Use /passthrough/deepseek/beta/completions with deepseek-v4-pro instead.
/v1/embeddingsNot available. DeepSeek does not publish an embeddings endpoint on this API root.
/v1/audio/*Not available. DeepSeek does not publish matching OpenAI-style audio routes.
/v1/images/generationsRejected. The route accepts only models whose provider is openai.
/v1/rerankRejected. The route accepts only the openai, cohere, and jina provider values.
/v1/videosRejected. The route's provider allowlist does not include deepseek.
/passthrough/deepseek/*Available through a configured passthrough route for provider-native routes such as /responses and /models, with the alias and usage limitations described above.

Next Steps​

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