API Key 与路由分组
适用角色：组织（顶层用户）、子用户、开发者 更新日期：2026-07-02
API Key 是调用模型的凭证。新版控制台里，每把 Key 绑定一个「路由分组」：用裸模型名调用时，请求就走这把 Key 绑定的分组。本文介绍如何创建、配置、管理 Key，以及调用时如何路由。
调用名（裸名 vs 指纹）的写法与双路由规则详见 开发者指南 · 调用指南与双路由。
一、Key 的路由模型：每把 Key 绑定一个分组
建 / 编 Key 时，为这把 Key 选择一个路由分组：
- 路由分组（单选）：这把 Key 用裸模型名（不带指纹）调用时，请求路由到该分组。可选项为你当前可用的分组（子用户只会看到组织授权给它的分组）。
- 不绑定的后果：若不选路由分组，这把 Key 无法用裸模型名调用（会被拒绝）；此时只能用带指纹的调用名点名到具体分组。
- 一把 Key 绑定一个分组，是老版「每 Key 对应一个分组」行为的延续，老客户端零改造。
什么是分组？分组相当于一种服务套餐标签——同一个模型可以通过不同分组提供，不同分组可能对应不同的渠道、价格和折扣。分组由平台统一维护，你可以在「调用指南」页看到当前可用的分组。详见 平台简介 · 多渠道服务体系与分组。
进阶：调度分组白名单（可选，仅组织可配） 除路由分组外，组织（顶层用户）还可为 Key 配置一个「调度分组白名单」，用于约束带指纹 / 点名调用能到达哪些分组。它与路由分组并存：裸名走绑定的路由分组；带指纹 / 点名调用则额外受白名单约束。此为进阶项，子用户不可配置，多数场景无需设置。
二、谁能创建 Key
| 角色 | 能否创建 Key | 说明 |
|---|---|---|
| 组织（顶层用户） | ✅ | 可建 Key，并配置路由分组、进阶白名单 |
| 子用户 | ✅ | 可自助创建 Key，路由分组只能在组织授权范围内选；不可配进阶白名单 |
- 组织与子用户都能在「API 密钥」页（
/keys）自助建 Key。 - 子用户建 Key 时，路由分组下拉只列出组织授权给它的分组；进阶白名单字段对子用户不显示。
- 子用户名下全部 Key 共享同一个额度上限（即额度上限的累计消费计数），真实扣费始终扣所属组织（父账号）的余额，详见 子用户管理。
- 子用户在 Key 页顶部另有「子用户额度卡片」，只读展示其额度情况。
三、创建 / 编辑 Key
- 进入「API 密钥」页（
/keys） - 点击「创建 Key」入口
- 配置以下项：
| 配置项 | 说明 |
|---|---|
| 名称 / 备注 | 便于识别 Key 的用途 |
| 路由分组 | 单选。裸模型名调用时路由到该分组；不选则该 Key 无法用裸名调用。选项按你的授权范围收窄 |
| 调度分组白名单 | 进阶、可选，仅组织可见。约束带指纹 / 点名调用可达的分组 |
| IP 黑 / 白名单 | 限制可使用该 Key 的来源 IP（可选） |
- 提交后，请妥善保存生成的 Key
四、Key 列表展示
「API 密钥」页列表展示每把 Key 的关键信息：
| 列 | 说明 |
|---|---|
| 脱敏 Key | 仅显示部分字符，保护完整密钥 |
| 路由分组 | 展示该 Key 绑定的分组名称及折扣信息；未绑定则提示需选择分组。支持在列表内联切换绑定分组 |
| IP 黑 / 白名单 | 以盾牌图标标识是否配置了 IP 限制 |
| 额度 / 限流 | 展示该 Key 的额度与限流窗口（如有） |
| 状态 | Key 当前是否可用 |
列表「路由分组」列可直接内联切换绑定分组（切换范围同样受授权约束），无需进入编辑弹窗。
五、调用时如何路由
调用时 model 名称有两种写法，路由行为不同：
| 调用的 model | 路由行为 |
|---|---|
带指纹（如 5MHXZWKA/gpt-4o） | 解析指纹 → 固定路由到该指纹对应的分组 |
裸模型名（如 gpt-4o） | 路由到这把 Key 绑定的路由分组（V1 行为） |
- 裸模型名走 Key 绑定的分组；若该 Key 未绑定任何分组，裸名调用会被拒绝（
403）——此时改用带指纹调用名，或先为 Key 绑定路由分组。 - 调用名统一在「调用指南」页获取并复制，详见 调用指南与双路由
- 选定渠道不可用时直接报错，不自动切换渠道、不降级、不兜底
六、老 Key 兼容
新版上线后，老 Key 继续有效，调用不中断：
- 老 Key 仍按其原绑定分组工作，行为与老版一致——这与新版「每 Key 绑定单一分组」的模型完全一致
- 老客户端、老脚本零改造，继续用裸模型名即可
- 如需点名到其他分组，可在「调用指南」复制带指纹的调用名
迁移相关说明见 迁移与过渡说明。
七、常见问题
Q：建 Key 时怎么选分组？ A：在「路由分组」里选一个分组，这把 Key 用裸模型名调用时就走它。不选的话，这把 Key 只能用带指纹的调用名。
Q：一把 Key 能同时走多个分组吗？ A：裸模型名固定走绑定的那一个路由分组。若要临时点名到别的分组，用带指纹的调用名（受组织配置的进阶白名单约束）。
Q：子用户能自己建 Key 吗？ A：能。子用户可在「API 密钥」页自助创建 Key，路由分组只能在组织授权范围内选；子用户名下全部 Key 共享同一额度上限，扣费扣组织余额。
Q：调用时 model 该填什么？ A：去「调用指南」复制。带指纹按指纹对应分组路由，裸名走这把 Key 绑定的分组，详见 调用指南与双路由。
Q：渠道不可用会自动换一个吗？ A：不会。选定渠道不可用时直接报错，不自动切换、不降级、不兜底。
Q：怎么限制某把 Key 的来源 IP？ A：在创建 / 编辑 Key 时配置 IP 黑 / 白名单，列表中会以盾牌图标标识。
Q：Key 丢了或怀疑泄漏怎么办？ A：在「API 密钥」页找到该 Key，点击停用或删除，然后创建一把新 Key。已停用或删除的 Key 立即失效，无法恢复。
联系我们
- 电子邮箱：support_cloudrouter@clouditera.com
- QQ 社群：712273971
- 平台网址：cloudrouter.online