通义千问api避坑：第一次上手最容易卡在这三处

搜「通义千问api避坑」的人，多半不是没看过文档，而是照着示例调通了，账单或报错却跟预期对不上。这篇不背价格、不列跑分，只讲三件最容易卡住的事：你以为的免费额度和实际扣费是不是一个口径、模型名和计费入口有没有对上、被限速或报错时该先查哪一格。每一处都给判断标准和排查顺序，看完能自己动手核对。

搜这四个字的人，通常不是没看文档。示例代码跑通了，回头一查账单或者一看报错，跟预期对不上。问题多半不在代码写错，而在接进去之前脑子里那几个默认假设，跟平台实际的口径不是一回事。

这篇不背价格、不列跑分，只把最容易卡住的三处拆开：你以为的免费额度和实际扣费是不是一个口径、代码里的模型名和计费入口有没有对上、被限速或报错时该先查哪一格。每处都给判断标准和能动手的排查顺序。

免费额度这关：先分清是送额度还是送时长

百炼平台上「免费额度」和「限时免费」是两套东西。前者是实打实发到账上的用量，用一次扣一次；后者是某段时间内不计费，过期就恢复原价，两者的到期逻辑完全不同。别拿别人半年前的截图当依据，去 /official-api/providers/alibaba 看当前页面怎么写的，页面措辞就是准的。

判断标准很简单：控制台的扣费明细里如果能看到「赠送」这一行，说明你用的是额度；如果只看到抵扣记录、没有赠送条目，那大概率是限时活动。分不清这两种，就别抱着「反正免费」的心态去压测，很容易第二天收到一份没预期的账单。

• 新账号先跑几十次最小请求，别急着上业务流量
• 第二天回控制台把扣费明细拉出来，逐条看扣的是赠送还是余额
• 把明细截图存一份，以后对账有基准
• 如果是团队共用账号，先确认自己看的是个人视角还是项目级账单

模型名和计费入口对不上，账就永远算不准

同一个系列下面往往挂着好几个规格，名字只差一小截，单价和上下文长度可能完全不是一档。最常见的误判是拿免费档的模型名去估正式环境的成本，算出来只有实际的零头，上线才发现预算差一大截。

做法很笨但有效：把代码里的模型标识原样复制出来，去 /models 和 /official-api/providers/alibaba 逐个对照，别凭记忆填。换模型之前先在 /tools/token-price-calculator 把输入、输出单价代进去算一遍，比拍脑袋靠谱。

长上下文和图片输入这两类，通常跟纯文本不是一个计价口径。纯文本的估算公式直接套上去，结果只会偏低，不会有偏高的意外。判断方法就是翻计费说明，看有没有单独列出这两项。

被限速、报错、额度不足：排查顺序别搞反

报错信息混在一起猜，是最耗时间的做法。先看返回体里的错误码类型，把它归到额度类、限流类还是参数类，再决定动哪里。三类问题对应的位置完全不同，改错地方只会越改越乱。

1. 先分类错误码拿到返回体，确认是额度不足、触发限流，还是参数不合法，别跳过这步直接改配置
2. 核对密钥归属首次接入就报权限或额度问题，优先查 key 属于哪个账号、哪个项目空间，SDK 装对了但 key 填进了另一个环境的配置文件，是新手最常见的一种
3. 量延迟基线压测前去 /tools/speed-test 跑一遍延迟，心里有个底再谈并发
4. 小并发逐步加从低并发往上加，观察错误率变化，别一上来开满然后怪接口不稳

还有一类容易被忽略：团队里几个人共用一个账号，A 看到额度还有，B 那边已经报不足，因为项目空间不同。遇到这种对不上的情况，先找管理员看项目级账单，别在个人页面上反复刷新。

这套判断什么时候不适用

上面按纯文本推的账，放到长文档批量处理或者带图输入的业务里会偏，得回计费说明按实际输入类型重算一遍。这不是方法错了，是假设不成立。

走第三方聚合平台而不是官方入口的，免费额度和计费口径以那家平台为准，本文的排查顺序只适用于官方控制台。团队共用账号时，个人视角的额度页可能看不到全部扣费，也得换项目级视角看。

先把口径对齐，再谈优化；口径没对齐，省下来的都是算错的。