用量查询

The guide below is in Chinese.

查询自己账号的调用明细、趋势和可导出的记录。使用登录访问令牌,可按模型、应用和时间筛选。

一、查询调用记录

Shell command
curl "https://staging-api.taotoken.io/api/v1/usage/records" \
  -H "Authorization: Bearer $TP_ACCESS_TOKEN"

排序:固定按发生时间倒序(最新在前),不可配置。

分页:

  • limit(可选):返回条数,默认 20;服务端静默封顶 100(传更大的值不会报错,按 100 处理)
  • offset(可选):跳过的条数,默认 0
  • 过滤后的总条数在响应头 X-Total-Count 中返回,响应体本身不含总数字段

过滤参数(均可选):

参数说明
spu_id按模型(SPU)过滤
sku_id按具体的模型规格(SKU,即实际计费/转发所命中的规格)过滤
from_date / to_date按发生时间过滤,格式 YYYY-MM-DD(UTC),to_date 含当日全天
app_id按应用过滤
client_key_id按 Client Key(ck-… 形式)过滤;非本人名下的 Client Key 一律返回空数组
plan_instance_id按套餐实例过滤;未使用套餐(直接扣余额)的记录此参数筛不到

取数范围:包含你名下 API Key 产生的记录,以及你拥有的应用名下 Client Key(SDK/客户端接入)产生的记录。不包含他人应用的记录。

尚不支持:按终端用户筛选——平台目前没有为终端用户维护持久化的标识。

响应字段(数组每项)

字段类型说明
idstring用量记录 ID
trace_idstring该次调用的链路追踪 ID,反馈问题时提供给平台可用于定位
sku_idstring本次调用命中的模型规格 ID
model_spu_namestring模型展示名
model_sku_namestring具体规格展示名(实际计费/转发使用的规格)
prompt_tokensinteger输入 token 数(不含缓存命中部分)
completion_tokensinteger输出 token 数
total_tokensinteger本次调用总 token 数(上游原始用量值;不保证等于输入+输出之和)
cache_read_tokensinteger命中缓存被读取的 token 数(按缓存读价计费,通常低于原价)
cache_write_tokensinteger写入缓存的 token 数(按缓存写价计费,通常高于原价——输入 token 很少但费用偏高的常见原因)
cache_write_costnumber缓存写入部分的费用(USD),已包含在 total_cost 内
total_costnumber本次调用向你收取的总费用(USD),已含全部分项
video_tokens / video_input_count / video_resolution / video_cost—视频生成相关的计费信息;非视频调用均为 0/null
currencystring币种,固定 USD
statusstringconfirmed 已确认,可用于对账。pending 尚未结算。served_unbilled 已服务但未扣费,token 计入用量,金额不计入费用汇总。已知原因包括余额不足或缺少折扣套餐适用的指导价。请为未知状态保留兜底。
chargesarray本次调用的扣款分段,说明这笔费用从哪个钱包、以什么形态扣的;空数组代表平台本次未收费
price_sourcestringplan 套餐额度、list 平台指导价、cache_storage 缓存存储时长费、spu_guide 折扣套餐的 SPU 指导价与适用折扣、spu_guide_missing 缺少适用指导价时未扣费。
plan_instance_id / plan_namestring / null命中的套餐实例与套餐名;未走套餐扣费时为 null
created_atstring调用发生时间(ISO 8601)

金额相关字段单位统一为美元(USD)。status 与 price_source 是开放枚举(status 目前有 confirmed/pending/served_unbilled 三个已知取值),未来可能新增取值,请确保你的解析逻辑对未知值做降级展示而不是报错。

二、获取筛选项

Code
GET https://staging-api.taotoken.io/api/v1/usage/records/filters

返回你历史用量中出现过的模型列表,可直接用于构造上面接口的 spu_id/sku_id 参数(按调用次数降序,主力模型排在前面)。

三、用量趋势

Code
GET https://staging-api.taotoken.io/api/v1/usage/trends

按天/周/月等粒度对用量做聚合统计,用于绘制趋势图。聚合在服务端完成,不受 /records 接口 100 条的分页上限影响——如果你的调用量较大,趋势图请优先使用本接口而不是自行拉取明细做客户端聚合。

四、导出

Code
GET https://staging-api.taotoken.io/api/v1/usage/records/export

支持与 /records 相同的过滤参数(spu_id/sku_id/from_date/to_date/app_id/client_key_id),另加 fmt 参数选择格式:

fmt返回
json(默认)application/json,文件名 usage_records.json
csvtext/csv,文件名 usage_records.csv;金额列为定点小数文本(如 0.00000118,不会出现科学计数法)
xlsxExcel 文件,文件名 usage_records.xlsx;表头与部分取值为中文,金额为数值单元格

表头语言:可选参数 lang 取 zh 或 en,csv 与 xlsx 的表头都改用该语言的可读文案。不传时行为不变(csv 表头为列键,xlsx 表头为中文);传其它值返回 422。控制台用量页的「导出」按钮会按当前界面语言自动带上这个参数。

行数上限:单次导出固定上限,撞到上限时响应头会带 X-Export-Truncated: true——出现该响应头时说明还有更多数据未导出,请缩小时间范围分批导出。

列范围:导出的字段集合与查询接口略有差异(例如导出内容不含 price_source),但同样不会包含你账号可见范围之外的数据。每次导出平台会留存一条审计记录。

下一步

计费、用量与限流 · 折扣套餐计价说明