查询消费用量
- 查询指定时间范围内的消费金额与调用统计
- 支持按模型过滤、按模型或自然日分组
- 支持当前 API Key 或整个账号的消费统计
- 返回美元金额、积分、调用次数与 token 用量
使用 API Key 查询指定时间范围内的消费金额,可按模型过滤,并按模型、自然日或二者组合分组。此接口直接返回聚合结果,不需要创建任务或轮询任务状态。
curl --get 'https://26j.cn/v1/usage' \
--header 'Authorization: Bearer <token>' \
--data-urlencode 'start=2026-09-01T00:00:00+08:00' \
--data-urlencode 'end=2026-09-08T00:00:00+08:00' \
--data-urlencode 'group_by=model'
import requests
response = requests.get(
"https://26j.cn/v1/usage",
headers={"Authorization": "Bearer <token>"},
params={
"start": "2026-09-01T00:00:00+08:00",
"end": "2026-09-08T00:00:00+08:00",
"group_by": "model",
},
timeout=30,
)
payload = response.json()
if not response.ok or not payload.get("success"):
message = payload.get("error", {}).get("message", "用量查询失败")
raise RuntimeError(f"HTTP {response.status_code}: {message}")
print(payload["data"]["total"])
print(payload["data"]["items"])
const url = new URL("https://26j.cn/v1/usage");
url.search = new URLSearchParams({
start: "2026-09-01T00:00:00+08:00",
end: "2026-09-08T00:00:00+08:00",
group_by: "model",
}).toString();
const response = await fetch(url, {
headers: { Authorization: "Bearer <token>" },
});
const payload = await response.json();
if (!response.ok || !payload.success) {
throw new Error(
`HTTP ${response.status}: ${payload.error?.message ?? "用量查询失败"}`,
);
}
console.log(payload.data.total);
console.log(payload.data.items);
{
"success": true,
"data": {
"scope": "key",
"start": 1788192000,
"end": 1788796800,
"tz": "Asia/Shanghai",
"group_by": "model",
"total": {
"amount_usd": 12.3456,
"credits": 123.456,
"requests": 1834,
"prompt_tokens": 902311,
"completion_tokens": 215044
},
"items": [
{
"model": "gpt-5.6-luna",
"amount_usd": 9.1271,
"credits": 91.271,
"requests": 1520,
"prompt_tokens": 880120,
"completion_tokens": 201300
},
{
"model": "sora-2",
"amount_usd": 3.2185,
"credits": 32.185,
"requests": 314,
"prompt_tokens": 22191,
"completion_tokens": 13744
}
]
}
}
{
"success": false,
"error": {
"code": "range_too_large",
"message": "Time range must not exceed 31 days.",
"type": "usage_query_error"
}
}
认证
Authorizationstring必填使用与调用模型相同的 API Key,通过 Bearer Token 认证。访问 API Key 管理页面 获取密钥。
Authorization: Bearer YOUR_API_KEY
余额为 0 时仍可查询。本接口不校验余额,但仍校验 API Key 状态、过期时间、IP 白名单及账号状态。
接口端点
GET /v1/usage
GET /usage
两个端点功能相同,支持 CORS 跨域请求。请妥善保管 API Key,不要将其暴露在公开的前端代码中。
请求参数
所有参数均通过 URL Query 传递。
integer | string起始时间,包含该时刻。支持 Unix 秒级时间戳或带时区的 RFC3339 字符串,例如 2026-09-01T00:00:00+08:00。
不传时默认为 end 前 24 小时。时间戳单位为秒,不是毫秒。
integer | string结束时间,不包含该时刻。格式与 start 相同,不传时默认为当前时间。
必须晚于 start,且 end - start 不得超过 31 天。
string模型名称,不传时统计全部模型。多个模型使用英文逗号分隔,最多 50 个。
精确匹配、不区分大小写,不支持通配符。
示例:gpt-5.6-luna,sora-2
string默认 none分组方式:
none:仅返回合计,items为空数组model:按模型分组date:按自然日分组model,date:按模型和自然日组合分组
string默认 Asia/ShanghaiIANA 时区名称,默认 Asia/Shanghai。
仅影响 group_by 包含 date 时的自然日边界,不改变查询的起止时刻。RFC3339 起止时间仍按其自身携带的时区解析。
string默认 key统计范围:
key:仅统计当前 API Key(默认)account:统计当前 API Key 所属账号的全部 API Key 合计
查询时间区间为 [start, end):包含起点、不包含终点。相邻查询以相同的时间作为前一次的 end 和后一次的 start,不会重复计算边界时刻。
手动拼接 URL 时,RFC3339 中的 + 必须编码为 %2B。示例中的 cURL --data-urlencode、Python params 和 JavaScript URLSearchParams 会自动处理编码。
请求示例
当前 API Key 最近 24 小时的消费合计
不传 Query 参数即可使用默认时间范围、默认统计范围和默认分组方式:
curl 'https://26j.cn/v1/usage' \
--header 'Authorization: Bearer <token>'
整个账号指定模型的每日消费
查询 2026 年 9 月 11 日至 9 月 18 日(北京时间,不含 9 月 18 日)的消费:
curl --get 'https://26j.cn/v1/usage' \
--header 'Authorization: Bearer <token>' \
--data-urlencode 'start=1789056000' \
--data-urlencode 'end=1789660800' \
--data-urlencode 'model=gpt-5.6-luna' \
--data-urlencode 'group_by=date' \
--data-urlencode 'scope=account' \
--data-urlencode 'tz=Asia/Shanghai'
按模型和自然日组合分组
curl --get 'https://26j.cn/v1/usage' \
--header 'Authorization: Bearer <token>' \
--data-urlencode 'start=2026-09-01T00:00:00+08:00' \
--data-urlencode 'end=2026-09-08T00:00:00+08:00' \
--data-urlencode 'model=gpt-5.6-luna,sora-2' \
--data-urlencode 'group_by=model,date' \
--data-urlencode 'tz=Asia/Shanghai'
该分组方式下,每个 items 元素同时包含 model 和 date。
响应字段
successboolean查询是否成功。成功时为 true,用量查询错误时为 false。
dataobject成功时返回查询范围、合计与分组明细。
data.total 与 data.items[] 共用以下统计字段:
| 字段 | 类型 | 说明 |
|---|---|---|
amount_usd |
number | 美元金额,保留 6 位小数 |
credits |
number | 站内积分,等于 amount_usd × 10,与官网展示单位一致 |
requests |
integer | 计费成功的调用次数 |
prompt_tokens |
integer | 输入 token 数;按次或按秒计费的图片、视频模型通常为 0 |
completion_tokens |
integer | 输出 token 数;按次或按秒计费的图片、视频模型通常为 0 |
errorobject用量查询错误时返回,包含 code、message 和 type,其中 type 为 usage_query_error。401 / 403 鉴权错误由鉴权层返回。
限流与缓存
- 每把 API Key 每分钟最多查询
60次,同时受全局 API 限流约束 - 相同参数的查询结果缓存
60秒,响应头X-Usage-Cache为hit或miss - 通常 1 秒内可查到消费记录,但最近 1 分钟的数据可能不完整,且存在缓存延迟
- 建议查询间隔不低于 1 分钟,不要将本接口作为实时扣费通知
统计口径
- 数据来自计费成功的调用记录,与官网“数据看板”使用相同数据
- 调用失败或任务失败后退款的记录不计入,无需自行冲抵;组图部分成功时按实际交付张数计费
- 按计费落账时刻归属消费;异步图片、视频任务在完成时落账,不是提交时刻。跨零点任务归入完成当天
- 删除后重建的 API Key 属于新的 Key;使用新 Key 查询
scope=key时,不包含旧 Key 的历史 - 后台人工调整余额不属于调用消费,不在统计范围内
- 可查询 2026 年 4 月 27 日之后的数据
错误处理
| HTTP 状态码 | error.code |
说明 |
|---|---|---|
| 400 | invalid_start / invalid_end |
起止时间格式无效 |
| 400 | invalid_range |
end 不大于 start |
| 400 | range_too_large |
时间跨度超过 31 天,请拆分为多个查询区间 |
| 400 | invalid_tz |
未知的 IANA 时区 |
| 400 | invalid_group_by |
分组方式无效 |
| 400 | invalid_scope |
统计范围无效 |
| 400 | too_many_models |
模型数量超过 50 个 |
| 401 / 403 | — | API Key 无效、过期、IP 不在白名单或账号被停用 |
| 429 | — | 超过每 Key 每分钟 60 次的限制,或触发全局 API 限流 |
| 503 | usage_unavailable |
用量数据暂时不可用,请稍后重试 |
收到 503 usage_unavailable 时,不会返回任何金额。这表示查询不可用,不表示消费为 0;不要将失败响应转换为零金额或覆盖此前成功查询的结果。
与其他接口的区别
| 接口 | 能力 |
|---|---|
GET /v1/dashboard/billing/usage |
返回累计已用总额,不能按模型或时间筛选 |
POST /v1/logs/export |
异步导出调用明细(CSV / XLSX),需要自行汇总 |
GET /v1/usage |
按指定时间与模型查询,直接返回消费合计及分组明细 |
This documentation is built and hosted on Mintlify, a developer documentation platform.