摘要:给 API Key 设了额度,费用仍可能超出预期。本文说明原因,并把 AI 试用的预算控制拆成三道有先后顺序的预算线。
先说结论:网关上的 Key 额度是软上限,在并发请求下不能当作硬账单上限。以 API易 的令牌文档为例,额度在请求开始时检查。多个请求同时通过检查,或者单次请求本身价格很高,最终消耗都可能超过设定额度。
可靠的做法是分三层处理:
- 应用后端在发请求前完成检查,并原子性地预留预算。
- 网关侧给试用流量单独发 Key,配上额度和模型白名单,缩小这把 Key 被滥用时的影响范围。
- 账户余额告警只负责通知,用来触发人工响应。
这三层的职责互不替代。真正的预算准入发生在应用自己的账本里。

知识地图与索引:三道预算线的先后与分工
下表同时承担知识地图和索引的作用。它列出三道预算线按什么顺序生效、各自负责什么、为什么这样安排,以及对应的正文编号。
| 顺序 | 预算线 | 负责什么 | 为什么放在这个位置 | 目标 | 正文 |
|---|---|---|---|---|---|
| 前提 | 理解软额度 | 区分请求前检查、预扣和实扣 | 不清楚扣费时序,后面三层就无从设计 | 明白超支是怎么发生的 | 1、1.1 |
| 第一道 | 应用后端预算 | 按用户和试用池做原子预留与结算 | 只有应用知道“谁在用、能用多少” | 让超支在发请求前被拦下 | 2.1、3 |
| 第二道 | 独立试用 Key | 额度、模型白名单、与正式流量隔离 | 应用出 bug 时,网关是第二层边界 | 缩小单把 Key 的暴露面 | 2.2 |
| 第三道 | 账户余额告警 | 余额低于阈值时通知 | 告警是事后信号,没有拦截能力 | 让人及时介入 | 2.3 |
| 落地 | 并发账本与上线检查 | 预留、结算、失败处理、对账、友好提示 | 把前面的原则落成可验证的流程 | 上线前能逐项验收 | 3、4 |
阅读顺序建议:先读第 1 节理解时序,再读第 2 节明确分工,第 3 节是实现部分。第 4 节适合上线前单独对照使用。
To Know:理解预算线前的必要术语
| 术语 | 简明解释 |
|---|---|
| 软上限 | 请求开始时检查额度,检查通过后不保证总消耗不越线 |
| 预扣 | 网关按估算先扣一部分额度,请求结束后按实际用量结算 |
| 原子预留 | 用单条不可分割的操作完成“检查余量并占用”,防止并发请求同时通过 |
| 在途预留 | 请求已发出、实际费用还没确认时,账本里仍处于占用状态的那部分预算 |
| remain_quota | API易 令牌的一次性总额度字段,文档口径为 500000 对应 $1 |
| 对账 | 用网关日志与自有账本逐条核对,修正估算与实际之间的偏差 |
1 API Key 额度为何可能被并发超出
API易 令牌文档对这一点写得很明确:Key 额度是软上限,在请求开始时检查。所以并发请求,或者单次高价请求,都可能让实际消耗超过设定额度。这是“开始时检查、结束时结算”这种计费结构本身的特性,和某个平台有没有 bug 没有关系。
可以用一个假设场景来理解(数字均为示意,非实测)。某试用 Key 剩余额度折合 $1,同一时刻涌入 20 个请求。每个请求在开始时看到的都是“余额为正”,于是全部放行。等它们陆续结束、按实际用量结算时,总消耗已经远超 $1。就算没有并发,一次长上下文加大输出的请求,单次费用也可能超过剩余额度。
还有两个常见误解需要说明:
- 额度不会每天自动恢复。文档说明 remain_quota 是一次性总额度,“每天重置”需要应用方自己写定时脚本实现。
- 模型白名单不等于费用上限。它只限制能调哪些模型,对同一模型的调用次数和每次的规模没有约束。

