通义千问 Qwen API 怎么接入？百炼平台密钥与 SDK 调用

2026-07-07

数据截至 2026-07，价格与限额以各官网为准。

接入通义千问 API 的路径本身很短：开通阿里云百炼、拿到一串 DashScope API-KEY、用 OpenAI 兼容模式改两行代码就能跑通第一次调用；真正容易卡人的，是 base_url 该填哪一个、免费额度到底怎么算、模型代号选哪个这几处细节，官方文档在这几点上都有点”新旧并存”，没提前弄清楚很容易走弯路。

阿里云这条线的特点是更新快——旧的 qwen-max/qwen-plus/qwen-flash 经典命名还在用，Qwen3 系列的新版本又在不断往外放，端点地址也出现了新旧两种写法。这篇按真实接入顺序走一遍，把该核对的地方标出来，别的教程一笔带过的细节这里尽量说透。

第一步：开通百炼平台，拿到 API-KEY

访问阿里云百炼控制台：bailian.console.aliyun.com。

如果你是第一次访问，会弹出一份服务协议，阅读并同意之后，系统会自动帮你开通百炼服务，同时发放新人免费推理额度——这一步不需要额外申请，同意协议本身就是开通动作。如果你打开控制台没看到这个弹窗，大概率说明这个阿里云账号之前已经开通过百炼了，直接进后台操作就行，不用纠结”是不是漏了一步”。

开通之后，在控制台里找 API-KEY 管理这个页面，创建或者查看你的密钥。这里官方内部把它叫 DASHSCOPE_API_KEY，因为通义千问的原生调用协议叫 DashScope，这个密钥同时也是走 OpenAI 兼容模式时要用的凭证，两条路用的是同一把 key，不用分开申请。

跟很多平台一样，安全上的底线是别把这串密钥直接写进代码里，更别提交进 Git 仓库。放进环境变量里最省心，后面无论是原生 SDK 还是 OpenAI 兼容客户端，都能直接从环境变量读，不用每次手动传参数。如果你在团队里协作，建议给不同环境（本地开发、测试、生产）分别建 key，方便出问题时单独吊销，不至于一个环境泄露就要全员换密钥。

第二步：base_url 该填哪个？官方目前有两套写法

这是整个接入流程里最容易卡壳的地方，值得单独展开讲。

通义千问支持 OpenAI 兼容模式，意思是你原来用 OpenAI SDK 写的代码，改一下 base_url 和 api_key 基本就能直接切过来调用通义千问的模型，不用换 SDK、不用改调用写法。但官方文档目前存在两套 base_url 表述，而且没有完全统一，接入前最好心里有数：

经典端点写法（社区教程和不少官方页面仍在使用，验证最广泛）：

中国内地：https://dashscope.aliyuncs.com/compatible-mode/v1
新加坡（国际站）：https://dashscope-intl.aliyuncs.com/compatible-mode/v1

新出现的端点写法（按业务空间 WorkspaceId 区分，看起来是平台正在往新一代地域端点迁移）：

北京：https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
新加坡：https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
美国（弗吉尼亚）：https://dashscope-us.aliyuncs.com/compatible-mode/v1
日本（东京）：https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
德国（法兰克福）：https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1

新写法里的 {WorkspaceId} 不是随便填的占位符，得去百炼控制台的业务空间详情页查看你自己的空间 ID，替换进去才能用，直接复制粘贴带花括号的那串是调不通的。

老实说，这两套写法哪个是”标准答案”，官方文档本身也没有给出非常清晰的取舍说明，本文也不替你下结论。稳妥的做法是：先用经典端点（dashscope.aliyuncs.com/compatible-mode/v1）跑通，这条路径验证时间最长、社区案例最多；如果你在控制台里明确看到自己的业务空间被引导去用新端点，或者官方文档当页提示旧端点要下线，再切换过去。核心原则就一条——以你打开控制台或文档当页看到的内容为准，别照抄一篇过期教程里的地址。

