很多人第一次接百炼，卡的不是模型选哪个，而是 Key 在哪、主账号和子账号的 Key 有什么区别、环境变量写完为什么还报鉴权失败。这篇按「建 Key → 存 Key → 用 Key → 报错排查」四步走一遍，顺带说清哪些操作只能主账号做、哪些坑一旦踩了就得重新建 Key。
很多人第一次接百炼，卡住的不是模型选哪个，而是 Key 在哪建、主账号和子账号的 Key 差在哪、环境变量明明写完了为什么还报鉴权失败。这篇按「建 Key → 存 Key → 用 Key → 报错排查」四步走一遍，顺带说清哪些操作只能主账号做、哪些坑一旦踩了就得重新建 Key。
先给一个心理准备：百炼的 API Key 不是「一把钥匙开所有门」。它跟你的账号体系、权限策略、业务空间绑在一起，所以同一个模型，别人能调通你调不通，很可能是 Key 本身没问题，而是权限或区域对不上。下面每一节都给我一个判断标准，照着核对就行。
Key 到底在哪建：主账号、子账号与业务空间的关系
控制台里 API Key 的入口一般挂在「模型服务 / 密钥管理」这一类目录下，但不同账号体系看到的位置不一样。找不到入口时，先确认自己登的是主账号还是被授权的 RAM 子账号——子账号要看被授了哪些权限，没权限的话连菜单都可能是灰的。
- 主账号 Key
- 权限最大，能访问账号下大部分资源，适合做兜底或运维用途，不建议直接塞进业务代码
- RAM 子账号 Key
- 继承子账号被授予的权限策略，权限没配够的表现是「Key 有效，但调不通某个模型」
- 业务空间
- 决定这把 Key 能访问哪些模型、用量算在谁头上；多人共用一个账号时，先约定谁的 Key 记谁的账
判断标准很简单：如果一把 Key 昨天能调、今天同样的代码报无权访问，先别怀疑 Key 坏了，去查权限策略或业务空间授权是不是被改过。什么情况下不适用？如果你用的是主账号 Key 且账号下没有做权限隔离，那基本不会遇到这类问题，报错就要往别处找。
Key 拿到手之后怎么存：别写死在代码里
最常见的翻车方式是：Key 贴进了聊天窗口、提交进了 Git、或者写死在代码常量里。这种情况下不要指望改权限能救回来，直接把那把 Key 删掉重建，成本最低。
- 写进环境变量或本地 .env 文件，代码里只读变量名，不出现明文
- 测试 Key 和线上 Key 分开，本地调试一把、服务器部署一把，出问题能单独吊销
- 团队协作用密钥管理服务或部署平台的 Secret，而不是共享文档或群消息
- 人员变动或疑似外泄时，按「先吊销、再新建、后替换」的顺序操作
# .env 里只放变量名对应的值，代码里读 os.environ
export DASHSCOPE_API_KEY="你的Key"
# 检查是否有多余空格或换行
printf '%s' "$DASHSCOPE_API_KEY" | wc -c第一次调用跑通：三个必查项
第一次调用失败，八成不是模型的问题，而是地址、Key、参数三者没对齐。建议把「鉴权通不通」和「参数对不对」分开测，别一上来就塞长 prompt 或多模态输入，那样报错信息会混在一起，很难定位。
- 核对地址与 Key 是否同区确认调用地址的域名和 Key 所属区域一致，跨区调用最常见的结果就是鉴权失败，而且报错信息通常不会直说是区域问题。
- 用最小请求验证连通性发一条最短的文本请求，只看返回是不是 200 或成功结构；这一步只验证鉴权，不验证业务逻辑。
- 用官方 SDK 跑通再换自写请求签名和请求头格式的差异，经常是「curl 能通、代码不能通」的原因，先用 SDK 排除格式问题。
如果你已经用 SDK 跑通了，但换成自写 HTTP 请求就报错，优先怀疑请求头里的鉴权字段拼写、Content-Type 和编码。这类问题跟 Key 本身无关，不用去重建 Key。
报错按这个顺序排查，别乱试
报错信息往往只给一个笼统的提示，直接照字面猜很容易走弯路。下面这张表按「先看哪类、再看什么」的顺序整理，遇到报错先归类，再按对应动作查。
| 报错类型 | 先查什么 | 常见原因 |
|---|---|---|
| 鉴权类（密钥无效、未授权） | Key 是否被删/禁用、是否有多余空格换行、地址区域是否匹配 | 复制时带了换行、用了别的区域的地址 |
| 权限类（无权访问某模型） | 子账号权限策略、业务空间授权范围 | Key 有效但策略没覆盖这个模型 |
| 额度与限流类 | 账户余额是否欠费、模型的并发或速率上限 | 持续出现就是真到顶了，偶尔出现可重试 |
| 参数类（模型名不存在、输入超长） | 模型标识拼写、上下文上限 | 拿别的平台的模型名直接套用 |
归类之后按顺序处理：先鉴权、再权限、再额度、最后参数。这个顺序的原因是，前面几类不解决，后面几类的报错信息会被掩盖，越试越乱。什么情况下不适用？如果你只改了 prompt 内容就报错，那大概率是参数类问题，直接从最后一类查更快。
日常管理：轮换、吊销与团队协作
Key 建出来不是一劳永逸的。给每把 Key 起一个能读懂的用途名或环境名，半年后回到列表里还能一眼认出哪把已经废弃，这一步花不了几分钟，但能省掉后面排查「这把是谁的」的时间。
- 按用途或环境命名 Key，别全叫「默认」或「测试」
- 定期对一遍 Key 清单和实际在跑的调用方，长期没用的直接删
- 人员离职或仓库外泄时，吊销后确认调用方有没有兜底 Key，避免线上直接断掉
- 轮换节奏跟着人员变动走，而不是固定周期一到就换
判断一把 Key 该不该留，标准是「还能不能对应到一个明确的调用方」。对不上号的 Key 就是泄漏面，删掉比留着安全。想把常见错误码的官方解释和实测表现对上，可以到站内资料库页面对照着看，那里会把每类报错的典型触发条件列出来。
下一步想核对当前各家的接入方式和常见报错处理，去站内资料库看当时的整理，再决定用哪套 Key 管理方案。→常见问题
主账号的 Key 能直接给子账号用吗？
技术上通常能用，但不建议。子账号各自建 Key，权限和用量都能单独控制，出问题只吊销一把；共用主账号 Key 的话，一旦泄漏等于整个账号暴露，而且用量账单上分不清是谁花的。
Key 没变，昨天能调今天报鉴权失败，怎么回事？
先排除三种情况：Key 被禁用或删除（看控制台状态）、账户欠费被限制、以及调用地址被换到了另一个区域。都不像的话，把报错原文和请求地址一起对照站内接口页面确认口径，别只看错误码数字。
把 Key 写在前端代码里行不行？
不行。前端代码对用户完全可见，等于公开。正确做法是前端调你自己的后端，由后端持有 Key 再转发到百炼；临时演示可以用短时效或限额的 Key，演示完立刻吊销。
