> ## 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.

# usage-query

## 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：

```text theme={null}
Authorization: Bearer <YOUR_BACKEND_TOKEN>
```

后台 Token 为用户在后台管理系统中生成的认证凭证，与普通 API Key（`sk-` 开头）不同。

***

## 4. 请求参数

### 4.1 Header 参数

| 字段              | 类型     | 必填 | 说明                                   |
| --------------- | ------ | -- | ------------------------------------ |
| `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. 请求示例

```bash theme={null}
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 成功响应

```json theme={null}
{
  "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）

```json theme={null}
{
  "success": false,
  "message": "Invalid backend token"
}
```

### 7.2 参数错误（400）

```json theme={null}
{
  "success": false,
  "message": "start_date and end_date must both be provided"
}
```

```json theme={null}
{
  "success": false,
  "message": "Date range cannot exceed 31 days"
}
```

### 7.3 权限错误（403）

```json theme={null}
{
  "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. 计费说明

* 本接口仅用于查询使用量，不产生任何费用
* 查询的时间范围内的已用配额已包含所有成功计费的任务
* 失败或取消的任务不计入已用额度

***