API Key 价格保护

为 API Key 设置“最高允许倍率”后，如果请求实际生效的倍率高于这个上限，ooioo 会在发送请求和扣费前直接拒绝。

这适合需要长期运行的 Coding Agent、自动化任务和团队项目：即使服务价格后来调整，Key 也不会在你不知情时按更高倍率继续消费。

开启价格保护

进入 控制台 → API 密钥，创建新 Key 或编辑已有 Key：

1. 打开 最高允许倍率；
2. 在 倍率上限 中填写你能接受的最高倍率；
3. 保存 Key。

创建新 Key 时，系统会根据所选分组的当前倍率带出默认上限。你可以保留默认值，也可以按预算需要调整。

建议

一个项目使用一个 Key，并保留系统带出的默认上限。这样调价后的影响范围更清楚，也更容易单独停用或调整。

请求会怎样处理

实际生效倍率	处理结果
低于上限	正常请求和扣费
等于上限	正常请求和扣费
高于上限	返回 402 price_limit_exceeded，请求不发送、不扣费

选择自动分组时，系统只会使用不高于上限的可用分组。如果没有符合条件的分组，请求同样会在发送和扣费前被拒绝。

进行中的流式请求按接入时的倍率完成；之后的调价只影响后续请求。

查看保护状态

API Key 列表会显示以下状态：

• 已保护：当前倍率没有超过上限；
• 已被价格上限阻止：当前倍率已经超过上限，该 Key 的请求会被拒绝；
• 未保护：该 Key 没有设置倍率上限。

历史 Key 默认保持“未保护”，不会因为功能上线自动改变行为。需要保护时，请编辑对应 Key 并开启上限。

上限设置得更低会怎样

你可以把上限设置为低于当前倍率，控制台会提示该 Key 将被阻止。保存后，新请求会立即返回价格保护错误。

这不会删除 Key，也不会产生扣费。价格回到上限以内，或你主动调高上限后，Key 才会恢复请求。

识别价格保护错误

价格保护触发时返回 HTTP 402，并带有明确的错误类型：

{
  "error": {
    "type": "price_limit_exceeded",
    "code": "price_limit_exceeded",
    "param": "group",
    "message": "当前生效倍率高于该 API Key 允许的最高倍率；请求未发送，也未扣费。"
  },
  "price_guard": {
    "current_group_ratio": 0.15,
    "max_group_ratio": 0.12
  }
}

客户端遇到这个错误时不要自动重试。请到 控制台 → API 密钥 查看当前倍率和最高允许倍率，再决定是否调整上限。

与其他限制的区别

价格保护只限制 API Key 可以使用的最高分组倍率：

• 额度控制这个 Key 最多可以消费多少；
• 过期时间控制这个 Key 可以使用到什么时候；
• 价格保护控制价格上涨到什么程度后必须停止请求。

它不是单次请求金额上限，也不会代替账户余额、订阅额度或模型权限设置。