响应与计费
Usage 与计费
usage 统计、余额检查和扣费记录。
真实 usage 优先，必要时保守估算
顶级AI优先按对应 API/wire family 提取上游真实 usage，再结合当前模型商品价格结算。按 token 计费的合法 JSON 对象，或已经交付至少一个上游/model chunk 的 stream，在 usage 缺失或无效时，可能采用保守下界估算。
调用到结算的顺序
调用前检查
验证用户 API Key、并发限制、模型状态和账户余额。扣除在途请求预留金额后的可用余额必须大于 0，才能发起模型调用。
选择上游候选
按内部调用入口和模型商品 public model id 选择可用上游。
转发请求并读取响应
非流式读取完整响应；流式响应按对应 API/wire family 观察 usage：OpenAI Chat 和 Gemini 保留最后有效 usage，Anthropic 合并 stream usage，Responses 读取完成事件里的 response usage。
提取 usage 并结算
usage 合法时写入真实用量；符合安全条件但 usage 缺失或无效时写入估算标记；无法安全结算时失败关闭。产生扣费时同时写入账务流水。
余额边界
余额可以结算后变成负数
调用发起前，账户余额扣除在途请求预留金额后的可用余额必须大于 0。一次调用完成结算后，账户余额允许被扣成负数；可用余额为 0 或负数时不能发起新的模型调用。
各 API family / operation 的 usage 来源
Prop
Type
usage 异常
| 网关字符串 | 含义 | 常见原因 |
|---|---|---|
usage_missing | 上游响应缺少可结算 usage | 上游没有返回 usage，或流式响应没有观察到当前 API/wire family 要求的 usage |
usage_invalid | usage 格式不符合要求 | token 字段为负数、类型不对、缓存 token 大于输入 token |
保守下界估算
估算不是通用的 token 计算器，只是防止“有效内容已经交付，但上游漏回 usage”时整笔调用逃逸计费的兜底：
- 仅适用于按 token 定价的合法 non-stream JSON 对象或已经交付至少一个上游/model chunk 的 stream；
usage_missing和usage_invalid都可能进入该兜底。 - 只估算输出：汇总可见文本、
reasoning/reasoning_content、Anthropicthinking与tool_use.input、OpenAI Chat / Responses 的 tool/function arguments 与 reasoning summary，以及 GeminifunctionCall；按 Unicode 字符数约每 4 个字符折算 1 token。 - 不估输入 token 或缓存输入 token。上面的 reasoning、thinking 和工具参数属于已生成的输出内容，会计入输出估算。
- 合法且已交付的 envelope/chunk 即使没有可提取输出，也会使用最少 1 个 output token；这只是防止零计费逃逸的保守下限，不代表上游真实消耗。
- 真正空或纯空白的 non-stream body、畸形 non-stream body 会对客失败并零扣费。上游/model 零 chunk 流已经提交 2xx，body 可能为空或只含网关 SSE keepalive，不能改写成错误体；网关会记录失败、释放预留并零扣费。已经交付内容后发生断流或客户端取消，仍按已收集的 partial usage 或已交付输出下限结算。
- per-image 商品不使用 token 估算；OpenAI/Gemini 图片入口按响应中实际有效图片数计费，没有有效图片时失败关闭且零扣费，Gemini 图片商品不依赖
usageMetadata。 - 用量记录会标记为估算，便于与上游真实 usage 区分。
不要提交客户端估算值
客户端自行计算的 token 数不会成为账务依据。真实 usage、服务端估算和失败关闭的选择都由网关按实际响应判断。
最后更新于