千问(Qwen,原「通义千问」)大模型的官方 API 由阿里云百炼大模型服务平台提供,控制台入口是 bailian.console.aliyun.com。注册阿里云账号并实名认证、开通百炼后,在「API Key 管理」创建以 sk- 开头的密钥即可调用。国内默认接入地址为 https://dashscope.aliyuncs.com/compatible-mode/v1,与 OpenAI 接口完全兼容,改 base_url 就能复用现有代码。旗舰模型 Qwen3.7-Max 支持 1M 上下文,输入 12 元、输出 36 元每百万 token,新用户通常有 90 天有效的免费体验额度。 千问 API 官方入口与百炼平台的关系
「千问 API」分散在好几个长得像入口的页面里,动手前先分清,能省掉一整天无效摸索:
- 百炼模型广场:控制台内的模型列表,浏览全部千问系列与三方模型、试玩对话、查看模型说明。
- API 密钥管理页:控制台左侧「API Key」,创建、复制、吊销密钥。
- DashScope 开发文档:阿里云 DashScope 是底层模型网关,千问调用兼容 OpenAI 接口,也提供 dashscope SDK。
- 千问 App / 通义客户端:面向普通用户的聊天产品,不提供 API Key,别在上面找开发者入口。
- 海外版 Model Studio:国际站点 dashscope-intl,面向海外区域,计价与国内不同。
注意区分:品牌层面,「通义千问」已更名「千问大模型」,接口与模型 ID 不受影响,旧文章里的 qwen-plus、qwen-max 这类命名仍在沿用;产品层面,消费者聊天 App 与开发者 API 是两套体系,拿 API Key 一律走百炼控制台。
千问 API Key 获取步骤与调用示例
核心流程可以压缩成四步,全程国内环境,无境外门槛:
- 注册并实名:注册阿里云账号,完成个人或企业实名认证(这是调用前置条件);
- 开通百炼:登录 bailian.console.aliyun.com,阅读并同意协议即自动开通,无需预付;
- 创建 API Key:进入「API Key」页面点击创建,生成以 sk- 开头的密钥,完整密钥只展示一次,立即复制并写入环境变量(如 DASHSCOPE_API_KEY);
- 发起首次调用:安装 OpenAI SDK 或 dashscope SDK,填对 base_url、密钥与模型名即可。
OpenAI SDK 兼容方式的最小示例:
- 接入地址:https://dashscope.aliyuncs.com/compatible-mode/v1(华北 2 北京等默认区域)
- 鉴权:api_key=os.getenv("DASHSCOPE_API_KEY")
- 模型:model="qwen3.7-max" 或 qwen3.7-plus、qwen-plus、qwen-turbo 等
- 调用:client.chat.completions.create(model=..., messages=[...])
开启深度思考的模型(如 qwen3.7-max)可在请求中带 enable_thinking / thinking_budget 参数,流式响应会先返回 reasoning_content 再返回正文。
需要注意:思维链内容全部计入输出 token,会真实产生计费消耗,成本测算要把它算进去。部分海外地域(新加坡、东京、法兰克福、中国香港等)要求在调用域名中携带业务空间 ID(WorkspaceId),具体格式以官方「首次调用千问 API」文档为准;美国(弗吉尼亚)区域则使用独立接入域名。
千问 API 调用的注意事项
- 密钥只显示一次:sk- 开头的 API Key 生成后仅完整展示一次,丢失只能删除重建;生产环境一律用环境变量或密钥管理服务存放。
- 别混用计费模式的 Key 和地址:按量计费 Key、Token Plan 套餐 Key、Coding Plan Key 各有专属 Base URL,混用会出现 401 Incorrect API key provided 一类报错。
- 模型名要区分大小写:qwen3.7-max 写错大小写或用了不在支持列表的旧 ID,直接返回 404 model_not_found。
- 纯文本模型别传图片:向纯文本模型传图像会报 invalid_parameter_error,视觉任务要改用多模态版本(如支持视觉的 qwen3.7-max 快照版或 VL 系列)。
- 深度思考会多花钱:开启 enable_thinking 后思维链 token 全部计费,且思考模式下有效上下文会相应缩小,长任务要提前预算。
- 注意地域与数据合规:百炼提供北京、新加坡、东京、法兰克福、中国香港等多地域节点,数据出境与跨境部署请结合业务合规要求选择区域。
千问模型清单与最新价格
截至本文核查时间(2026 年 9 月 9 日),百炼主力模型与官方计价(中国境内,人民币 / 每百万 token)整理如下。旗舰 Qwen3.7-Max 的完整价目来自阿里云官方帮助中心:
模型梯队速览:
| | | |
|---|
| | | 支持深度思考与函数调用;2026-06-08 快照版新增视觉理解;另有仅思考模式的 preview 版本 |
| | | |
Qwen3.6-Plus / Qwen3.6-Flash | | | 3.6 系列已上线百炼,Plus 侧重编程与多模态 |
| | | |
| | | |
| | | |
模型迭代很快,上述非 Max 模型的具体单价与上下文参数建议以百炼控制台「模型广场」的实时标价为准。省钱三板斧:长提示词吃上下文缓存(命中价约为标准输入 2 折);非实时任务走Batch 文件批处理(约 5 折);夜间批量任务关注 NightPlan 夜间折扣权益。
千问 API 计费方式与免费额度
百炼提供多种计费模式,按阶段选型可以省不少钱:
- 按量后付费:按输入、输出 token 分别计费,适合初期测试与小规模使用,默认开启;
- Token Plan 订阅:预购 Credits 额度,个人版与团队版,调用优先抵扣 Credits,单价低于按量原价,适合用量稳定的业务;
- 资源包 / 抵扣包:官方不定期上架「千问大语言模型推理通用抵扣包」等省钱计划,按承诺消费金额阶梯折扣;
- Batch 与夜间权益:文件批处理约 5 折;已开通 Token Plan 的用户可享 NightPlan 夜间(约 22:00–次日 8:00)折扣,适合离线任务。
免费额度:新用户开通百炼后通常赠送一定免费体验额度,资料多指向 90 天有效期,覆盖千问系列模型;具体到账数量与单模型额度在不同时期政策不同,务必以控制台「免费额度」页面的实际显示为准。控制台支持「免费额度用完即停」开关,测试阶段建议开启,避免意外进入按量计费。
限流方面,百炼按模型与区域设置 RPM / TPM 上限(旗舰模型基础配额通常在每分钟数百次请求级别),正式上线前可在控制台查看当前配额并申请提升。选型建议一句话:日常高频简单任务用 Qwen-Turbo / Flash 档,常规业务用 Plus 档,真正需要深度推理、复杂工具编排再上 Max。
千问 API 常见报错与排查
错误响应体包含 request_id、code、message 三个字段,排查时先看 code 精确定位,保留 request_id 便于提工单:
| | | |
|---|
InvalidApiKey: No API-key provided | | | |
InvalidApiKey: Invalid API-key provided | | 密钥无效:复制不完整、已过期,或误用了其他计费模式的 Key | 确认使用对应计费模式的 Key,完整无空格,必要时重新创建 |
Incorrect API key provided | | | 按套餐核对专属 Base URL(如 Token Plan 专属地址) |
AccessDenied.Unpurchased / Model.AccessDenied | | | |
ModelNotFound / model_not_found | | | |
| | | |
| | | |
Requests rate limit exceeded | | | |
| | | |
Throttling / Throttling.RateQuota / Throttling.AllocationQuota | | | |
InternalError / RequestTimeOut | | | 记录 request_id,稍后重试,持续出现则提工单 |
| | | |
| | | |
千问 API 开放平台常见问题
Q:千问 API 免费吗?
A:新用户开通阿里云百炼后通常有 90 天有效的免费体验额度,覆盖千问系列模型,具体数量以控制台显示为准;额度用完后按量计费。
Q:通义千问和千问大模型是一个东西吗?
A:是同一个产品线的不同叫法。品牌已从「通义千问」更名为「千问大模型」,底层接口与模型 ID(qwen-plus、qwen-max 等)完全不变。
Q:API Key 在哪里创建?
A:登录阿里云百炼控制台(bailian.console.aliyun.com),左侧「API Key」页面点击创建即可,密钥以 sk- 开头、只完整显示一次。
Q:调用地址填什么?
A:国内默认用 OpenAI 兼容地址 https://dashscope.aliyuncs.com/compatible-mode/v1;部分海外地域需要携带业务空间 ID 的专属域名,美国(弗吉尼亚)区域另有独立域名,以官方文档为准。
Q:OpenAI SDK 的代码能直接用吗?
A:能。百炼的 OpenAI 兼容接口请求响应结构与 OpenAI 一致,只需替换 base_url、API Key 和模型名即可。
Q:创建 API Key 时要选模型吗?
A:不需要。调用时通过请求体的 model 参数指定模型;如需限制某把 Key 只能调特定模型,创建时可开启自定义权限并勾选模型范围。
Q:为什么报 401 Incorrect API key provided?
A:通常是 Key 与 Base URL 的计费模式不匹配——比如用了按量 Key 却指向 Token Plan 专属地址。换成与套餐一致的 Base URL 即可。
Q:深度思考模式和普通模式有什么区别?
A:深度思考模式下模型先生成内部推理(reasoning_content)再输出最终答案,质量更高但更慢更贵——思维链 token 全部计入输出计费,有效输入长度也会缩小。
Q:免费额度用完会直接扣钱吗?
A:控制台提供「免费额度用完即停」开关,开启后额度耗尽即停止调用,不会产生账单;不开则进入按量计费。测试期建议开启。
Q:国内能直接用吗?需要境外支付吗?
A:可以直接用。百炼是阿里云国内服务,手机号注册、境内实名认证、人民币结算,数据默认存储在国内区域,无境外门槛。
Q:上下文很长会很贵吗?
A:不同模型按长度分档计价,超档会跳价。省钱的正确姿势是:长固定上下文用显式缓存、重复场景吃隐式缓存命中价、非实时任务走 Batch,能显著压低成本。
Q:视觉任务该用哪个模型?
A:Qwen3.7-Max 的 2026-06-08 快照版本已支持视觉理解;更轻量的场景可选用千问 VL 系列多模态模型,成本更低。
Q:qwen3.7-max 有 preview 版本吗?和正式版差在哪?
A:有 qwen3.7-max-preview,仅支持思考模式、纯文本输入,面向实验性任务;正式版(含快照)能力更全,生产环境优先用正式版。
Q:报错里的 request_id 有什么用?
A:request_id 是单次请求的全局唯一标识。提工单或找官方排查时必须附上它,否则对方无法定位你的请求记录。
以上内容仅供参考,阿里云百炼的模型版本、价格、免费额度与计费政策可能随时调整,请以百炼控制台模型广场与 help.aliyun.com 官方文档的最新公布为准。