通过 OpenAI SDK 调用 Qwen API：DashScope 集成完整指南 (2026)

DashScope 把整个 Qwen 家族放在了一个兼容 OpenAI Chat Completions 协议的端点后面。你只需要改三个值就能把原来调 GPT-4o 的代码切到 Qwen3.8-Max、Qwen3.7-Plus 甚至百炼上托管的 DeepSeek V4、Kimi K3 和 GLM-5.3。不用重写请求格式，不用装新的客户端库。

这篇指南从"我还没有阿里云账号"讲到"我已经在网关里把 Qwen、Claude 和 GPT 串在一起跑了"。

OpenAI 兼容指供应商提供一个 chat-completions 接口，其请求与响应结构与 OpenAI API 契约足够接近——只需替换三个值（API key、base URL、模型名），原来的 OpenAI SDK 调用即可直接工作。最小实践面是POST /v1/chat/completions 带 messages、model， 并返回 OpenAI 形式的流式响应。

3 分钟跑通第一个请求

第 1 步，注册阿里云账号。 海外用户访问 alibabacloud.com，国内用户访问 aliyun.com，然后在控制台开通百炼（Model Studio）。

第 2 步，拿到 API Key。 打开百炼控制台的 API Key 页面，创建一把新密钥。密钥和地域绑定，北京区的密钥只能打北京端点，新加坡的密钥只能打新加坡端点。

第 3 步，装 OpenAI SDK。

pip install --upgrade openai

第 4 步，发请求。

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

response = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "用两句话解释 API 路由。"},
    ],
)

print(response.choices[0].message.content)

返回的响应对象和 OpenAI 的一模一样，id、choices、usage 字段全在。你原来写的解析逻辑不用动。

各地域 Base URL

DashScope 在多个地域运行，每个地域有独立端点。阿里云正在推动迁移到按工作空间隔离的新域名，性能和稳定性都更好。

把 {WorkspaceId} 换成你在百炼控制台看到的真实 ID。旧版 dashscope.aliyuncs.com 仍然能用，但阿里云建议所有新接入都走工作空间域名。

最常见的翻车场景是用北京的 API Key 去打新加坡的端点，DashScope 会返回 HTTP 401 invalid_api_key。Key 和端点的地域必须对上。

模型 ID 一览

DashScope 按代际和梯队组织模型。以下是 2026 年 8 月对 API 开发者最有参考价值的文本生成模型。

Max 梯队（旗舰）

Plus 梯队（均衡）

Flash / Turbo 梯队（速度和成本优先）

百炼上的开源模型

百炼上的第三方模型

DashScope 不只跑 Qwen。阿里云在同一个 OpenAI 兼容端点上托管了多家厂商的模型，换个 model ID 就能切到另一家。

这让百炼变成了一个多模型市场。一个账号、一把密钥，就能访问好几家中国 AI 实验室的模型。

思考模式（Chain-of-Thought 推理）

Qwen3.7-Max 和 Qwen3.8-Max 支持思考模式，模型先在内部跑一段推理链，再输出最终回答。你通过 OpenAI SDK 的 extra_body 参数开启。

response = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "user", "content": "证明根号 2 是无理数。"},
    ],
    extra_body={
        "enable_thinking": True,
        "thinking_budget": 10000,
    },
    stream=True,
)

开启思考模式后，流式输出的每个 chunk 里会多出一个 reasoning_content 字段，放的是推理过程。计费同时算思考 token 和最终回答 token。

想关掉思考模式，传 enable_thinking=False 即可。

Tool Calling（函数调用）

DashScope 的 OpenAI 兼容端点支持标准的 tools 参数。请求和响应格式和 OpenAI 一致。

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取某个城市的当前天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "城市名"}
                },
                "required": ["location"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "上海今天天气怎么样？"}],
    tools=tools,
    tool_choice="auto",
)

模型在 assistant 消息里返回 tool_calls 数组，你把函数执行结果以 tool 角色消息喂回去。流程和 OpenAI 完全一样。Qwen3.8-Max 和 Qwen3.7-Max 都支持并行 tool calls。

流式输出

标准的 stream=True 就能用。DashScope 返回的 chunk 对象和 OpenAI 的 chat.completion.chunk 格式一致。

stream = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "用俳句写一首关于 API 路由的诗。"}],
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

传 stream_options={"include_usage": True}，最后一个 chunk 里会带上 token 用量，方便你做成本追踪。

计费（北京地域，2026 年 8 月）

按百万 token 计费，单位是人民币。Max 梯队采用阶梯定价，单价取决于单次请求的输入 token 总量。

