OpenAI API中的input_tokens、cached_tokens、cache_write_tokens、reasoning_tokens、output_tokens和total_tokens有什么区别？

字段 所在位置 表示什么 是否应额外加到父字段

-- --- --- ---

inputtokens usage 本次处理的输入 Token 总数 基础字段

cachedtokens usage.inputtokensdetails 输入中命中缓存的 Token 否，属于 inputtokens 明细

cachewritetokens usage.inputtokensdetails 输入中写入缓存的 Token 否，属于输入明细

outputtokens usage 本次生成使用的输出侧 Token 基础字段

reasoningtokens usage.outputtokensdetails 输出侧用于推理的 Token 否，属于 outputtokens 明细

totaltokens usage 输入与输出的总使用量 最终汇总字段

具体模型、缓存模式和 API 版本支持的明细可能不同。生产代码应容忍明细字段为0或不存在，并以实际响应 Schema 和对应模型文档为准。

完成的 Response 通常包含 usage，其中有输入、输出、明细和总量。响应刚创建、仍在排队或处理中时，Usage 可能尚不可用；流式应用也应等待完成事件或最终 Response 再入账。

如果请求在网关层直接失败，可能没有模型 Usage。不能把“usage缺失”一律记录为零成本请求，也不能因为没有最终文本就假设模型没有消耗 Token。

inputtokens 表示模型处理的输入总量，可能来自 Instructions、用户消息、会话历史、工具定义、工具结果、图像或文件的编码表示，以及 API 为该请求构建的其他输入内容。