开始使用
API Key 与权限
API Key 同时是认证凭证、分组入口和成本边界。把每把 Key 绑定到明确的应用与环境，才能可靠限制权限和定位用量。
认证方式
| 协议或工具 | 请求头 | 说明 |
|---|---|---|
| OpenAI 兼容接口 | Authorization: Bearer YOUR_API_KEY | Responses、Chat Completions、Models 与 Images |
| Anthropic Messages | x-api-key: YOUR_API_KEY | 直接 HTTP 与使用 api_key 的 Anthropic SDK |
| Claude Code | Authorization: Bearer | ANTHROPIC_AUTH_TOKEN 由 Claude Code 转成 Bearer 凭证 |
权限如何生效
一次调用需要同时通过多层校验。模型在广场中可见，不等于当前 Key 一定有权使用。
| 维度 | 影响 | 检查位置 |
|---|---|---|
| Key 状态与有效期 | 禁用、撤销或到期后不能继续调用 | 控制台 API Key 管理 |
| 所属分组 | 决定可用模型、资金池、计费和路由规则 | 创建或编辑 Key 时选择的分组 |
| 账户与 Key 额度 | 任一层可用额度不足都可能拒绝请求 | 余额、订阅和 Key 额度 |
| 速率与并发 | 限制单位时间请求数、Token 或同时处理的请求 | 控制台和返回错误信息 |
| IP 规则 | 部署出口不符合允许或拒绝规则时无法调用 | Key 的访问来源配置 |
具体可设置字段以当前控制台为准。不要通过重复创建同分组 Key 来绕过模型权限或账户级限制。
隔离与存储
- 按应用隔离：不同服务使用不同 Key，便于撤销、限额和成本归属。
- 按环境隔离：生产、预发布、本地开发和 CI 分别使用独立 Key。
- 通过 Secret 注入：使用部署平台 Secret、容器密钥或操作系统凭据，不写入源代码。
- 日志脱敏：只记录 Key 的内部标识或末尾少量字符，不记录完整值。
- 最小权限：选择满足当前模型与协议的分组，不为未知的未来需求扩大范围。
轮换与泄露处置
- 创建新 Key，并使用最小请求验证模型、分组和调用记录。
- 逐个更新调用端，观察旧 Key 是否仍有请求。
- 确认迁移完成后撤销旧 Key，而不是只修改显示名称。
- 如果 Key 已泄露，立即撤销并检查异常用量；不要等待正常轮换窗口。
轮换期间不要把两把完整 Key 同时写进日志或工单。需要联系支持时，只提供控制台记录标识和响应中的请求 ID。
常见拒绝原因
- 401：缺少、格式错误、无效或已撤销的 Key。
- 403：Key 有效，但分组、账户、订阅、模型或来源规则不允许本次调用。
- 429：可能是速率、并发、Token、余额或额度限制；必须读取具体错误代码和信息再决定是否重试。
稳定的错误结构和重试判定见错误与重试。