响应与计费
Usage 与计费
usage 统计、余额检查和扣费记录。
真实 usage 优先，必要时保守估算
顶级AI优先按对应 API/wire family 提取上游真实 usage，再结合当前模型商品价格结算。按 token 计费的合法非流式成功 JSON 对象，或网关已提取到模型输出的流式响应，在 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 定价的合法非流式成功 JSON 对象，或网关已提取到模型输出的流式响应；
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 和工具参数属于已生成的输出内容，会计入输出估算。
- 合法非流式成功 JSON 对象即使没有可提取输出（包括
{}），也会使用最少 1 个 output token；这不代表上游真实消耗。流式响应没有有效 usage 且没有可提取输出时不估算，心跳、空事件和原始传输 chunk 不构成计费依据。 - 真正空白或畸形的非流式 body 会对客失败并零扣费；无可信 usage 或可提取输出的流式响应零扣费，但已提交的 2xx 不能改写成错误体，body 可能为空或只含 SSE keepalive。没有计费证据时释放预留。断流、客户端取消或交付失败仍可能按网关已观察到的可信 partial usage 或输出结算，不以客户端成功收到 chunk 为前提。非流式响应结算后的交付失败也不回滚扣费，失败状态不必然表示零扣费。
- per-image 商品不使用 token 估算；OpenAI/Gemini 图片入口按响应中实际有效图片数计费，没有有效图片时失败关闭且零扣费，Gemini 图片商品不依赖
usageMetadata。 - 用量记录会标记为估算，便于与上游真实 usage 区分。
不要提交客户端估算值
客户端自行计算的 token 数不会成为账务依据。真实 usage、服务端估算和失败关闭的选择都由网关按实际响应判断。
最后更新于