账单查询与导出

账单统计按时间粒度汇总模型调用用量、次数和消费金额；Excel 账单用于保存和离线核对记录。

准备访问令牌

在个人资料页面的“安全”区域创建访问令牌，然后填入查询账单统计或导出账单的在线调试。

选择时间与筛选条件

选择统计粒度，例如选择“天”查看每日汇总。
填写开始、结束时间的秒级 Unix 时间戳，或使用输入框右侧的日期选择器。日期选择器按浏览器本地时区转换；查询整天时，请检查结束时间是否覆盖当天。
如需只查看某个 API Key 或模型，再填写名称；查看全部匹配记录时，将这两个筛选项留空。

筛选项	是否必填	使用方式
统计粒度 `type`	是	1=分钟、2=小时、3=天、4=周、5=月
开始、结束时间	是	`startTime`、`endTime`，单位为秒；结束时间不能早于开始时间
API Key 名称 `tokenName`	否	填写名称，不是 Key 密钥或访问令牌；省略时不按名称筛选
模型名称 `modelName`	否	填写实际模型名称；省略时不按模型筛选

查询并查看统计结果

在查询账单统计的在线调试中提交条件。响应体 code=200 表示业务成功，data 为汇总记录数组，不是逐次调用日志。

time、timeGroup：统计记录的时间与秒级分组时间戳。
callCount、totalUseTime：调用次数与累计耗时。
totalPromptTokens、totalCompletionTokens 及缓存字段：输入、输出与缓存相关用量。
totalAmount：消费金额；字段说明和完整响应示例见 Reference，不要将 Token 用量直接当作金额。

如果返回 code: 200、data: []，表示查询成功，但所选时间范围和筛选条件没有匹配记录。

部分可选字段可能为 null，不要将其当作 0。

导出 Excel 账单

在导出账单的在线调试中使用相同条件提交。成功取得文件后：

核对结果区显示的导出时间范围。
保留自动生成的时间范围文件名，或修改“文件名称”；.xlsx 后缀会自动保留。
点击“下载 Excel 账单”，将文件保存到本地。

文件名中的时间按浏览器本地时区显示。Excel 的内容与列结构由平台生成，修改下载名称不会改变账单内容；核对查询与导出结果时，请保持时间范围、粒度及名称筛选一致。

HTTP 200 不一定表示导出成功：如果返回 JSON，应先处理业务错误，不要将它保存成 .xlsx 文件。

常见问题

现象	处理方式
查询成功但没有记录	检查时间戳单位和日期范围，再尝试清空名称筛选
业务 `code: 401`，提示“未授权访问”	检查访问令牌是否有效；确认有效后仍失败，请联系平台支持
导出返回业务 `code: 400`，提示“参数验证失败”	检查是否填写统计粒度及开始、结束时间
导出返回业务 `code: 500`，提示 `ERROR`	先检查 JSON 格式与参数类型；确认正确后仍失败，再联系管理员
下载文件无法用 Excel 打开	检查响应 Content-Type，确认没有将 JSON 业务错误保存为 Excel 文件

以上导出业务错误可能出现在 HTTP 200 响应中，不能只根据 HTTP 状态判断成功。不同输入的完整响应示例见对应 Reference。

当前模型价格可在模型广场查看。

在程序中调用

下面的 Bash 示例依赖 curl 和 jq，覆盖获取认证、查询统计和保存 Excel 三个步骤。

将下面三个代码块按顺序合并保存为一个 .sh 文件，修改访问令牌和查询时间后，使用 bash 运行；不要逐段粘贴到交互式终端。

示例范围为北京时间 2026-10-10 00:00:00 至 2026-10-20 23:59:59，粒度为天，不附加名称筛选；请替换为需要查询的时间。

1. 获取账单认证

用访问令牌调用 GET /api/user/self，解析 data.remark 中的 token，再用于同一站点的账单请求。访问令牌用于第一步 Bearer 认证，不能直接替代账单请求的 token Header。

set -euo pipefail

ACCESS_TOKEN='your-user-token'

BILLING_TOKEN=$(curl --fail --silent --show-error "https://api.agtcloud.cn/api/user/self" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | \
  jq -er '
    select(.success == true)
    | .data.remark | fromjson | .token
    | select(type == "string" or type == "number")
    | tostring | select(length > 0)
  ')

2. 查询统计

curl --fail-with-body "https://api.agtcloud.cn/bill/stats" \
  -X POST \
  -H "token: ${BILLING_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": 3,
    "startTime": 1791561600,
    "endTime": 1792511999
  }'

读取 JSON 中的 code 判断业务是否成功，不要仅依赖 cURL 的退出状态。根级 timestamp 是毫秒级响应时间，不要与秒级查询时间混用。

3. 校验并保存 Excel

成功响应应为 application/vnd.openxmlformats-officedocument.spreadsheetml.sheet 文件流，而不是 JSON 业务错误。

下面先将响应写入临时文件，只有 HTTP 状态为 200、类型为 Excel 且文件非空时，才保存为 bill_export.xlsx；已有同名文件不会被覆盖。

response_file=$(mktemp './.bill_export.XXXXXX')
[[ "$response_file" == ./.bill_export.* && -f "$response_file" && ! -L "$response_file" ]] || exit 1
trap 'if [[ "$response_file" == ./.bill_export.* && -f "$response_file" && ! -L "$response_file" ]]; then rm -f -- "$response_file"; fi' EXIT

response_meta=$(curl --silent --show-error "https://api.agtcloud.cn/bill/excel" \
  -X POST \
  -H "token: ${BILLING_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": 3,
  "startTime": 1791561600,
  "endTime": 1792511999
}' \
  --output "$response_file" \
  --write-out '%{http_code}\n%{content_type}')

http_status=${response_meta%%$'\n'*}
content_type=${response_meta#*$'\n'}
if [[ "$http_status" != 200 || "${content_type%%;*}" != application/vnd.openxmlformats-officedocument.spreadsheetml.sheet || ! -s "$response_file" ]]; then
  printf 'Export failed: HTTP %s (%s)\n' "$http_status" "$content_type" >&2
  if [[ "${content_type%%;*}" == application/json ]]; then
    jq '{code, message}' "$response_file" >&2
  fi
  exit 1
fi

if [[ -e bill_export.xlsx || -L bill_export.xlsx ]]; then
  printf 'bill_export.xlsx already exists; choose another filename.\n' >&2
  exit 1
fi
mv -n -- "$response_file" bill_export.xlsx
if [[ -e "$response_file" ]]; then
  printf 'bill_export.xlsx already exists; choose another filename.\n' >&2
  exit 1
fi
printf 'Saved bill_export.xlsx\n'