Version: 1.0.0

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.

This guide covers both Qwen chat traffic and Wan video tasks through a single Model Studio 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.
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 ID	Default API root	Scope
`alibaba`	`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`	International, using the Singapore endpoint
`alibaba-cn`	`https://dashscope.aliyuncs.com/compatible-mode/v1`	Mainland 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"

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: "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.

Generate Videos with Wan and HappyHorse

The same provider key drives the gateway's modeled video routes. Create a second alias that points at a Model Studio text-to-video model — a Wan 2.7 model, or a HappyHorse text-to-video model such as happyhorse-1.1-t2v. Both families answer on the same asynchronous DashScope endpoints, so the workflow below is identical; only the upstream model name changes.

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": "wan-video-prod",
    "model_name": "wan2.7-t2v",
    "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": "qwen-video-caller",
    "allowed_models": ["'"${VIDEO_MODEL_ID}"'"]
  }' | jq -r '.plaintext')

For the open-source AISIX gateway, add wan-video-prod to the existing models collection. Replace the existing qwen-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: "wan-video-prod"
    provider: "alibaba"
    model_name: "wan2.7-t2v"
    provider_key: "qwen-prod"

api_keys:
  - display_name: "qwen-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "qwen-plus-prod"
      - "wan-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": "wan-video-prod",
    "prompt": "A paper boat drifts down a rain-soaked street at dusk.",
    "seconds": 5
  }'

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

Only the alibaba provider value is dispatched. alibaba-cn is outside the video route's allowlist, so a mainland China alias returns a not-implemented error on submit. Reach the mainland China video API through a passthrough route whose target_url is the native Model Studio base for that region.
The chat api_base is reused as-is. AISIX strips one /compatible-mode/v1, /api/v1, or /v1 suffix, derives the vendor root, and composes DashScope's native task paths underneath. A provider key already configured for Qwen chat traffic works on the video routes without change, and the gateway sets the mandatory asynchronous submission header for you.
size targets the earlier Wan protocol. seconds is forwarded as the integer parameters.duration, and size is forwarded as parameters.size in the provider's WIDTH*HEIGHT spelling. That parameter belongs to Wan 2.6 and earlier. Wan 2.7 models replaced it with resolution and ratio tiers, and AISIX does not check which family the alias names — it forwards whatever you send. Omit size yourself on a Wan 2.7 alias, as the example above does, and let the provider default apply.
HappyHorse text-to-video works on the same route. happyhorse-1.1-t2v and happyhorse-1.0-t2v use the same submission endpoint, poll endpoint, and task states as Wan, and express output dimensions as resolution and ratio tiers — so, as with Wan 2.7, omit size and let the provider default apply. The image-to-video (happyhorse-1.1-i2v), reference-to-video, and video-editing variants are separate Model Studio APIs with reference-media inputs the modeled route does not carry; reach them through a passthrough route, like the other provider-native fields below. Runway also hosts HappyHorse models on its own platform — see RunwayML for that integration.
Provider-native video fields require a passthrough route. The normalized request models only prompt, seconds, and size; extra fields are ignored. To send native fields such as negative_prompt, seed, or Wan 2.7's resolution and ratio, use a passthrough route pointed at the native DashScope root, which differs from the OpenAI-compatible root the /passthrough/alibaba examples on this page assume. A route claiming /passthrough/alibaba-video with https://dashscope-intl.aliyuncs.com/api/v1 as its target_url submits at /passthrough/alibaba-video/services/aigc/video-generation/video-synthesis and polls at /passthrough/alibaba-video/tasks/{id}. Send the native body with the exact upstream model ID, and set the provider's asynchronous submission header yourself. Passthrough does not return the unified AISIX video object or gateway-encoded task ID.
Finished videos are delivered by redirect. GET /v1/videos/{id}/content returns 302 with a Location header pointing at the provider's signed download URL. The bytes travel from Model Studio storage to the client and do not pass through the gateway, so follow redirects when downloading, for example with the -L flag in curl.

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

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:

Route	Behavior with a Qwen model alias
`/v1/chat/completions`	Supported, buffered and streaming.
`/v1/messages`	Supported 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/responses`	Supported 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/embeddings`	Supported 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 routes	Supported 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 text-to-video API, which serves both Wan and HappyHorse text-to-video models. For current Wan 2.7 and HappyHorse models, omit `size`, because the AISIX `size` mapping targets earlier Wan APIs. See Generate Videos with Wan and HappyHorse. Use a passthrough route when you need native `resolution`, `ratio`, or multimodal fields; for `alibaba-cn`, this requires a route targeting 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/generations`	Not supported. This route accepts only models whose configured provider is `openai`; Model Studio image APIs require a passthrough route.
`/v1/rerank`	Not 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/rest`	Available through configured passthrough routes for native Model Studio APIs that AISIX has not modeled. A passthrough route does not rewrite a caller-facing alias inside the body and relays upstream SSE incrementally. Recognized chat, completions, and Responses envelopes record supported usage fields. Requests without a recognized carrier field remain opaque: buffered responses record zero tokens, while opaque SSE can still record top-level supported `usage` fields. Use a separate route when the native API has a different base URL.

The /passthrough/alibaba and /passthrough/alibaba-cn paths on this page assume passthrough routes claiming those prefixes, each with the matching Model Studio API root as its target_url; grant the route names on the caller key's allowed_routes.

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:

Model Aliases: configure routing, retry behavior, or cost metadata for this alias.
Routing and Failover: fail over between Qwen regions or between Qwen and another provider.
Video Generation: follow the submit, poll, and download workflow for supported Wan text-to-video models.
Provider-Specific Overrides: adapt request and response shapes when an upstream API differs from its adapter.
Provider Compatibility: review supported proxy endpoints and provider-specific boundaries.

Prerequisites​

Configure with AISIX Cloud​

Create a Provider Key​

Create a Model​

Create a Caller API Key​

Configure with the Open-Source AISIX Gateway​

Verify the Provider Connection​

Generate Videos with Wan and HappyHorse​

Endpoint Coverage​

Next Steps​