Skip to main content
API7.ai Logo

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"

Create a complete declarative resources file for this provider:

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. The catalog provider key in this guide still uses the openai chat adapter, so normalized AISIX routes do not automatically select those native upstream formats:

AISIX setup or routeUpstream behavior
/v1/responses with the catalog DeepSeek aliasUses 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. DeepSeek currently supports deepseek-v4-flash on this route, but not deepseek-v4-pro.
/v1/messages with the catalog DeepSeek aliasTranslates 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. DeepSeek's documented Anthropic compatibility limits still apply.
/v1/completions with the catalog DeepSeek aliasDoes 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.

Provider passthrough forwards the native Responses request and response without rewriting an AISIX alias. AISIX records the request, but token counts remain zero, so AISIX token-based budgets and cost calculations do not account for passthrough traffic.

Endpoint Coverage​

RouteBehavior with a DeepSeek catalog alias
/v1/chat/completionsSupported, including stream: true.
/v1/responsesSupported through the chat-based Responses bridge, not DeepSeek's native Responses API.
/v1/messagesSupported through translation to chat completions. /v1/messages/count_tokens is not available because it requires an Anthropic-backed model.
/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/*Supported 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: