第 1 课
开通百炼,用 curl 和 Python 调通 qwen4-max
认清 qwen4-max 与预览版的差别,在华北 2(北京)拿到 API Key 和业务空间 ID,用业务空间专属域名以 curl 和 Python 发出第一个请求,看懂默认思考、免费额度和计费,并用假 Key 复现 401。
课程目录第 1 / 3 课
学习位置仅保存在当前浏览器,有效期 180 天。
开通百炼,用 curl 和 Python 调通 qwen4-max
本课对照阿里云百炼官方文档「qwen4-max(最新模型)」「文本生成」「获取与配置 API Key」「地域和接入域名」「新人免费额度」「模型调用价格」编写。命令在 2026-11-18 核对;成功回复采用官方示例,401 为同日用假 Key 实打。
本课目标
- 认清
qwen4-max和预览版的差别,选对北京地域和业务空间专属域名 - 开通百炼、拿到 API Key 和业务空间 ID,配好环境变量
- 用 curl 和 Python 发出第一个请求,看懂默认思考和计费
- 用假 Key 复现 401,确认请求打到了百炼而不是写错地址
前置条件
- 已实名认证的阿里云账号
- 本机有 curl 和 Python 3.9 或更高版本
- 会在终端里设置环境变量
第 1 步:先认清要调用的模型
Qwen4-Max 是 2026 年 11 月 16 日发布的旗舰多模态模型。调用时 model 参数写 qwen4-max,不要写成仍在预览通道里的 qwen4-max-preview。预览版走 Token Plan 专用地址,本课用的是按量计费(免费额度也走这条)。
官方模型页给出的关键规格(华北 2(北京),2026-11-17 更新):
| 项目 | 数值 |
|---|---|
| 上下文长度 | 1,000,000 Token |
| 非思考:最大输入 / 输出 | 991,808 / 131,072 |
| 思考:最大输入 / 思考+回答 | 983,616 / 262,144 |
| 默认思考开关 | enable_thinking=true |
| 默认推理强度 | reasoning_effort=high |
| 默认思考预算 | thinking_budget=131072 |
| 输入模态 | 文本、图像、视频 |
| 输出模态 | 文本 |
未传入 reasoning_effort 和 thinking_budget 时,官方默认就是上表这两项。思考模式下,思维链 Token 按输出计费。
价格和免费额度也以模型页和价格页为准。华北 2(北京)实时推理:
- 输入 10 元 / 百万 Token,输出 30 元 / 百万 Token(思维链 + 回答)
- 新人免费额度 100 万 Token,从开通百炼、模型发布或申请通过之日起 90 天内有效(以较晚者为准)
- 官方写明:仅北京地域有免费额度,其他地域没有;免费额度只抵扣实时推理,主账号和 RAM 子账号共用,不能跨模型挪
建议在控制台打开「免费额度用完即停」,额度耗尽时停止服务,避免悄悄转到按量付费。查看剩余额度和开关规则,见官方「新人免费额度」文档。
国际站或新加坡账号另有 QwenCloud 文档中的免费额度说明,接入域名也不同。本课只跟做北京地域的百炼路径,因为中文用户的免费额度在这里。

