VanaAPI
登录

← 文章

逐步读懂 API 响应中的用量字段

接口格式ZH2026-10-25

接入模型后，建议先把用量记录接好，再做成本分析。本篇从一条请求开始，依次检查输入、输出、缓存和流式统计，建立可核对的记录方式。

§ 第一步：保存一条完整响应

Vana API 提供统一入口，支持 OpenAI 兼容接口、Anthropic Messages 和 Gemini 原生协议。统一地址不意味着所有响应的字段名称相同。先关闭流式输出，发送一个简短问题，并保存脱敏后的请求参数、响应正文和请求标识。([vanaapi.com](https://vanaapi.com/))

建议把这次调用作为测试样本，后续调整解析逻辑时重复使用。不要只保存回答文本，否则排查统计差异时会缺少原始依据。

§ 第二步：按协议找到统计对象

先确认调用的是哪一种接口，再选择解析路径，不要根据模型品牌猜测字段名称。

  • OpenAI 聊天补全接口读取 usage.prompt_tokens、usage.completion_tokens 和 usage.total_tokens。([platform.openai.com](https://platform.openai.com/docs/api-reference/chat/object?lang=ruby&utm_source=openai))
  • OpenAI Responses 接口使用 usage.input_tokens、usage.output_tokens 和 usage.total_tokens，不能直接套用聊天补全的字段名。([platform.openai.com](https://platform.openai.com/docs/api-reference/responses-streaming/response/reasoning_summary_part?lang=javascript&utm_source=openai))
  • Anthropic Messages 读取 usage.input_tokens、usage.output_tokens，并检查缓存相关字段。([platform.claude.com](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?2f226f2c_page=2&d7430fcd_page=2&e45d281a_page=2&query=spam&utm_source=openai))
  • Gemini 原生接口读取 usageMetadata，其中包含 promptTokenCount、candidatesTokenCount 和 totalTokenCount。([ai.google.dev](https://ai.google.dev/api/generate-content))

§ 第三步：区分总量与明细

在聊天补全响应中，prompt_tokens_details.cached_tokens 是输入中的缓存部分；completion_tokens_details.reasoning_tokens 是输出中的推理部分。它们是明细，不应再加到对应总量上。([platform.openai.com](https://platform.openai.com/docs/api-reference/chat/object?lang=ruby&utm_source=openai))

例如，一条假设响应显示输入为 1000、输出为 200、缓存输入为 800，总量仍是 1200，而不是 2000。可以把这些数值写进测试用例，检查你的汇总函数是否重复计算。

§ 第四步：单独处理缓存和思考用量

Anthropic Messages 的缓存统计口径不同：完整输入量需要将 input_tokens、cache_creation_input_tokens 和 cache_read_input_tokens 相加。不要把 input_tokens 单独当作全部输入。([platform.claude.com](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?2f226f2c_page=2&d7430fcd_page=2&e45d281a_page=2&query=spam&utm_source=openai))

Gemini 的 promptTokenCount 已包含缓存内容，cachedContentTokenCount 不应再次加入输入。另行保留 thoughtsTokenCount，因为可见候选输出并不代表全部生成用量；核对时优先保留服务端给出的 totalTokenCount。([ai.google.dev](https://ai.google.dev/api/generate-content))

§ 第五步：等流式统计结束再入账

使用支持该选项的聊天补全流式接口时，设置 stream_options.include_usage 为 true。最终统计块的 choices 可以为空，解析器不能因此丢弃它；连接中断时，也可能收不到这个块。([platform.openai.com](https://platform.openai.com/docs/api-reference/chat/object?lang=ruby&utm_source=openai))

Anthropic 流式响应中，message_delta 的用量是累计值，不是每个事件新增的数量。保留初始输入信息，并用后续累计值更新对应字段，不要逐事件求和。([platform.claude.com](https://platform.claude.com/docs/en/build-with-claude/streaming?utm_source=openai))

§ 第六步：建立可核对的用量记录

建议每次实际请求保存协议、模型、时间、请求标识、原始统计对象，以及解析后的输入、输出和缓存数量。缺失字段标记为“未知”，明确返回的零才记录为零；重试应保留独立记录，再关联到同一次业务操作。

令牌数量不等于费用。建议按适用价格分别核算各类用量，再与账单记录核对，不要用总令牌数直接乘一个统一单价。准备接入时，可以创建一个 Vana API 账户，从一条非流式请求和一条流式请求开始验证这套记录流程。

再读一篇