Qwen API Key 是调用通义千问模型的凭证。它不只是一串密码：请求能不能通过鉴权、费用记到哪个账号、出问题后能不能快速定位，都取决于 Key 的类型和归属。Qwen 的 Key 还额外绑定两个东西——地域和业务空间，这也是很多“Key 明明没填错却返回 401”的根源。

本文按“理解归属—创建—配权限—存变量—排错—轮换”的顺序，讲清阿里云百炼官方与中商起航 AI 网关两条路径。

说明：Qwen、通义千问、阿里云、百炼（Model Studio）、DashScope 是阿里巴巴集团及其关联公司的商标或产品名称，本文仅作技术说明，与阿里巴巴集团无隶属、代理或授权关系。创建入口、权限规则与计费口径以阿里云百炼官方文档和控制台为准。

一、先理解 Key 的三层归属

在百炼里，一把 Key 同时属于三个维度：

  • 账号：可以是阿里云主账号，也可以是某个 RAM 用户。
  • 地域：北京、新加坡、美国弗吉尼亚、中国香港等地域各自独立。
  • 业务空间：默认业务空间或子业务空间，决定这把 Key 能调用哪些模型。

这三个维度任何一个不匹配，都会表现为鉴权失败或权限不足。尤其是地域：每个地域有独立的接入域名、API Key 和模型列表，Key 不能跨地域使用。拿北京创建的 Key 去请求新加坡地址，通常返回 401 和 invalid_api_key，但这并不代表 Key 本身失效。

二、在阿里云百炼创建 API Key

官方路径适合只使用 Qwen、希望第一时间拿到新模型和新能力的团队。基本步骤如下：

  1. 登录阿里云百炼控制台，在页面右上角选择正确的地域。
  2. 进入 API Key 页面，点击“创建 API Key”。
  3. 选择归属账号：默认是阿里云主账号，也可以指定某个 RAM 用户。
  4. 选择归属业务空间：默认空间适合快速开始；需要隔离模型或成本时选子空间。
  5. 设置权限：建议先选“全部”；需要收紧时选“自定义”，配置 IP 白名单和可访问模型范围。
  6. 创建完成后，立即复制完整 Key 和页面给出的 API Host，存入密码管理器或服务端密钥管理系统。
  7. 用一条最小请求验证鉴权、地域和模型名都正确，再写入正式配置。

有两个细节容易被忽略。第一，创建 Key 需要超级管理员或业务空间管理员权限，普通成员可能看不到创建按钮。第二，明文 Key 通常只在创建时完整展示一次，关闭弹窗后无法再次查看；如果没保存，只能重置或新建。长期 Key 不会自动过期，但“不过期”不等于“不用轮换”。

三、业务空间、RAM 与权限边界

业务空间是百炼权限模型的核心。默认业务空间下的 Key 可以调用该空间的标准模型；子业务空间下的 Key 只能调用这个空间已授权的模型。如果你部署了调优模型，必须使用模型所在业务空间的 Key，否则会出现“模型存在但无权访问”。

RAM 用户相关的规则更要注意：

  • Key 可以归属 RAM 用户，账号格式通常是 username@<AccountAlias>.onaliyun.com。
  • 在 RAM 控制台删除该用户或角色，其名下 Key 会立即失效，且不可恢复。
  • 把 RAM 用户移出业务空间，Key 会失效；重新加入后恢复生效。

自定义权限适合生产环境：用 IP 白名单限制来源，用模型范围限制可调用的模型。IP 白名单支持 IPv4 和 IPv6，但 IPv6 目前只有北京地域支持，美国地域仅支持 IPv4；具体条目上限以控制台为准。套餐类 Key（例如 sk-sp- 开头的 Key）与通用 API Key 是两套体系，不要拿套餐 Key 去配通用 Base URL。

四、把 Key 放进环境变量

最危险的做法是把 Key 写进源码、前端 bundle、Notebook 输出或聊天记录。百炼约定的环境变量名是 DASHSCOPE_API_KEY，代码只引用变量名：

# 本地 .env 文件，记得加入 .gitignore
DASHSCOPE_API_KEY=your_key_here

# 当前终端临时生效
export DASHSCOPE_API_KEY="your_key_here"

