BeefAPI读取用量汇总
查询当前企业 Key 的人民币结算、预留和退回汇总。
GET https://enterprise.beefapi.com/v1/usage
使用企业 Key 的 Bearer 认证。结果只覆盖该 Key、所属账号和企业市场，不包含其他 Key 的消费，也不返回钱包余额。
curl --fail-with-body https://enterprise.beefapi.com/v1/usage \
-H "Authorization: Bearer $BEEFAPI_KEY"查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
start_time | 正整数 | 起始 Unix 秒，包含该时刻 |
end_time | 正整数 | 结束 Unix 秒，不包含该时刻 |
model | string | 可选，精确模型 ID |
request_id | string | 可选，仅汇总对应请求记录 |
不传时间时默认最近约 30 天。起始必须早于结束，单次跨度最多 31 天。跨月报表分段查询并保持时间边界连续，避免重叠统计。
筛选示例，运行前将时间变量设置为自己的 Unix 秒：
curl --fail-with-body --get https://enterprise.beefapi.com/v1/usage \
-H "Authorization: Bearer $BEEFAPI_KEY" \
--data-urlencode "start_time=$START_TIME" \
--data-urlencode "end_time=$END_TIME" \
--data-urlencode 'model=seedance-2.0-mini'响应
下列为结构示例，不代表真实用量：
{
"currency":"CNY",
"start_time":1790000000,
"end_time":1790086400,
"settled_amount":"1.200000",
"pending_amount":"0.000000",
"refunded_amount":"0.000000",
"records":1,
"unknown_records":0,
"by_model":[{"model":"gpt-5.6-sol","settled_amount":"1.200000","pending_amount":"0.000000","refunded_amount":"0.000000","records":1,"unknown_records":0}],
"daily":[]
}| 字段 | 解释 |
|---|---|
currency | 企业响应为 CNY |
settled_amount | 已结算金额汇总，可含负向调整 |
pending_amount | 待结算预留金额 |
refunded_amount | 已记录退回金额；不要从已结算值重复减去 |
records | 纳入统计的记录数，不保证等于生成成功数 |
unknown_records | 账务状态未知的记录数 |
by_model | 按模型分桶，字段与汇总一致 |
daily | 按日期分桶，含 date 和同类金额字段 |
金额使用十进制字符串，建议使用十进制定点库计算，避免浮点误差。该接口是消费记录视图，不是剩余额度、充值金额或发票。
错误与查询权限
过期、耗尽或停用但仍存在的 Key 可查询历史；仍需通过站点、账号和 IP 限制。删除 Key 后不能依靠旧密钥继续访问。参数错误返回 400，查询过于频繁可能返回 429，读取失败可能返回 503；缩小时间区间并有限重试。