1.1 API Key 额度的三个时点:请求前检查、预估与实扣
一次调用在计费上有三个时点,各自回答的问题不同:
| 时点 | 发生在哪 | 回答的问题 | 能否作为硬上限 |
|---|---|---|---|
| 请求前检查 | 网关,请求开始时 | 这把 Key 此刻还有没有余量 | 不能,并发下会同时通过 |
| 预估与预扣 | 网关,基于估算 | 这次请求大概要占多少 | 不能,估算与实际有偏差 |
| 实际扣费 | 网关,请求结束后 | 这次请求实际用了多少 | 事后数据,无法用来准入 |
API易 关于预扣额度的说明是:网关基于估算预扣,事后按实际用量结算,这一机制不替代业务侧的原子预留。网关的预扣是为了自身计费,并不知道你的某个用户今天还剩多少试用额度。所以“这个用户能不能再发一次请求”这个问题,只能由应用后端回答。
2 AI 试用的三道预算线
三道线分别面向三类风险:业务逻辑层面的超额使用、Key 层面的滥用或泄露、账户层面的余额耗尽。OWASP API Security Top 10(2023)中的 API4「Unrestricted Resource Consumption」讲的也是同一类问题:没有对资源消耗设置限制的接口,会带来服务和成本两方面的风险。对 AI 接口来说,成本风险往往更直接。
2.1 第一道预算线:应用后端的用户与试用池预算
这是唯一能做“准入”的一层,需要管两个层级:
- 用户级预算:每个试用用户的总额度,或者日额度。日额度靠应用自己的定时任务重置,不依赖网关。
- 试用池预算:所有试用用户共享的总上限。即便单个用户都没超限,用户数激增时总成本也要有封顶。
一个请求要同时通过用户级和池级的预留才能放行,并且两者必须在同一个原子操作或同一个事务里完成。否则还会出现“用户预留成功、池子已经满了”的竞态。
这一层还要在服务端决定请求的规模:允许用哪个模型、max_tokens 上限是多少、输入长度不能超过多少。这些参数不能交给前端传入后直接透传,否则用户只要改一个参数,预估金额就失真了。
2.2 第二道预算线:独立试用 Key、额度与模型白名单
网关侧给试用流量单独发一把 Key,与正式流量完全隔离。这把 Key 的职责是限制暴露面:应用账本出了 bug,或者 Key 被泄露时,损失被限制在这把 Key 的额度之内,不会波及正式业务。
配置时要注意:
- 额度按“试用池预算 + 一定缓冲”来设。它应该比应用侧的池预算略高,作为兜底存在,不要和池预算设得一样,否则应用层的预留形同虚设。
- 模型白名单只放试用开放的模型。它能防止试用 Key 被用来调高价模型,但不限制次数和规模,所以第 2.1 节的服务端规模限制仍然必须有。
- 由于额度是软上限,这道线允许“轻微越线”。它的意义在于把越线幅度控制在可接受范围内,不能指望它做到零超支。
按项目拆分 Key、额度和日志的通用做法属于另一个话题,这里只强调一点:试用流量单独一把 Key。
2.3 第三道预算线:账户余额告警
API易 的余额告警文档明确说明,告警是通知,不会拦截请求。余额跌破阈值时,告警负责把消息推送给负责人,由人决定是充值、暂停试用入口,还是排查异常流量。
使用这一层时有两个建议:
- 告警阈值按“从发现到处理所需时间内的最大消耗”来定,不要随手设一个整数。
- 告警要关联到具体的处置动作,例如在值班手册里写明“收到告警后先关闭试用注册入口”。只有通知、没有后续动作的告警,形同虚设。
3 一个假设的并发账本:原子预留到对账
本节给出一个示意设计。表结构、价格和数字都是假设,用来说明流程,不代表任何系统的实测数据。流程共五步:
原子检查并预留 → 服务端锁定 model 与规模 → 发请求
→ 结算 / 失败处理 → 离线对账修正

