千问API开放平台的5个官方入口
先解决一个容易绕晕的点:调千问接口的平台不叫"千问开放平台",官方产品名是「阿里云百炼」。「千问」是模型和 C 端产品的品牌,「百炼」才是承载 API 的平台,「DashScope」是它更早的名字,所以官方示例里的环境变量至今还叫 DASHSCOPE_API_KEY。
五个官方入口各管一段:
- 百炼产品介绍页(www.aliyun.com/product/bailian):先看能力范围和计费概览再决定上不上手。dashscope.aliyun.com 现在会 301 跳到这里,它已不是独立站。
- 百炼官方文档中心(help.aliyun.com/zh/model-studio):API 参考、模型列表、定价表、错误码、限流条件全在这一条路径下。旧的 help.aliyun.com/zh/dashscope/ 已 404,收藏夹里的老链接该换了。
- 千问产品官网(www.qianwen.com):面向普通用户的对话产品,和 API 开放平台是两条独立产品线。这里聊天免费,但生成不了 API Key。
- 国际站控制台(modelstudio.console.alibabacloud.com):面向海外账号,界面为英文,模型清单和定价与国内站不同。
有三个入口已经变过,照旧教程走会卡住。 旧控制台域名 dashscope.console.aliyun.com 打开只显示"该域名已下线";通义官网 tongyi.com 会直接跳到千问官网,还带一个 ch=tongyi_redirect 参数。都属官方自家域名迁移。按需求分流:调接口走百炼,聊天走千问官网,海外账号走国际站。
百炼API Key获取与环境变量配置
从零到第一次调通,五步。
- 注册阿里云账号并完成实名认证,未实名的账号拿不到付费调用能力。
- 开通阿里云百炼。用主账号进入百炼大模型服务平台,阅读并同意服务协议后系统自动开通;没弹出协议说明你之前已开通过。
- 创建 API Key。进入百炼的 API Key 页面,先确认右上角选的是哪个地域,再点"创建 API Key"。弹窗里可配置归属账号、业务空间和权限,选"自定义"能进一步限定可访问 IP 与模型范围。
- 复制 Key 并配到环境变量。官方示例的变量名是 DASHSCOPE_API_KEY,Windows 用 setx,macOS 和 Linux 追加到 ~/.zshrc 或 ~/.bashrc。
- 用官方接口做一次连通性验证,确认 Key 生效、地域选对。
三条安全红线,加粗记住:
- API Key 以 sk- 开头。 别带多余空格或换行,也确认没拿成别家的密钥。最常见的错误是变量名写错:api_key=os.getenv("sk-xxx") 会让程序去找一个叫 sk-xxx 的环境变量,正确写法是 api_key=os.getenv("DASHSCOPE_API_KEY")。
- Token Plan 和 Coding Plan 团队版发的专属 Key 以 sk-sp- 开头,必须配各自的专属 Base URL,和通用 Key、通用地址混用会直接返回 401。
- 不要在浏览器、移动应用这类客户端代码或不可信环境中放长期有效的 API Key(官方明确要求),可改用最长 1800 秒的临时 API Key。
调用地址有两套官方口径并存,这个坑不小:
| |
|---|
| https://dashscope.aliyuncs.com/compatible-mode/v1 |
| https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1 |
| https://{WorkspaceId}.ap-southeast-1.maas.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 |
| https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1 |
| https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1 |
老地址 dashscope.aliyuncs.com 仍能正常使用,官方建议迁到业务空间专属域名,理由是性能和稳定性更好。{WorkspaceId} 换成你的业务空间 ID,在控制台业务空间管理页可查。
还有一条硬规则:每个地域有独立的接入域名、API Key 和模型列表,三者不能跨地域混用。
千问模型价格与上下文长度对照
千问系列模型按输入 Token 和输出 Token 双向计费,计费模式分两档:一部分单价固定,另一部分实行阶梯计费。
| | | |
|---|
| | | |
| | | |
| | | |
| | 0 < Token ≤ 128K;128K < Token ≤ 256K | |
| | 0 < Token ≤ 32K;32K < Token ≤ 128K;128K < Token ≤ 256K | |
| | | |
| | | |
| | 0 < Token ≤ 32K;32K < Token ≤ 256K;256K < Token ≤ 1M | |
华北2(北京)地域的刊例价,单位是元 / 百万 Token:
| | |
|---|
| | |
| | |
| | |
qwen3.6-max-preview(0 < Token ≤ 128K) | | |
qwen3-max(0 < Token ≤ 32K) | | |
| | |
| | |
qwen3.7-flash(0 < Token ≤ 32K) | | |
三条规则直接决定账单数字:
- 阶梯计费看的是单次请求的输入 Token 总量。 单价由这一次请求的输入长度决定,而整个请求的所有 Token(含输出)都按落档那一档的单价结算。比如某模型分 32K、128K 两档,你一次输入 100K Token,落在第二档,全部 Token 都按第二档计价。K 代表 1,000,M 代表 1,000,000。
- Batch 调用半价。 支持 Batch 的模型,输入输出单价均按实时推理价格的 50% 计费。
- 上下文缓存另有折扣。 显式缓存创建按标准输入单价的 125% 计费,命中按 10% 计费。Batch 折扣和缓存折扣不能同时生效。
以上是华北2(北京)刊例价,控制台里另有活动优惠。Plus 档(如 qwen3.7-plus)的价格按"非思考模式 / 思考模式"分列展示,官方定价页这一档的表格结构与 Max、Flash 档不同,具体数值以定价页实时表格为准。
百炼免费额度与消耗优先级规则
百炼默认是按量后付费,没有强制预充值。首次开通百炼时,平台会自动发放各模型的新人免费额度,不用手动领取。规则有六条:
- 只有华北2(北京)地域的模型有免费额度,其他地域一律没有。 把地址换成新加坡,额度立刻不生效。
- 有效期 90 天,从开通百炼、模型发布或模型申请通过之日起算,以较晚者为准。到期自动失效,不补发、不延期、不重置,用不用都在计时。
- 每个模型有独立额度,通常是 100 万 Token。 不互通、不共享、不能跨模型合并。带日期后缀的快照版(如 qwen3.8-max-0902)与不带日期的最新版算两个独立模型。某个模型额度用完,系统不会自动切到别的有额度的模型。
- 剩余量是输入和输出共用的总额度,控制台显示的余量是扣完后的 Token 总数。
- 主账号和它的 RAM 子账号共享同一份额度,两边消耗放在一起算。
- 只抵扣模型实时推理的费用。 Batch 调用、模型调优、模型部署、PAI-DSW、OSS 存储及请求费用都不支持抵扣。
扣费顺序固定为 免费额度 > 资源包 > 节省计划 > 按量付费,实时调用会自动优先使用免费额度。
有个默认行为要提前知道:「免费额度用完即停」(部分用户叫"安心模式")。开启后额度耗尽会直接停止响应并返回 HTTP 403,错误码 AllocationQuota.FreeTierOnly,不再扣费。未实名认证的用户由系统强制开启且不能关闭。官方文档写得很直接:生产环境不建议开启,以免额度耗尽导致服务不可用。 余量降到 20% 或耗尽时会有短信、站内信、邮件提醒,余量与用量在控制台的免费额度页、模型广场、模型用量页三处可查。
用量稳定且偏大的可以考虑 Token Plan 订阅:以 Credits 统一计量,可用于 Claude Code、Cursor、Qwen Code、Codex、Qoder、OpenClaw 等工具,个人版分 Lite、Essential、Standard、Pro 四档,按 7 天窗口限额。两点要注意:它目前只支持华北2(北京)地域;它的专属 API Key 不消耗免费额度,调用会直接按量付费。原 Coding Plan Lite 已于 2026 年 3 月 20 日停止新购、4 月 13 日停止续费和升级。 千问API常见报错与限流排查
下面这张表按状态码整理,条目都能在官方错误码文档里对到。
| | |
|---|
| | 到费用与成本页面充值,到账几分钟后恢复;欠费期间即使还有免费额度也无法调用 |
| | 确认 Key 以 sk- 开头、没混入别家平台的密钥;环境变量名要写 DASHSCOPE_API_KEY,别把 sk- 开头的 Key 当变量名;sk-sp- 专属 Key 必须配专属 Base URL |
403 AllocationQuota.FreeTierOnly | | 关闭"免费额度用完即停"开关即可转为按量付费;未实名认证的用户需要先认证并充值 |
| | 到模型广场确认该模型已开通;也可能是模型已下线,需按下线说明换用替代模型;Token Plan 专属模型必须用专属 Key |
| | 对照模型列表核对 model 参数的大小写和拼写;别把开源社区的模型名当百炼 ID 用(应写 qwen3-235b-a22b-instruct-2507,而不是带斜杠的仓库名);国际站各地域可选模型不同 |
| | 降低调用频率或稍后重试。如果单次请求就返回 429,检查请求头是不是误设了 X-DashScope-Async: enable |
429 Throttling.AllocationQuota | 每秒或每分钟消耗 Token 数(TPS / TPM)超限 | 按限流文档调整调用策略;默认额度不够用可联系商务经理申请提额 |
| | 改成匀速调度、指数退避,或加请求队列缓冲,别让流量瞬时打尖 |
429 Throttling.Concurrency | | 等片刻重试。平台按整体负载动态调整并发上限,高峰时段更容易触发 |
| | 稍后重试;用 Qwen-Omni 等要求流式输出的接口时确认已设 stream=true |
限流按每分钟计量,同时看两个指标:RPM(每分钟调用次数) 和 TPM(每分钟消耗 Token 数,含输入与输出),任一超出即触发,服务也可能按 RPS(RPM/60)和 TPS(TPM/60)限制。
部分模型在限流表上标的是"动态限流"(qwen3.8-max、qwen3.8-flash、qwen3.7-max、qwen3-max 等),没有固定数字。有明确数值的例子:qwen3.7-max-2026-06-08 为 600 RPM / 1,000,000 TPM,qwen-max 为 1,200 RPM / 1,000,000 TPM。还有一条实惠规则:用 Batch API 调用不受限流限制。
排查报错时顺手记下 Request ID(UUID 格式,形如 649b2bbc-c541-9e16-9845-db7fe4fe5b2d),它出现在 API 响应的 Header 或 Body 里,提工单时要用。没记下也能在控制台模型监控页按模型查调用记录,里面有 Request ID、状态码和错误码。
千问API开放平台常见问题
Q:千问API开放平台官网到底是哪个?
A:控制台是 bailian.console.aliyun.com,介绍页是 www.aliyun.com/product/bailian。官方产品名叫"阿里云百炼",没有单独的"千问开放平台"站点。
Q:调千问接口要花钱吗?
A:新用户开通百炼后,每个模型自动获得约 100 万 Token 免费额度,90 天有效,用完后按量后付费。
Q:免费额度为什么显示不出来?
A:三个常见原因:已到期或耗尽;该模型不在华北2(北京)地域;该模型本身不参与新人免费额度发放。
Q:API Key 在哪创建?
A:百炼控制台的 API Key 页面。右上角要先选对地域,创建时可以选归属账号、业务空间和权限范围。
Q:一个 Key 能调所有模型吗?
A:可以,Key 本身不绑定模型,调用时用 model 参数指定。但创建时选了"自定义"权限并限定了模型范围,就只能调范围内的。
Q:为什么我这边价格和别人说的不一样?
A:地域不同价格不同,国际站和国内站是两套定价;阶梯计费下单价还取决于单次请求的输入长度,同样的总 Token 量,拆成多次小请求和一次长请求账单可能差很多。
Q:提示额度没用完却调不通?
A:先查账号是否欠费,欠费时即使还有免费额度也调不通。其次是用完即停开关开着,或者地域选错了。
Q:国内站和国际站能用同一个 Key 吗?
A:不能。每个地域的接入域名、API Key 和模型列表互相独立,需要分别创建。
Q:数据安全方面官方怎么说的?
A:官方文档有单独的"合规资质与隐私说明"页面,列出资质与数据处理口径。企业用户可选 Token Plan 团队版,官方承诺不使用你的数据训练模型。
百炼的模型价格、活动优惠和限流额度都会随官方调整,调用前在控制台的免费额度页和定价页看一眼当期标准即可。想持续跟进千问系列模型的上新与价格变动,可以关注本站的 AI 工具栏目,有新版本我们会同步。千问API开放平台官网就是阿里云百炼这一个体系,API Key、文档、额度与账单都在同一个阿里云账号下,认准百炼控制台和 model-studio 文档路径就不会走岔。