# 最小验证：确认 Key、地域和模型名匹配
curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.8-max","messages":[{"role":"user","content":"ping"}]}'

生产环境至少做到：.env 不提交到 Git；使用云厂商 Secret Manager、KMS 或容器 Secret；CI/CD 使用独立变量；日志对 Authorization 头脱敏；前端永远不持有服务端 Key。需要提醒的是，示例中的模型名会随版本更新，实际名称以控制台模型列表和模型价格页为准。

五、官方 Key 与网关 Key 怎么选

如果团队只用 Qwen，官方 Key 最直接。如果同时使用 Qwen、DeepSeek、GLM、Kimi 等多个模型，或者希望统一额度、账单和发票，可以考虑在中商起航 AI 网关创建 Key。两者不是替代关系，而是两种管理方式。

维度 阿里云百炼官方 Key 中商起航 AI 网关 Key
创建入口 百炼控制台 网关控制台
适用范围 百炼地域内的 Qwen 及第三方模型 网关已开通的多家模型
计费账户 阿里云账户 网关账户
Base URL dashscope.aliyuncs.com 等百炼地址 https://ai.zhongshangqihang.com/v1
适合场景 只用 Qwen、要最新模型 多模型统一接入与账单

两类 Key 的鉴权体系不同，不能混用：官方 Key 配官方 Base URL，网关 Key 配网关 Base URL。混用最常见的表现就是 401，其次是请求打到了错误的地域或服务。

六、401 排查：先看地域，再看请求头

遇到 401，不要急着重装 SDK，按下面的顺序排查：

  1. 请求头是否为 Authorization: Bearer <key>，Bearer 后是否只有一个空格。
  2. Key 是否复制完整，有没有带入换行、引号或前后空格。
  3. Key 的创建地域与 Base URL 的地域是否一致。
  4. 业务空间是否匹配；业务空间专属域名只接受该空间自己的 Key。
  5. Key 是否被禁用、删除或重置；创建者 RAM 用户是否已被移出空间或删除。
  6. 是否把 sk-sp- 开头的套餐 Key 用在了通用接口上。
  7. 账号是否欠费。欠费通常返回 400 和 Arrearage，不是 401，但同样会表现为“调不通”。

如果以上都正常，记录响应里的 Request ID，到控制台的调用日志或模型监控里查。Request ID 是提交工单时最有用的信息，比“报错了”三个字有效得多。

七、轮换、吊销与审计

一把 Key 走天下，短期省事，长期难排查。建议至少按环境和服务拆分：测试、生产、CI 各用一把；每个后端服务一把；Key 名称带上环境和服务名，例如 prod-customer-service。再配合额度上限和用量告警，异常调用能在烧掉大量额度前被发现。

轮换时不要直接删除旧 Key。正确顺序是：创建新 Key → 灰度切换少量流量 → 确认模型权限、额度和账单正常 → 吊销旧 Key。这样新配置出问题时还能快速回退。团队成员离职、外包交接、Key 曾出现在日志或公开仓库时，应立即吊销并重建，同时检查账单和调用记录是否有异常。

八、常见问题（FAQ）

1. Qwen API Key 在哪里创建？

登录阿里云百炼控制台，选择地域后进入 API Key 页面创建。若使用中商起航 AI 网关，则在网关控制台创建，两套 Key 不通用。

2. 为什么 Key 有效却返回 401？

最常见的原因是地域不匹配，其次是 Key 复制不完整、请求头格式错误、业务空间不匹配，或创建者 RAM 用户已被删除。先核对 Key 与 Base URL 是否属于同一地域，再检查请求头。

3. 一个 Key 可以给多个项目共用吗？

技术上可以，但不建议。共用 Key 无法区分调用来源，一处泄露会影响全部业务，账单也难以分摊。至少按环境和核心服务拆分。

4. Key 泄露了怎么办？

立即在控制台禁用或删除该 Key，创建新 Key 并更新服务端配置；检查账单和调用日志，确认是否有异常用量；必要时联系平台支持说明情况。不要只改代码而不吊销旧 Key。

5. 官方 Key 和网关 Key 能混用吗？

不能。两者的鉴权体系、Base URL 和计费账户都不同。混用通常返回 401，也可能把请求发到错误的服务地址。

相关阅读