本文介绍如何解析查询用量明细导出任务状态返回的 DownloadUrl 对应的 CSV 文件，重点说明字段说明、切换时刻、生效规则、charge_value_list 解析、多模态用量返回范围、兼容策略和多语言示例代码。

CSV 格式与版本变化

切换时刻与生效规则

GetRecordExportTask 根据导出任务查询窗口的结束时间 EndTime 决定该任务使用的 CSV 格式。切换时刻根据用户的首次调用时间分为两类：

2026 年 9 月 2 日前已产生调用的用户：切换时刻为 2026 年 9 月 15 日。

2026 年 9 月 2 日及以后新增调用的用户：切换时刻为 2026 年 9 月 2 日。

生效规则如下：

EndTime 早于或等于对应切换时刻：CSV 返回旧格式。

EndTime 晚于对应切换时刻：CSV 返回新格式。

任务提交后，该任务对应的 CSV 字段格式保持不变，不会在轮询期间发生切换。

新旧格式差异

GetRecordExportTask 接口的请求参数、响应参数以及 DownloadUrl 的生成方式保持不变。本次变更仅影响通过 DownloadUrl 下载的 CSV 文件内容格式。

旧格式：18 列。

新格式：16 列。

删除字段：input_token_charge_item、output_token_charge_item、cache_hit_token_charge_item。

新增字段：charge_value_list。该字段位于 volc_instance_id 之后、timestamp 之前，用于统一返回各计费项信息。

其他字段：其余字段名称、顺序和含义保持不变。

CSV 字段说明

新格式 CSV 字段

新格式 CSV 文件按以下顺序返回字段。

标识与模型字段

字段	说明
req_id	业务请求 ID，用于关联请求与用量明细。
uuid	计量记录唯一标识，用于定位和识别同一条记录。
account_id	用量归属的火山账号 ID。
user_id	上游记录中的调用用户 ID；未提供时为 0。
model_name	计量记录归属的模型名称。
model_version	模型版本标识。
model_endpoint	请求关联的模型接入点 ID。

用量与计费字段

字段	说明
input_tokens	输入 Token 数；在文本推理场景下，包含缓存命中的 Token 数。
output_tokens	输出 Token 数；生视频的输出 Token 也在此列，不表示视频时长。
cache_hit_tokens	输入中命中的缓存 Token 数，不应与输入量重复相加。
billing_status	计费分类状态。当前 CSV 返回 normal 状态的按量后付计量明细。
product	计费归属的产品 code，来自计费配置。
volc_instance_id	关联的火山交易或计费实例 ID，与模型接入点 ID 不同。
charge_value_list	计费项列表。每个元素包含 code、value 和 scale，单项计量值为 value / scale。

时间字段

字段	说明
timestamp	上游事件的 Unix 时间戳，单位为秒，不是 CSV 导出时间。
pt_hour	数据所属小时分区，格式为 YYYY-MM-DD HH:00:00。

charge_value_list 解析

对于新格式 CSV，charge_value_list 的值为 JSON 数组字符串。数组中的每个元素表示一个计费项。

示例如下：

字段说明：

code：计费项名称，对应旧格式中的 *_charge_item 字段值。

value：整数计量值，例如 token 数或其他计费计量值。

scale：整数缩放因子。

单个计费项的计量值为 value / scale。

多模态与字段限制

以下信息无法通过该 CSV 查询：

信息类型	说明
音频用量	当前不支持通过该 CSV 查询音频用量，不提供音频 Token 拆分和音频时长等字段。
生视频分辨率和时长	当前不支持通过 CSV 查询生视频的具体分辨率和时长；计费项 code 只能辅助识别计费档位，无法还原精确分辨率。
生图数量和规格	当前不支持通过 CSV 查询生成图片数量、输入图片数量、像素和规格；生图计费用量以 charge_value_list 中的计费项为准。
其他业务详情	当前不支持通过 CSV 查询完整的业务任务详情。

解析与兼容建议

兼容历史格式：同时处理新旧 CSV 时，建议优先根据列名判断格式。仅当解析逻辑依赖字段位置时，再根据列数 18 或 16 分支处理。

当读取到 charge_value_list 字段时：需先执行 JSON 解析，再遍历数组元素获取各计费项的真实计费值。

若已有旧逻辑依赖 input_token_charge_item、output_token_charge_item、cache_hit_token_charge_item 三列：需迁移为读取 charge_value_list 后按 code 分发处理。

注意事项

影响范围：本次变更仅影响通过 DownloadUrl 下载的 CSV 文件内容，不影响 GetRecordExportTask 接口的请求参数、响应参数 schema 和 DownloadUrl 字段本身的返回逻辑。

建议在任务完成并拿到 DownloadUrl 后尽快下载文件。下载链接有效期为 12 小时，过期后需重新提交任务以获取新链接。

兼容历史结果：业务需要长期兼容历史导出结果时，建议同时保留新旧格式的解析分支，不要仅按固定列位置解析。

账单说明：CSV 中的计费用量仅用于对账，最终费用以火山引擎控制台费用中心 > 账单管理中的账单为准。

示例代码

以下示例用于读取 DownloadUrl 对应的 CSV 文件，解析 charge_value_list 中的 JSON 数组，并输出每条记录的请求 ID、各计费项的计量值及 total_billing 汇总值。示例代码可用于本地排查、解析逻辑校验和业务接入前验证。

Python

Go

Java

C++

返回示例如下：

火山方舟