Connect a DashScope upstream

DashScope is Alibaba Cloud's AI service, covering text generation, multimodal, text embedding, reranking, ASR, and other model types. This chapter walks you through creating a dashscope upstream + qwen-turbo model, calling it with the OpenAI SDK, and briefly covering the other kind variants.

Prerequisites

• The gateway is running (http://localhost:7890) and you can log in to the Console
• ENCRYPTION_KEY is set — the upstream API key and access key saved below are encrypted before being stored; if it's not set, saving reports encryption_key not set in config. See Docker single node → Prerequisites
• An Alibaba Cloud DashScope API key

1. Create a dashscope upstream

Console → Upstreams → New:

Field	Value	Description
Name	dashscope	Unique upstream identifier
Protocol	dashscope	Determines the executor and request schema
Base URL	https://dashscope.aliyuncs.com	The real upstream address, no trailing /
API Key	Alibaba Cloud key	Click "Add" to add multiple keys, distributed by weight
Enabled	✓

Save.

2. Create a qwen-turbo model

On the dashscope upstream row, click Expand → model sub-table → New model:

Field	Value	Description
Name	qwen-turbo	The model name exposed to clients
Upstream	dashscope	Select the upstream you just created
Upstream model ID	qwen-turbo	The real DashScope model name
Protocol	dashscope (inherited from upstream)	Can also be overridden at the model level
Enabled	✓

Save.

Different DashScope model types have different endpoints, selected by the kind field. Text generation (such as qwen-turbo, qwen-plus, qwen-max) uses the default endpoint /api/v1/services/aigc/text-generation/generation and does not need kind specified. See the table below for other variants.

3. Configure a key group to allow access

Console → Access Keys → Key Groups tab → New:

Field	Value	Description
Name	default	Group name
Models	Select qwen-turbo, or * (all)	Determines which models this group's keys can call
Enabled	✓

4. Issue an access key

Console → Access Keys → New:

Field	Value	Description
Name	my-app-key	The key's identifier, used for management and audit
API key	Click "Generate"	Auto-generates a string; the credential clients send when calling
Group	default	Determines which models this key can access
Enabled	✓

5. Call with the OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:7890/v1",
    api_key="<your access key>",
)

resp = client.chat.completions.create(
    model="qwen-turbo",
    messages=[{"role": "user", "content": "hi"}],
)
print(resp.choices[0].message.content)

The gateway automatically translates the OpenAI request format into the DashScope format, sends it to https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation, and translates the response back into the OpenAI format.

6. Or use curl

curl http://localhost:7890/v1/chat/completions \
  -H "Authorization: Bearer <your access key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-turbo",
    "messages": [{"role":"user","content":"hi"}]
  }'

Receiving a reply means it's working.

Other kind variants

DashScope text generation uses the default endpoint; other model types switch endpoints via the kind field. The table below is an overview; see Upstream and model fields for full field descriptions.

kind	Endpoint	Applicable models
(default)	/api/v1/services/aigc/text-generation/generation	qwen-turbo, qwen-plus, qwen-max
dashscope-multimodal	/api/v1/services/aigc/multimodal-generation/generation	qwen-vl-chat-v1, qwen-vl-plus, qwen-audio, fun-asr-flash
dashscope-text-embedding	/api/v1/services/embeddings/text-embedding/text-embedding	text-embedding-v4
dashscope-rerank	/api/v1/services/rerank/text-rerank/text-rerank	gte-rerank
dashscope-audio-asr	/api/v1/services/audio/asr/transcription (async)	fun-asr

The last three rows (embedding / rerank / ASR) have endpoints under the Bailian MaaS domain (https://<workspace-id>.cn-beijing.maas.aliyuncs.com), a different domain from text generation's https://dashscope.aliyuncs.com, so you need a separate upstream — see Text embedding (separate upstream) below.

Video generation (direct_path)

Async models such as video generation need direct_path = true plus the full endpoint URL:

{
  "name": "wanx2.1-t2v",
  "upstream": ["dashscope"],
  "upstream_model_id": "wanx2.1-t2v",
  "protocol": "dashscope",
  "direct_path": true,
  "base_url": "https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis"
}

Async models also need this in extra_config: {"dashscope": {"async_mode": true}}

Text embedding (separate upstream)

Text embedding / rerank / ASR models use the Bailian MaaS domain, a different domain from text generation's https://dashscope.aliyuncs.com, so you must first create a separate upstream and then create models under it.

1) Create an upstream dashscope-maas (Console → Upstreams → New):

Field	Value	Description
Name	dashscope-maas	Unique upstream identifier; the models below reference it via upstream
Protocol	dashscope	Same as text generation
Base URL	https://<workspace-id>.cn-beijing.maas.aliyuncs.com	The Bailian MaaS domain; replace <workspace-id> with your Bailian workspace ID
API Key	Alibaba Cloud key	Can be the same key as text generation
Enabled	✓

2) Create a text embedding model under that upstream:

{
  "name": "text-embedding-v4",
  "upstream": ["dashscope-maas"],
  "upstream_model_id": "text-embedding-v4",
  "protocol": "dashscope",
  "kind": "dashscope-text-embedding"
}

Clients send requests using the standard OpenAI /v1/embeddings protocol, and the gateway automatically translates them to the DashScope format. Similarly, mount rerank / ASR under dashscope-maas with kind set to dashscope-rerank / dashscope-audio-asr respectively.

Passthrough vs translation

DashScope clients can go two ways:

• Passthrough: POST /v1/services/{*rest} — the request body is sent to the DashScope upstream as-is
• Translation: POST /v1/chat/completions — the gateway translates the OpenAI format into the DashScope format

Passthrough suits the DashScope native SDK or cases where you want to bypass translation entirely; translation suits direct OpenAI SDK integration.

FAQ

Q: The client reports 400 unsupported_feature? That "client protocol → upstream protocol" combination has no translator. Check the Protocol interop matrix. OpenAI → dashscope is supported.

Q: The client reports 401 / 403 / 404?

• 401: the access key isn't correct
• 403 model_access_denied: the key group's "Models" list doesn't include qwen-turbo
• 404 model_not_found: the model name is misspelled, or hide_name is set on it

Q: The client reports 502 bad_gateway? The upstream is unreachable. Check DashScope's base_url (https://dashscope.aliyuncs.com, no trailing /), whether the API key is correct, and whether it's in the Alibaba Cloud allowlist.

Q: Calling a video/image generation model reports 404? Async models need direct_path = true + the full endpoint URL + extra_config.dashscope.async_mode = true. See Upstream and model fields for details.

Next: Upstream and model fields for full upstream/model fields and all kind variants; Endpoints · auth · protocol interop for the full endpoint list; Client integration and gateway differences for SDK integration.