Usage
查询当前 Key 的余额、额度、时间窗限额和用量统计。适合在脚本或客户端状态栏中展示剩余额度。
GET/v1/usage
查询参数
daysinteger
返回最近多少天的每日用量,范围 1–90。超出范围返回 400。
start_datestring
模型统计的起始日期,格式 YYYY-MM-DD。默认 30 天前。
end_datestring
模型统计的结束日期(含当天),格式 YYYY-MM-DD。默认今天。
timezonestring
每日用量的时区,例如 Asia/Shanghai。
bash
curl "https://api.thetaio.tech/v1/usage?days=7" \
-H "Authorization: Bearer $THETAIO_API_KEY"响应模式
响应的 mode 字段说明 Key 的计费方式:
mode | 条件 | 关键字段 |
|---|---|---|
quota_limited | Key 设置了总额度或时间窗限额 | quota、rate_limits、expires_at |
unrestricted | Key 没有独立限额,按钱包或订阅扣费 | planName、remaining、balance 或 subscription |
json
{
"mode": "quota_limited",
"isValid": true,
"status": "active",
"quota": { "limit": 50, "used": 12.4, "remaining": 37.6, "unit": "USD" },
"remaining": 37.6,
"unit": "USD",
"rate_limits": [
{
"window": "5h",
"limit": 5,
"used": 1.2,
"remaining": 3.8,
"window_start": "2026-11-19T04:00:00+08:00",
"reset_at": "2026-11-19T09:00:00+08:00"
}
],
"expires_at": "2026-12-31T23:59:59+08:00",
"days_until_expiry": 42
}json
{
"mode": "unrestricted",
"isValid": true,
"planName": "钱包余额",
"remaining": 86.2,
"balance": 86.2,
"unit": "USD"
}json
{
"mode": "unrestricted",
"isValid": true,
"planName": "Pro 订阅",
"remaining": 18.5,
"unit": "USD",
"subscription": {
"daily_usage_usd": 1.5,
"weekly_usage_usd": 6.2,
"monthly_usage_usd": 21.0,
"daily_limit_usd": 20,
"weekly_limit_usd": 100,
"monthly_limit_usd": 300,
"expires_at": "2026-12-19T00:00:00+08:00"
}
}用量统计字段
所有模式在有数据时还会返回:
| 字段 | 说明 |
|---|---|
usage.today / usage.total | 今日与累计的请求数、输入 / 输出 / 缓存 Token、cost、actual_cost |
daily_usage | 按 days 返回的每日用量 |
model_stats | start_date 至 end_date 内按模型汇总的用量 |
这些统计是尽力而为的:统计服务不可用时字段会缺省,不影响额度字段的返回。额度耗尽或已过期的 Key 仍可调用此接口。