3.1 预算账本的表结构与状态
示意的数据结构有两张表:budgets 记录每个用户和试用池的上限、已花费、已预留;reservations 记录每一笔预留及其状态。
| 预留状态 | 含义 | 对“可用余量”的影响 |
|---|---|---|
| reserved | 已预留,请求在途 | 占用预估金额 |
| settled | 拿到实际用量,已结算 | 转为已花费,释放差额 |
| released | 确认请求未被执行 | 全额释放 |
| unknown | 超时、断连,费用未知 | 继续占用,等待对账 |
可用余量的计算方式是 limit - spent - reserved,其中 reserved 包括 unknown 状态的预留。
3.2 原子检查并预留:防止并发同时通过
关键在于把“检查”和“占用”合并成一条条件更新语句,靠数据库保证原子性:
-- 示意:只有余量足够时才占用,返回受影响行数
UPDATE budgets
SET reserved = reserved + :estimate
WHERE owner_id IN (:user_id, :pool_id)
AND limit_amount - spent - reserved >= :estimate;
-- 受影响行数必须等于 2(用户与池都成功),否则回滚事务并拒绝请求
预估金额要取上限值:按输入 token 数乘以输入单价,再加上 max_tokens 乘以输出单价。实际用量通常低于这个数,结算时把差额退回即可。宁可多占一点,也不能少占。
3.3 服务端锁定 model 与任务规模
预留用到的估算参数,必须与真正发出的请求参数完全一致。示意代码如下:
ALLOWED_TRIAL_MODELS = {"trial-model-a"} # 示意:试用开放的模型
MAX_OUTPUT_TOKENS = 1024 # 示意:服务端强制上限
MAX_INPUT_TOKENS = 8000
def build_trial_request(user_input, requested_model):
model = requested_model if requested_model in ALLOWED_TRIAL_MODELS \
else "trial-model-a"
input_tokens = count_tokens(user_input)
if input_tokens > MAX_INPUT_TOKENS:
raise InputTooLarge()
estimate = price_in(model) * input_tokens \
+ price_out(model) * MAX_OUTPUT_TOKENS
return model, MAX_OUTPUT_TOKENS, estimate
前端传来的 max_tokens 和 model 只是参考值,最终以服务端裁定为准。
3.4 发请求、结算与失败处理
发请求前,生成一个唯一的请求 ID 写入预留记录,便于事后在日志里匹配。请求返回后分三种情况处理:
- 成功并拿到 usage:按实际用量计算金额,
spent += actual,reserved -= estimate,预留状态改为 settled。 - 明确未执行的失败:例如参数校验失败、鉴权失败这类能确认请求没有进入计费的错误。此时释放预留,状态改为 released。
- 超时或连接中断:请求可能已经在上游执行并产生费用,只是结果没有传回来。此时不要把费用当作零,状态记为 unknown,预留保持占用。
第 3 种情况最容易出错。如果超时就直接释放预留,等于把可能已经发生的费用从账本里抹掉。在高并发、高超时率的时段,这种误差会持续累积。
3.5 离线对账:修正 unknown 与估算偏差
API易 的日志查询支持增量导出,文档的定位是离线对账,不能用作逐请求放行的依据。所以对账应当做成定时任务:
- 拉取上次对账以来的增量日志,按请求 ID 或时间窗口与
reservations表匹配。 - 日志中能找到的 unknown 预留,按日志里的实际金额改为 settled;超过约定时间窗口仍找不到记录的,再改为 released。
- 统计“预估金额与实际金额”的偏差分布。如果实际金额经常接近甚至超过预估,就要回头检查第 3.3 节的估算公式。
对账结果同时也是给第三道预算线的输入:账本合计与账户实际消耗如果持续对不上,本身就是一个需要人工排查的信号。

4 预算线上线检查与额度不足的友好提示
4.1 三道预算线上线检查表
| 检查项 | 归属预算线 | 验收方式 |
|---|---|---|
| 用户与池的预留在同一事务内完成 | 第一道 | 压测并发请求,确认已花费加预留不超过上限 |
| model、max_tokens、输入长度由服务端裁定 | 第一道 | 篡改前端参数,确认无效 |
| 超时请求记为 unknown 且保持占用 | 第一道 | 注入超时故障,检查账本状态 |
| 对账任务定时运行并处理 unknown | 第一道 | 检查对账日志与状态流转 |
| 试用 Key 独立、额度略高于池预算 | 第二道 | 核对 Key 配置与池预算数值 |
| 试用 Key 模型白名单仅含试用模型 | 第二道 | 用非白名单模型调用,确认被拒 |
| 日额度重置脚本存在且有监控 | 第一、二道 | 检查定时任务的执行记录 |
| 余额告警阈值与处置手册对应 | 第三道 | 演练一次告警到关闭入口的流程 |
4.2 额度不足时的用户提示
预留失败时,应用应当返回明确的业务错误,不要让请求落到网关后再报一个难以理解的错误。提示里建议包含三项信息:
- 发生了什么:例如“本日试用额度已用完”或“当前试用名额已满”,用户额度不足和试用池满了要分开提示。
- 何时恢复:如果设置了日额度,告知重置时间;一次性额度用完的,说明后续可选的升级方式。
- 当前状态:可以展示剩余额度,但要基于账本的可用余量,并且把在途预留扣除在内,避免出现“显示有余额却被拒绝”的情况。
完成上述检查后,可以用一个简单的方法验收整套预算线:模拟一次并发高峰叠加上游超时,确认账本中“已花费 + 在途预留”始终不低于对账后的实际消耗,同时试用 Key 的消耗没有显著越过它的额度。两条都满足,这三道预算线才算真正可用。
参考资料
- API易 令牌管理文档:软上限、remain_quota、日重置与模型白名单说明
- 链接:
docs.apiyi.com/api-capabilities/token-management
- 链接:
- API易 预扣额度说明:估算预扣与事后结算机制
- 链接:
docs.apiyi.com/faq/pre-deduction-quota
- 链接:
- API易 余额告警说明:告警只通知、不拦截
- 链接:
docs.apiyi.com/faq/balance-alerts
- 链接:
- API易 日志查询文档:增量导出与离线对账
- 链接:
docs.apiyi.com/api-capabilities/log-query
- 链接:
- OWASP API Security Top 10 2023:API4 Unrestricted Resource Consumption
- 链接:
api-security.owasp.org/editions/2023/en/0xa4-unrestricted-resource-consumption/
- 链接:
凡事豫则立,不豫则废。——《礼记·中庸》
