API Key 与分组
每个客户端使用不同 Key，能更快定位异常消耗，也能单独撤销权限。
创建步骤
- 登录 牛API 控制台。
- 打开 API Key 管理入口。入口名称和位置待补牛API实测截图确认。
- 使用能识别用途的名称，例如
codex-personal或cherry-laptop。 - 若控制台支持，设置合理的额度、有效期和模型权限。
- 创建后立即安全保存；页面关闭后可能无法再次查看完整 Key，此行为待实测确认。
待补牛API实测截图：Key 名称、额度、有效期和权限设置
只展示脱敏示例，完整 Key 必须不可见。
权限与限制
创建 Key 时检查控制台是否提供以下选项。没有看到对应选项时不要自行假设已经启用。
| 维度 | 建议 | 当前状态 |
|---|---|---|
| 用途名称 | 标记客户端、设备或项目 | 可直接采用 |
| 额度 | 从小额度开始，按实际用量调整 | 控制台行为待实测 |
| 有效期 | 临时测试使用较短有效期 | 控制台行为待实测 |
| 模型权限 | 只授权需要的模型 | 控制台行为待实测 |
| IP 白名单 | 固定服务器可考虑限制来源 | 是否提供待确认 |
| 请求频率 | 与客户端并发和任务类型匹配 | 是否提供待确认 |
分组与可用范围（待验证）
同类平台普遍使用“分组”机制：创建 Key 时选择的分组决定它可以调用哪些模型、走哪类渠道、按什么倍率计费以及限额上限。这类平台的典型表现是：
- 模型不可用时要先检查 Key 所属分组是否包含该模型；
- 出现“没有可用渠道”类报错时，通常意味着 Key 没绑定正确分组，或该分组当前没有可用渠道。
牛API是否存在公开的分组、套餐或权限组机制尚待确认；在确认前，只按控制台实际显示的模型权限、额度和有效期操作，不要套用其他平台的分组规则。
遇到“没有可用渠道”类报错怎么办
如果请求返回类似“没有可用渠道”或提示某个分组/范围不可用，先检查 Key 的模型权限与控制台资源状态，再用最小请求复现。该错误形态在牛API侧尚未实测确认，无法消除时按提交问题清单整理信息联系支持。
如何拆分 Key
- 按客户端拆分：Cherry Studio、Codex、Claude Code 使用不同 Key；
- 按设备拆分：个人电脑、服务器和自动化任务分别管理；
- 按环境拆分：开发、测试和生产不要共享同一个 Key；
- 按成员拆分：团队成员不要共用一个长期 Key；
- 按项目拆分：出现异常消耗时可以快速定位和撤销。
多人共享同一 Key 会让用量归属、权限回收和泄露排查变得困难。
安全基线
- 不公开分享，不放在截图、工单正文或群聊中；必须展示时只露出前后几位；
- 不提交 GitHub，不写进项目源码或前端代码；
- 使用环境变量或操作系统密钥管理器；
- 不同客户端、设备和自动化任务使用不同 Key；
- 日志只保留开头和末尾少量字符；
- 发现异常后立即删除并重建，而不是仅修改本地配置。
示例值
本文档中的所有示例统一使用：
text
YOUR_API_KEY1
它只是占位符，不能直接发送请求。
异常处理
401：检查 Key 是否完整、有效，客户端是否继承了正确环境变量；402：检查余额、Key 额度和资源状态；429：停止并行请求，降低并发并等待后重试；- 只有一个 Key 失败：与另一个专用 Key 对比，检查有效期、权限和额度；
- 出现异常消耗：立即停用 Key，保存发生时间与请求 ID，再核对用量记录。