Skip to main content
API7.ai Logo

Qwen (Alibaba Cloud)

Qwen is Alibaba Cloud's family of language and multimodal models, served through Model Studio, also known as DashScope. Applications call Qwen through stable AISIX aliases while the gateway holds the DashScope credential.

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 DashScope API key from Alibaba Cloud Model Studio for the region you plan to use.
  • 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 Qwen-backed chat-completions route. The examples use the Singapore regional endpoint.

Because Alibaba Cloud Model Studio exposes an OpenAI-compatible endpoint, AISIX connects through the openai adapter and uses the DashScope API root for the region where you created the credential.

Create a Provider Key​

DashScope API keys and endpoints are region-specific. The AISIX catalog has separate international and mainland China provider IDs, with these default API roots:

Provider IDDefault API rootScope
alibabahttps://dashscope-intl.aliyuncs.com/compatible-mode/v1International, using the Singapore endpoint
alibaba-cnhttps://dashscope.aliyuncs.com/compatible-mode/v1Mainland China, using the Beijing endpoint

An API key issued for one region does not work with another region's endpoint. Create one provider key per region when routing to both. Use alibaba for international traffic and alibaba-cn for mainland China so usage records and cost reports attribute traffic to the matching catalog.

Alibaba Cloud recommends a workspace-dedicated domain for production. The shared DashScope roots above remain available for existing integrations, but a dedicated domain provides workspace isolation and higher concurrency. The example below uses the Singapore form; replace YOUR_WORKSPACE_ID with the workspace that issued the API key. For another region, use the matching domain from the Model Studio console.

Create the provider key that stores the DashScope credential and API root, and capture its ID:

# Replace with your value
export DASHSCOPE_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": "qwen-prod",
    "provider": "alibaba",
    "api_key": "'"${DASHSCOPE_API_KEY}"'",
    "api_base": "https://YOUR_WORKSPACE_ID.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

❶ provider is alibaba, the catalog provider ID for the international Model Studio region. Use alibaba-cn for the mainland China region. 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 DashScope API key. It follows the credential-handling behavior in Provider Keys.

❸ api_base already includes the /compatible-mode/v1 path. Use the workspace and region that issued the API key. If you omit this field, AISIX Cloud uses the shared international root for alibaba and the shared Beijing root for alibaba-cn; those catalog defaults do not select your workspace-dedicated domain.

Create a Model​

Create the model alias callers will send in requests, and capture its ID:

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

❶ display_name is the alias callers send in model.

❷ model_name is the Qwen model ID. This example uses the current qwen3.7-plus model; check the Model Studio model list for availability in your region before creating the alias.

❸ provider_key_id attaches the alias to the Qwen provider key.

Create a Caller API Key​

Create the caller API key resource that can access the model alias. The plaintext key is generated by the server and returned once in the 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": "qwen-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

The allowed_models value must reference the model ID you captured. Store the plaintext key securely; it cannot be retrieved again.

The new resources project to attached gateways automatically, so the route is ready to call almost immediately.

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 DASHSCOPE_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: "qwen-prod"
    provider: "alibaba"
    adapter: "openai"
    api_key: ${DASHSCOPE_API_KEY}
    api_base: "https://YOUR_WORKSPACE_ID.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"

models:
  - display_name: "qwen-plus-prod"
    provider: "alibaba"
    model_name: "qwen3.7-plus"
    provider_key: "qwen-prod"

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

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias qwen-plus-prod. Confirm the request on the Model Studio usage page. If the request fails with an upstream authentication error, check the provider key api_key and confirm that the key and base URL use the same region.

Endpoint Coverage​

A Qwen provider key uses the openai adapter, but route support also depends on AISIX provider rules and the APIs available on the configured Model Studio base:

RouteBehavior with a Qwen model alias
/v1/chat/completionsSupported, buffered and streaming.
/v1/messagesSupported through translation to chat completions. /v1/messages/count_tokens is limited to Anthropic-backed models. Alibaba's native Anthropic-compatible API uses a different /apps/anthropic base and therefore needs a separate provider key.
/v1/responsesSupported through the AISIX Responses bridge, not Alibaba's native Responses API. Fields without a chat-completions equivalent are ignored. To use native features such as previous_response_id or provider-hosted tools, call /passthrough/alibaba/responses with the exact upstream model ID in the body.
/v1/embeddingsSupported when the alias names a text embedding model available in the same region, such as text-embedding-v4. AISIX appends /embeddings to the configured OpenAI-compatible base.
/v1/videos and its status and content routesSupported only when the model's provider value is exactly alibaba; alibaba-cn is outside the video route's allowlist. AISIX maps the request to DashScope's asynchronous Wan text-to-video API. For current Wan 2.7 models, omit size, because the AISIX size mapping targets earlier Wan APIs. Use provider passthrough when you need native resolution, ratio, or multimodal fields; for alibaba-cn, this requires a separate provider key rooted at the native Model Studio base.
/v1/audio/*Not supported on the OpenAI-compatible base configured on this page. Model Studio audio APIs use provider-native routes and request shapes.
/v1/images/generationsNot supported. This route accepts only models whose configured provider is openai; Model Studio image APIs require provider passthrough.
/v1/rerankNot supported. This route accepts only the openai, cohere, and jina provider values; Model Studio rerank models use a provider-native API.
/passthrough/alibaba/*rest and /passthrough/alibaba-cn/*restSupported for native Model Studio APIs that AISIX has not modeled. Provider passthrough does not rewrite a caller-facing alias inside the body, buffers upstream SSE responses, and records zero token and cost usage. Use a separate provider key when the native API has a different base URL.

See Provider Compatibility for the full endpoint and provider matrix.

Next Steps​

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