Documentation Index
Fetch the complete documentation index at: https://docs.tkhub.ai/llms.txt
Use this file to discover all available pages before exploring further.
1. 概述
/api/usage/token/ 是本平台提供的令牌（Token）使用量查询接口，支持按时间范围查询指定 API Key 的配额使用情况。
用户通过后台管理 Token 进行认证，即可查询自己名下任意 API Key 在指定时间段内的已用额度、剩余额度等信息。
2. 接口地址
| 方法 | 路径 | 作用 |
|---|
| POST | /api/usage/token/ | 查询指定 API Key 的使用量 |
| 环境 | Base URL |
|---|
| 生产环境 | https://api.tkhub.ai |
$BASE_URL 表示，实际调用请替换为对应环境地址。
3. 认证
所有请求均需携带后台管理 Token：
Authorization: Bearer <YOUR_BACKEND_TOKEN>
sk- 开头）不同。
4. 请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|
Authorization | string | 是 | 后台 Token，格式：Bearer <backend_token> |
4.2 请求体（JSON）
| 字段 | 类型 | 必填 | 说明 |
|---|
api_key | string | 是 | API Key（可带 sk- 前缀或不含前缀） |
start_date | string | 是 | 开始日期，格式：YYYY-MM-DD |
end_date | string | 是 | 结束日期，格式：YYYY-MM-DD |
- 日期范围最多 31 天
api_key 必须属于当前认证用户，否则返回 403 错误
5. 请求示例
curl -X POST $BASE_URL/api/usage/token/ \
-H "Authorization: Bearer $BACKEND_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"api_key": "sk-xxxxx",
"start_date": "2026-04-01",
"end_date": "2026-04-30"
}'
6. 响应格式
6.1 成功响应
{
"code": true,
"message": "ok",
"data": {
"object": "token_usage",
"name": "我的Token",
"total_granted": 227.37,
"total_used": 153.64,
"total_available": 73.73,
"unlimited_quota": false,
"model_limits": {},
"model_limits_enabled": true,
"expires_at": 1746681600
}
}
6.2 响应字段说明
| 字段 | 类型 | 说明 |
|---|
object | string | 对象类型，固定为 token_usage |
name | string | Token 名称 |
total_granted | number | 总额度（转换后），保留两位小数 |
total_used | number | 已用额度（转换后），保留两位小数 |
total_available | number | 剩余额度（转换后），保留两位小数 |
unlimited_quota | boolean | 是否无限额度 |
model_limits | object | 模型限制映射 |
model_limits_enabled | boolean | 是否启用模型限制 |
expires_at | integer | 过期时间戳（Unix 秒），0 表示永不过期 |
- 平台支持三种配额显示模式（CNY / Tokens / 美元），由后台设置决定
- 转换公式：
配额值 / QuotaPerUnit × 汇率（CNY 模式）
- 所有金额类字段均保留两位小数
7. 错误响应
7.1 认证失败（401）
{
"success": false,
"message": "Invalid backend token"
}
7.2 参数错误（400）
{
"success": false,
"message": "start_date and end_date must both be provided"
}
{
"success": false,
"message": "Date range cannot exceed 31 days"
}
7.3 权限错误（403）
{
"success": false,
"message": "api_key does not belong to the current user"
}
8. 错误码
| HTTP | message | 说明 |
|---|
| 400 | No Authorization header | 未提供 Authorization header |
| 400 | Invalid Bearer token | Bearer token 格式错误 |
| 400 | Invalid request body | 请求体 JSON 格式错误 |
| 400 | Invalid date format, use YYYY-MM-DD | 日期格式错误 |
| 400 | Date range cannot exceed 31 days | 日期范围超过 31 天 |
| 401 | Invalid backend token | 后台 Token 无效 |
| 401 | Invalid api_key | API Key 不存在 |
| 403 | api_key does not belong to the current user | API Key 不属于当前用户 |
9. 计费说明
- 本接口仅用于查询使用量，不产生任何费用
- 查询的时间范围内的已用配额已包含所有成功计费的任务
- 失败或取消的任务不计入已用额度