大模型 API Token 计费：从预估到 usage 对账的完整账本

三家厂商都提供请求前 token 计数能力，但结果应用于预算、上下文检查和模型路由，而非最终账单。Claude 官方还提醒计数是估计值，实际 Messages 输入可能有小幅差异；因此 estimate_tokens 与 billed_usage 必须分列。

请求后保存原始 usage JSON，并提取 provider、model、input、cache read、cache write、output、thinking/reasoning 和 total。任何无法映射的新增字段先进入 provider_extra，不应静默并入 input。

证据边界：本节以 S1 支持“官方指南说明请求前 token counting 与请求后 usage 的成本核算职责。”。

OpenAI 的 cached_tokens 与 cache_write_tokens、Claude 的 cache_read_input_tokens 与 cache_creation_input_tokens、Gemini 的 cached_content_token_count 描述相近但规则不同。统一账本可使用 cached_read_tokens 和 cache_write_tokens，但必须保留 provider_semantics 与原字段。

Gemini 还会暴露 thoughts_token_count，OpenAI reasoning 模型有 reasoning_tokens；这些字段在厂商价格口径中可能计入输出相关费用。统一层应叫 hidden_or_thinking_output_tokens，并通过每家价格规则决定是否单独计价，不能假设三家完全相同。

证据边界：本节以 S2 支持“官方 token counting endpoint 接受与 Messages 相同的结构化输入并返回估计输入 token。”。

展示层可以统一到每百万 token，但底层必须保留原始计价单位、币种、模态和上下文档位。文本、图片、音频、视频或文档可能采用不同 token 化与价格规则，相同 token 数并不意味着相同信息量或成本。

跨厂商比较应以同一业务样本为基准：固定输入文件、目标输出 schema、质量阈值和最大重试次数，分别调用各模型并记录实际 usage。最终比较每个合格任务成本，而不是只把价格页上的每百万 token 数字排成一列。

证据边界：本节以 S3 支持“官方指南区分 count_tokens 的请求前估算与 usage_metadata 的输入、缓存、输出和 thinking 用量。”。

对每个 provider 计算 estimate_error＝实际输入 token－请求前估计 token，并按模型、语言、工具和模态分组。误差持续扩大通常意味着 tokenizer、请求渲染或工具定义发生变化，需要重新基线，而不是继续沿用旧换算比例。

同时计算 cost_per_successful_task＝所有尝试总成本÷合格结果数，并保留 latency 与 quality。这样可以识别一种常见情况：单 token 更便宜的模型因为输出更长或重试更多，最终每任务成本反而更高。

工程落地时，为“大模型 API Token 计费”建立独立 article_run_id，并保存 selected_semrush_record、database、measured_on、source_snapshot_ids、content_hash、reviewer 与 gate_status。Semrush 字段只参与选词和意图决策，不进入价格公式，也不把 US 指标解释成中文或中国市场需求。

论点账本必须逐条可回放：S1 对应 C1：“请求前 token counting 用于预算，请求完成后的 usage 才是成本对账的主要依据。”；S3 对应 C2：“Gemini usage_metadata 分别提供输入、缓存、输出与 thinking 等语义字段，统一账本应按语义映射而非只复制字段名。”。编辑器在段落层写入 evidenceRefs，构建检查确认引用 ID 存在；来源页面发生结构变化时，只把对应论点退回复核，不让整篇文章静默继承旧快照。

动态复核字段包括：当前 token counting 接口、支持模型与请求结构、响应 usage 字段名及 thinking/cached token 口径。发布任务应读取当前页面、保留原始单位和地区、与上一快照做字段级 Diff，并记录核验日期 2026-08-29。缺失、受限或无法确认的值保持 null 或“待复核”，不使用 0、均值或相邻产品代填。

独立 SVG 采用“请求前估算到响应后对账的数据流”结构，输入维度为：预估输入、缓存用量、输出、thinking、最终费用。图表只绘制有来源的数据，缺失项显示空缺；alt、caption、图内标题与正文使用同一术语，并在图注标明动态字段核验日期。