API 密钥权限与额度限制
一枚 API 密钥能否成功调用模型，不只取决于密钥值是否正确。启用状态、过期时间、独立额度、账户余额、所属分组和模型范围都会参与判断。
调用需要满足的条件
API 请求通常需要同时满足以下条件：
- API 密钥存在且填写完整。
- API 密钥处于已启用状态。
- API 密钥尚未过期。
- API 密钥没有达到自身额度上限。
- 账户余额充足。
- API 密钥所属分组支持目标模型。
- 目标模型没有被该密钥的模型范围排除。
任何一项不满足，都可能导致调用失败。
启用状态
API 密钥列表中的「状态」会显示密钥当前是否已启用。
- 已启用：允许继续尝试调用 API。
- 已停用：使用该密钥的所有请求都会被拒绝。
停用适合临时阻断访问，不会立即删除密钥配置。需要暂停项目、排查异常消耗或怀疑密钥泄露时，应先停用密钥。
过期时间
创建密钥时可以选择「永不过期」，也可以设置具体日期和时间，或使用「1 小时」「1 天」「1 个月」等快捷选项。
| 使用场景 | 建议有效期 |
|---|---|
| 临时测试 | 1 小时或 1 天 |
| 短期项目 | 按项目结束时间设置 |
| 长期个人工具 | 较长有效期，并定期检查 |
| 自动化服务 | 明确轮换周期，避免无计划地永久使用 |
密钥到期后，即使账户余额和密钥额度仍然充足，也不能继续调用模型。
只有确认需要长期运行的场景才建议使用「永不过期」。临时密钥设置过期时间，可以减少遗忘清理带来的风险。
独立额度
API 密钥可以设置自己的消耗上限，用于控制某个工具、项目或成员最多可以使用多少额度。
无限额度
开启「无限额度」后，该密钥没有单独的额度上限，但仍然受账户余额、有效期、分组和平台规则限制。
有限额度
关闭「无限额度」后，可以设置该密钥的独立额度。密钥达到额度上限后会停止调用，不会自动使用其他密钥的额度。
独立额度适合：
- 临时测试
- 成本上限明确的项目
- 交给不同成员或设备使用的密钥
- 希望隔离各工具用量的场景
账户余额与密钥额度
最终可用额度同时受账户和密钥限制，可以简单理解为：
可继续使用的额度 = 账户可用余额与密钥剩余额度中更小的一项
| 账户余额 | 密钥额度 | 是否可继续调用 |
|---|---|---|
| 充足 | 充足 | 可以 |
| 不足 | 充足 | 不可以，需要增加账户余额 |
| 充足 | 已耗尽 | 不可以，需要调整或更换密钥 |
| 不足 | 已耗尽 | 不可以，两项都需要处理 |
如果密钥开启无限额度，只需要判断账户余额以及其他访问条件。
分组权限
分组决定 API 密钥能够使用的模型渠道、请求路由和计费倍率。
例如，Bita API 当前可能展示 default、claude-origin 和 gpt-origin 等分组。某个模型在模型广场可见，不代表所有分组的 API 密钥都可以调用它。
修改分组前应确认：
- 目标模型在新分组中可用
- 第三方工具需要的接口格式能够使用
- 新分组倍率符合成本预期
- 现有客户端不会因为模型列表变化而失败
修改完成后，建议先调用 /v1/models 查询可用模型，再发送一条最小测试请求。
分组的完整解释参见创建 API 密钥：分组。
模型范围
API 密钥列表中的「模型」列显示该密钥的模型范围：
- 无限制：没有为密钥单独指定模型范围，但仍然只能调用所属分组中可用的模型。
- 指定模型：只能调用密钥范围和分组范围共同允许的模型。
如果当前创建或编辑页面没有提供模型范围设置，则以 API 密钥分组和模型广场的可用模型为准。
「无限制」只表示 API 密钥本身没有额外限制模型。分组、渠道状态和平台配置仍可能限制实际可用模型。
推荐配置
| 场景 | 状态 | 有效期 | 独立额度 | 分组 |
|---|---|---|---|---|
| 首次接入测试 | 已启用 | 1 天 | 设置较小额度 | 目标模型支持的分组 |
| 个人聊天客户端 | 已启用 | 较长期限 | 按个人预算设置 | 客户端所需分组 |
| 编程工具 | 已启用 | 定期轮换 | 按项目预算设置 | 接入文档指定分组 |
| 临时共享环境 | 已启用 | 1 小时或 1 天 | 必须限制 | 只选择必要分组 |
| 暂停使用的项目 | 已停用 | 保持原设置 | 保持原设置 | 保持原设置 |
修改限制后的影响
调整 API 密钥设置通常会影响所有正在使用该密钥的客户端：
- 停用密钥后，请求会立即失败。
- 修改分组后，可用模型和计费倍率可能发生变化。
- 缩短有效期后，密钥可能提前失效。
- 降低额度后，密钥可能立即达到上限。
- 收紧模型范围后，原有模型请求可能不再被允许。
生产项目修改前，建议先创建新密钥完成测试，再切换客户端配置。
常见失败原因
| 表现 | 可能原因 |
|---|---|
| 提示密钥无效 | 密钥填写不完整、已删除或已停用 |
| 提示额度不足 | 账户余额不足或密钥独立额度耗尽 |
| 提示模型不存在或不可用 | 分组不支持目标模型，或模型 ID 不正确 |
| 之前可用但突然失败 | 密钥过期、状态被修改或模型渠道变化 |
| 修改分组后调用失败 | 新分组不支持原模型或接口格式 |
排查时可以同时打开 API 密钥列表、模型广场和使用日志，依次核对状态、有效期、额度、分组和模型 ID。
下一步
需要查看每枚密钥和每个模型的实际调用情况时，继续阅读用量与调用日志。