Python 最小调用示例

装好 OpenAI 官方 SDK（pip install openai），几行代码就能跑通：

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # 按上面地域/新端点按需替换
)

completion = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "你是谁？"},
    ],
)
print(completion.model_dump_json())

几个细节提一下。第一，因为走的是 OpenAI 兼容模式，client 用的就是 OpenAI 官方的 SDK 包，不用额外装阿里云自己的 SDK，改 base_url 和 api_key 两个参数就切过来了，其余调用写法（messages 结构、流式输出等）跟平时用 OpenAI SDK 一致，迁移成本很低。第二，model 字段这里填的是 qwen-plus，如果你想换成 qwen-max、qwen-flash 或者 Qwen3 系列的新模型，直接改这个字符串就行，其它代码不用动——但模型代号具体怎么选、贵不贵，涉及计费细节，本文不展开，放在计费那篇里讲更合适。第三，返回结构走的是标准 OpenAI 格式，用 completion.model_dump_json() 或者按 OpenAI SDK 惯常的取值方式拿 choices[0].message.content 都行，不用额外学一套新的响应解析逻辑。

如果你更习惯用阿里云原生的 DashScope SDK（非 OpenAI 兼容模式），官方也提供对应的原生调用文档，字段命名和响应结构跟 OpenAI 兼容模式不完全一样，两条路选一条走完整就行，别混用。

免费额度：90 天怎么用、覆盖到哪

开通百炼的新用户会拿到一笔免费推理额度，这里有个时间点要注意：自 2025-09-08 11:00 起，新开通账号的免费额度有效期统一调整为 90 天（在这个时间点之前已经开通过的老账号不受影响，按各自原来的规则走）。

额度大小以官方模型详情页当时标注的为准，这里只能给个感受性的参考：官方文档里对 qwen-max 的免费额度描述是输入、输出各 100 万 tokens 这个量级，合起来大概是 200 万 token 上下浮动；其他模型比如 qwen-plus 各自有独立的免费额度池，模型之间不互通——也就是说你用 qwen-max 把额度用光了，qwen-plus 那份额度不受影响，还能接着用。

有几个边界条件容易被忽略：

主账号和它下面的 RAM 子账号共享同一份免费额度，是统一计算消耗的，不是每个子账号各领一份。
免费额度只抵扣实时推理调用这一种场景，Batch 批量调用、Context Cache 上下文缓存、模型调优、模型部署这些场景的费用，免费额度覆盖不到，得单独按量付费。
中国内地版和新加坡（国际）版的免费额度是分别独立核算的，不互通，如果你两边账号都开了，别以为额度是共用的。
额度用完之后，未完成实名认证的账号会直接调不通，得先完成企业或个人实名认证，并完成充值，才能转入按量付费继续调用。

常见坑 / 注意

base_url 别选错地域：中国内地和新加坡（国际）走的是两个不同的域名，账号体系、免费额度都是分开算的，选错了轻则调不通，重则额度对不上账。
新端点里的 WorkspaceId 是真实值不是占位符：花括号里那串字符要去控制台业务空间详情页查真实 ID 替换，直接复制文档原文是跑不通的。
API-KEY 别硬编码进代码：放环境变量，别提交进 Git，泄露了及时在控制台吊销重建。
免费额度不含 Batch 和 Context Cache：以为免费额度能覆盖所有调用方式是常见误解，这两类场景免费额度不抵扣。
模型代号迭代很快：qwen-max/qwen-plus/qwen-flash 这些经典命名，和 qwen3.5/qwen3.6/qwen3.7 这类新版本目前是并存状态，写死某个模型名之前，建议先去百炼「模型广场」核对一下这个代号是不是还在正常提供服务。
免费额度用完别硬调：没做实名认证就想继续白嫖额度是行不通的，账号会直接调不通，提前规划好实名和充值的时间点。