2026-11-18 用无头浏览器对下面这个地址实拍。文档站样式表可能未完全加载,正文与官方一致。
第 2 步:开通百炼,拿到 API Key 和业务空间 ID
按官方「获取与配置 API Key」「新人免费额度」和「首次调用」的步骤,做这几件事:
- 用已实名的阿里云账号登录百炼控制台。首次进入时系统会自动开通,一般不必再点一次确认。
- 页面右上角把地域切到 华北 2(北京)。每个地域的 API Key、域名和模型列表都不能混用。
- 打开北京地域的 API Key 页: https://bailian.console.aliyun.com/cn-beijing/model/settings/api-key
- 单击「创建 API Key」。归属账号一般用主账号,归属业务空间用默认业务空间即可,权限建议选「全部」。
- 创建成功后立刻复制完整 Key,并同时复制弹窗里的 API Host。新版 Key 只在这一次完整显示,关掉对话框后列表里只剩脱敏值。
- 按官方「新人免费额度」文档打开「用完即停」。
API Host 的形式是:
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
{WorkspaceId} 就是业务空间 ID,常见写法类似 llm-xxxxxxxx。也可以到业务空间管理页复制「API Host」列,再去掉协议和域名,只留下这一段 ID。
本课全程使用 业务空间专属域名。官方「地域和接入域名」写明:这是推荐的生产接入方式;旧的 dashscope.aliyuncs.com 自 2026 年 9 月 30 日起不再支持新特性。Qwen4-Max 的思维链摘要和显式缓存都属于新能力,不要再用旧域名。
第 3 步:把 Key 和业务空间 ID 配进环境变量
不要把 Key 写进代码或笔记本。在当前终端会话里临时配置即可(把尖括号里的内容换成你的真实值,不要保留尖括号):
export DASHSCOPE_API_KEY='<YOUR_API_KEY>'
export WORKSPACE_ID='<YOUR_WORKSPACE_ID>'
echo "Key 前缀:${DASHSCOPE_API_KEY:0:8}********"
echo "业务空间:${WORKSPACE_ID}"
官方示例里的接入地址直接写成 {WorkspaceId}。下面为了便于复制,用环境变量 WORKSPACE_ID 拼出同一条地址,效果与官方一致。
如果只想先确认变量在,应看到自己的业务空间 ID,以及 Key 的前 8 位加一串星号。不要把完整 Key 贴到聊天、截图或代码仓库里。
第 4 步:用 curl 发出第一个请求
先安装并不需要。直接在同一个终端执行(官方「文本生成」快速开始里的 curl,只是把 {WorkspaceId} 换成了变量):
API="https://${WORKSPACE_ID}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
curl -X POST "$API/chat/completions" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen4-max",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "你是谁?"
}
]
}'
这条请求没有关思考。qwen4-max 默认 enable_thinking=true,所以第一次调用往往会先思考再回答,等待时间比普通聊天更长,返回的 message 里通常还有 reasoning_content。
官方「文本生成」页用下面这段作为 content 的对照,并注明完整 JSON 示例来自 qwen3.8-max,用来说明字段,而不是保证你这次的用字完全相同:
我是千问,阿里巴巴集团旗下的通义实验室自主研发的超大规模语言模型
。我可以帮助你回答问题、
创作文字,比如写故事、写公文、写邮件、写剧本、逻辑推理、
编程等等,还能表达观点,
玩游戏等。如果你有任何问题或需要帮助,欢迎随时告诉我!
官方给出的字段结构如下。你实际返回里还会有 id、created 等,思考开启时 message 会多出 reasoning_content,usage.completion_tokens 也会把思维链算进去:
{
"choices": [
{
"message": {
"role": "assistant",
"content": "(与上一段官方示例全文相同,这里省略以免代码块溢出)"
},
"finish_reason": "stop",
"index": 0,
"logprobs": null
}
],
"object": "chat.completion",
"usage": {
"prompt_tokens": 26,
"completion_tokens": 66,
"total_tokens": 92
}
}
如果只想先尽快看到一句回复、暂不看思考过程,把请求体加上一行(仍是官方深度思考文档里的开关):
"enable_thinking": false
curl 的 JSON 里它是顶层字段,和 model、messages 并列。下一课再专门看思考过程。
第 5 步:用 Python 再调一次
先安装官方示例使用的 OpenAI SDK:
pip install -U openai
新建 hello_qwen4.py。下面在官方「文本生成」Python 示例的基础上,只把 Base URL 改成从环境变量读取,并多打印 usage:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url=(
f"https://{os.getenv('WORKSPACE_ID')}"
".cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
),
)
completion = client.chat.completions.create(
model="qwen4-max",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "你是谁?"},
],
)
message = completion.choices[0].message
print(message.content)
print(completion.usage)
运行:
python3 hello_qwen4.py
content 应与第 4 步同类,是一段自我介绍。usage 会给出 prompt_tokens、completion_tokens 和 total_tokens。思考开启时,还可在 message.reasoning_content 里看到思维链。
enable_thinking 不是 OpenAI 标准参数。若要在 Python SDK 里显式开关思考,放进 extra_body,例如 extra_body={"enable_thinking": False}。Node.js 和 curl 则写在请求体顶层。
第 6 步:按 usage 估算费用
免费额度把一次请求的输入 Token 和输出 Token 加在一起扣减,不分开记账。额度用完或过期后,按北京实时单价结算:输入 10 元 / 百万 Token,输出 30 元 / 百万 Token。
用官方示例里的 prompt_tokens=26、completion_tokens=66 做一道算术(方便对公式,不是你这次调用的账单):
输入:26 / 1,000,000 × 10 元 = 0.00026 元
输出:66 / 1,000,000 × 30 元 = 0.00198 元
合计:0.00224 元
思考开着时,输出会包含思维链,completion_tokens 往往比 66 大得多,费用主要出现在输出侧。默认 thinking_budget 是 131,072,第一次练习不必改它;若只是验证连通,用 enable_thinking: false 更省额度和时间。reasoning_effort 的取值是 low、high、xhigh,默认 high,下一课再调。
Token Plan 专用 Key 不会消耗这笔新人免费额度。本课请用控制台创建的普通 API Key。
第 7 步:用假 Key 看 401
把 Key 换成一段明显无效的值,确认报错来自百炼,而不是域名写错。2026-11-18 在本机对业务空间风格的域名实打结果如下(llm-placeholder 只是占位,你应继续用自己的 WORKSPACE_ID):
API="https://${WORKSPACE_ID}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1"
curl -sS -X POST "$API/chat/completions" \
-H "Authorization: Bearer sk-invalid-kunnet-course-test" \
-H "Content-Type: application/json" \
-d '{"model":"qwen4-max","messages":[{"role":"user","content":"你是谁?"}]}'
官方返回的 message 是一行,里面带着错误码文档地址。完整原文在 transcripts/401-workspace-placeholder.json。字段如下(地址单独写出,以免代码块横向滚动):
{
"error": {
"message": "Invalid API-key provided. For details, see: …",
"id": "9ada8238-3055-9e33-9b90-cc1b69a99dd1",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}
错误码说明:
https://help.aliyun.com/zh/model-studio/error-code#apikey-error
HTTP 状态码是 401,code 为 invalid_api_key。同一天对旧域名 dashscope.aliyuncs.com 用同一段假 Key,返回同样的 code,只是 message 写成了 Incorrect API key provided。看到这个码,说明请求已经到达百炼,把环境变量改回真实 Key 即可。若是 DNS 失败或完全没有 JSON,先检查 WORKSPACE_ID 是不是只含业务空间 ID、有没有多抄一层域名。
更多错误码见:
常见坑
- 用了
qwen4-max-preview或 Token Plan 专用地址,按量 Key 会调用失败。本课的模型 ID 是qwen4-max。 - 地域和 Key 不匹配。北京的 Key 不能打到新加坡或弗吉尼亚的域名上。
- 继续使用
https://dashscope.aliyuncs.com/compatible-mode/v1。官方已说明该域名不再支持新特性。 - 刚开通百炼,免费额度可能延迟出现,官方说通常两小时内生效。
- 把 API Key 写进脚本后提交到 Git。本课只从环境变量读取。
小结
你已经在北京地域拿到 Key 和业务空间 ID,用 curl 和 Python 调通了 qwen4-max,并看懂默认思考、免费额度和 401。下一课会把思考过程打印出来,打开思维链摘要与加密,再让模型读一张官方示例图。