支持 Batch 调用的模型（qwen3.8-max、qwen3-max）享受 5 折。上下文缓存另有单独的输入折扣，缓存命中的 token 通常按标准输入价的 10% 计费。

海外地域价格更高。新加坡的 qwen3.8-max 输入价 ¥14.988/M，北京是 ¥12/M。

最新价格请查看 百炼定价页面。

常见错误及解决办法

HTTP 401 invalid_api_key 说明你的 API Key 和端点不在同一个地域。到你实际调用的那个地域的控制台重新创建 Key，或者换成和 Key 匹配的端点。

HTTP 404 可能用了 DashScope 原生协议的路径格式。你的 base URL 结尾应该是 /compatible-mode/v1，不是 /api/v1。

model not found 模型 ID 区分大小写。写 qwen3.8-max 而不是 Qwen3.8-Max。第三方模型要带供应商前缀，比如 ZHIPU/GLM-5.3-Flash。

思考 token 被计费但看不到推理过程 开了 enable_thinking=True 之后，推理 token 会计入 usage.completion_tokens，但推理链只在流式输出的 reasoning_content 字段里出现。如果你不开 stream，思考 token 照样计费，但你拿不到推理过程。

频率限制 DashScope 按模型和账号级别设有 QPM/TPM 限制，具体数值没有按模型公开。免费账号容易触顶，升级阿里云账号等级可以提高上限。

生产环境清单

1. 用工作空间域名。 旧版 dashscope.aliyuncs.com 没有按工作空间隔离。
2. 轮换 API Key。 DashScope 的密钥默认不过期，你要自己在 secrets manager 里设轮换周期。
3. 关注模型下线日历。 阿里云会周期性下线旧版 Qwen 快照。模型下线页面 列出了所有排期。我们在 DashScope 模型生命周期参考 里持续追踪。
4. 对重复 prompt 开上下文缓存。 系统提示词超过 1,024 token 且跨请求复用时，隐式缓存自动生效。显式缓存的用法参考 DashScope 缓存文档。
5. 测试思考模式的计费影响。 思考 token 可以把输出 token 量翻 2 到 5 倍。上线前先跑一批有代表性的请求看看账单。
6. 设 stream_options.include_usage 逐请求追踪实际 token 消耗。

通过路由网关统一管理 Qwen 和其他提供商

如果你的应用需要同时调 Qwen、Claude 和 GPT，API 路由网关可以挡在你的代码和上游 provider 之间。TheRouter 把 OpenAI 兼容请求路由到已配置的 provider（包括 DashScope），并且支持 fallback 链。DashScope 挂了或者限流了，请求自动回落到备选 provider。

典型配置方法是把你的应用指向 TheRouter 的端点而不是直接指向 DashScope，在 TheRouter 里把 DashScope 添加为 provider 并填上 API Key 和 base URL，然后设一条 fallback 链，先试百炼上的 Qwen3.8-Max，DashScope 返回 5xx 就切到 DeepSeek API。TheRouter 原样转发 OpenAI 兼容格式，两边的代码都不用改。

这种方案特别适合已经在用百炼做主力推理、同时需要对冲地域故障和临时限流的场景。

更完整的百炼平台介绍请参考 阿里云百炼 API 指南。Qwen3.7 系列的细节请看 DashScope Qwen3.7 系列指南。

常见问题

Node.js 的 OpenAI SDK 能用吗？ 可以。把 baseURL 设成 DashScope 的兼容端点，传入你的 DashScope API Key，写法和 Python 完全一样。

百炼支持 Batch API 吗？ 支持。标注"Batch 调用半价"的模型可以用 /v1/batches 端点，提交 .jsonl 请求文件后异步拿结果，每个 token 的价格打五折。

qwen3.8-max 和 qwen3.8-max-prime 有什么区别？ Prime 是速度优先的变体，单价翻倍（¥24/¥72 对比 ¥12/¥36），换取更低的首 token 延迟。适合对响应速度特别敏感的场景。

有免费额度吗？ 新账号在大多数 Qwen 模型上会获得 100 万 token 的免费额度，从开通百炼或模型发布之日起 90 天内有效（取较晚者）。百炼上的第三方模型可能有单独的促销额度。

百炼支持 Assistants API 或 Responses API 吗？ 百炼实现的是 Chat Completions 端点，不支持 OpenAI 的 Assistants API 和 Responses API。要做 Agent 编排，可以用百炼自己的应用 API，或者在 Chat Completions + tool calling 上自己搭 Agent 循环。