通义API文档实战手册：在阿里云百炼上跑通第一次调用的全部细节
这份页面写给正准备把通义千问系列接进自己系统的开发者。文档主站在 help.aliyun.com 的「大模型服务平台百炼（Model Studio）」板块，模型迭代很快，本页聚焦长期稳定的结构性知识：文档怎么查、模型怎么挑、Key 怎么配、报错怎么排、成本怎么估——具体数字一律标注官方出处，变动项以官网为准。
一句话定位：百炼是阿里云的大模型服务平台，聚合 Qwen 全系与多家第三方模型，提供文本、视觉、语音、图像视频生成等 API；「通义API文档」即其官方帮助中心，涵盖从获取 Key、选择 Base URL 到限流计费的全部接口说明[7]。
文档地图：七个最该收藏的页面
- 地域及接入域名：每个地域有独立域名、API Key 和模型列表，不能跨地域混用；北京地域走 dashscope.aliyuncs.com，国际站新加坡走 dashscope-intl.aliyuncs.com[1]。
- 选择模型：各地域可用模型与上下文长度的权威清单，版本更新以这里为准[2]。
- 限流：各模型的 RPM（每分钟请求数）与 TPM（每分钟 Token 数）配额表[3]。
- 获取与配置 API Key：控制台创建密钥并写入环境变量的标准姿势[4]。
- 新人免费额度：各模型免费额度规则与有效期说明[5]。
- 模型调用计费：各地域输入/输出单价总表[2]。
- Base URL 总览：兼容模式与原生 DashScope 两套调用地址的对照[1]。
模型选择矩阵：Qwen 系列按场景对号入座
千问家族按能力分层：旗舰档能力最全价格最高，均衡档是大多数业务的主力，轻量档扛高并发低成本任务。下表为通用选型框架（命名随版本演进，如 qwen-max / qwen-plus / qwen-flash 等具体型号与上下文长度请查模型列表页[2]）：
| 梯队 | 典型用途 | 特点 |
|---|---|---|
| 旗舰档（Max 系） | 复杂推理、智能体编排、难任务兜底 | 效果上限最高，单 token 价格也最高 |
| 均衡档（Plus 系） | 客服问答、内容生成等在线主力业务 | 效果与成本折中，多数场景首选 |
| 轻量档（Turbo/Flash 系） | 分类抽取、摘要、高并发简单任务 | 延迟低、单价低，适合海量调用 |
| 超长文本（Long 系） | 整本文档、超长对话分析 | 上下文窗口显著大于常规档位 |
| 视觉理解（VL 系） | 图片问答、票据识别、界面理解 | 图文混合输入，按多模态 token 计费 |
| 语音与生成 | ASR 转写、语音合成、图像视频生成 | 按音频时长/张数/秒数等口径单独计费[6] |
一个常被忽略的参考样本：数学专项的 qwen-math-plus 在北京地域定价为输入 4 元、输出 12 元每百万 Token，上下文 4096，免费额度各 100 万 Token、开通后 90 天内有效，且各模型免费额度不共用[6]——这组数字能帮你建立对量级的直觉。
从 Key 到首次回复：六步完整路径
- 开通服务。用阿里云账号登录百炼控制台完成产品开通，默认业务空间即可测试；生产环境建议规划独立业务空间做隔离与限流管理。
- 创建 API Key。在控制台「API-Key」页新建密钥，官方明确要求不要把凭证硬编码进代码，应使用环境变量或密钥管理服务[4]。
- 认准地域域名。确认所用模型在北京还是新加坡等地域，Key 与域名必须同地域配套[1]。
- 装 SDK 或裸调 HTTP。已有 OpenAI 代码库的项目直接切 base_url 即可迁移，这是兼容模式最大的红利。
- 发起第一次请求。最小可运行示例（Python，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")
r = client.chat.completions.create(
model="qwen-plus",
messages=[{"role":"user","content":"用一句话介绍你自己"}])
print(r.choices[0].message.content) - 回看用量。到控制台「模型用量」页核对调用次数与 Token 消耗，数据延迟约一小时，免费额度可开启「用完即停」防止意外扣费[5]。
报错与限流速查：先对号再入座
| 现象 | 根因 | 处置 |
|---|---|---|
401 InvalidApiKey: No API-key provided | 请求头没带密钥 | 检查 Authorization 头与环境变量注入[4] |
401 InvalidApiKey: Invalid API-key provided | Key 复制不完整、用错套餐专属 Key 或已过期 | 重新生成并整段粘贴，注意区分套餐专用与通用 Key |
404 model not found | 模型名拼错、大小写不符或该地域未上架 | 回模型列表核对 ID 与地域[2] |
400 Range of input length should be [1, xxx] | 输入超出上下文窗口 | 裁剪历史消息或换长上下文档位 |
429 Requests rate limit exceeded | 触发 RPM/TPM 限流 | 降频重试、加退避队列；配额见限流文档[3] |
403 AllocationQuota.FreeTierOnly | 开启了免费额度用完即停且额度耗尽 | 等待重置或关闭该开关转为付费[5] |
401 Incorrect API key provided | 把套餐专属 Key 用在了通用 dashscope 地址上 | 换回对应套餐的专属 Base URL |
订阅制补充：Token Plan 与按量计费怎么搭配
除按量计费外，百炼提供面向个人的 Token Plan 与面向开发者的 Coding Plan 类订阅。以官方常见问题页的口径为例：Token Plan 个人版会发放套餐专属 API Key（sk-sp- 开头）和专属 Base URL，只有走这套专属凭证才能抵扣套餐额度，误配通用 Key 或通用域名都会导致报错或照常扣费；团队版则按「坐席」发放每月固定 Credits 额度（标准/高级/尊享三档），额度用尽后调用被阻断而不会自动转按量计费[5]。两类订阅的 Key 相互独立不可混用，系统按 Key 自动识别套餐。
工具链适配方面，订阅套餐兼容 OpenAI 与 Anthropic 协议，凡支持自定义 Base URL 和 Key 的编码工具均可接入，官方列举了 Cursor、Claude Code、Qwen Code、Cline、Cherry Studio 等。生产治理还有两条冷知识值得记下：其一，模型用量统计按业务空间维度汇总而非账号维度，且数据延迟约一小时、仅保留三十天内明细；其二，部分能力存在地域差异——例如模型调优目前仅北京地域支持，新加坡等地域以功能对照表为准[1]。上线前把这两条核进运维手册，能省掉半夜翻工单的时间。
成本估算讨论盒：动手前先算账
一个可复用的估算公式
月成本 ≈ 日均处理字数 × 30 ÷ 100万 × (输入单价 + 输出占比 × 输出单价)。Token 折算官方给了经验值：平均 1 个汉字约对应 1.5–2 个 Token，1 个英文单词约 1.3 个[2]。
演算示例（仅为方法演示，非报价）：假设某摘要服务每天吃进 2000 万汉字的输入、产出十分之一长度的输出。汉字折中取 1.75 Token/字，则日输入约 3500 万 Token；若采用类似 qwen-math-plus 的 4 元/百万输入、12 元/百万输出价目结构，仅输入侧一天就是约 140 元量级——这解释了为什么工程上要拼命压 Prompt 长度、给历史对话做截断，以及为什么非实时任务优先走批量推理通道。
三个省钱开关：① max_tokens 限制输出长度直接锁住费用上限；② 简单任务降级到轻量档模型；③ 批量推理对非实时任务通常比实时调用更具成本优势[3]。
常见问题
- Q1：通义 API 从哪里开始看文档？
- 进入 help.aliyun.com 的「大模型服务平台百炼（Model Studio）」板块，先读快速开始与地域接入域名两篇，再按需查阅模型列表和限流[1]。
- Q2：API Key 放在哪里最安全？
- 写入服务器环境变量或密钥管理服务，官方文档明确反对硬编码进代码仓库[4]。
- Q3：已有的 OpenAI 代码能直接迁移吗？
- 可以，改 base_url 为百炼兼容模式地址并替换模型名即可，协议层面保持 OpenAI 兼容。
- Q4：遇到 429 应该怎么处理？
- 先查限流文档确认当前 RPM/TPM 配额，客户端加指数退避与请求合并，高峰期考虑申请提升配额[3]。
- Q5：新人免费额度怎么用才不浪费？
- 各模型额度互相独立且有有效期，先用小流量验证目标模型效果，并可开启「免费额度用完即停」避免超额扣费[5]。