# 大模型（LLM）账单查询 API

## 概述

大模型账单查询 API 用于查询当前账户名下大模型（文本）调用的消费数据，提供两个独立接口：

- **账单明细**：按「日期 / 小时 / 模型 / 计费项」展开的逐条用量与费用（支持分页）。
- **账单汇总**：按「API Key / 模型 / 套餐」聚合的用量与总费用（一次性返回，数据量小）。

两个接口的数据与控制台「账单」页面同源同口径。

## 接口信息

- **明细接口**: `GET /api/v2/open/llm/bill/details`
- **汇总接口**: `GET /api/v2/open/llm/bill/summary`
- **认证方式**: Bearer Token (API Key)

## 公共请求参数

### Headers

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| Authorization | string | 是 | Bearer {API_KEY} |

### Query Parameters（两个接口通用）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| from | string | 否 | 起始时间。支持秒级时间戳或 `YYYY-MM-DD`（按服务器本地时区解释，当天从 00:00:00 起算）。缺省为最近 30 天 |
| to | string | 否 | 结束时间。格式同 `from`（当天到 23:59:59 止）。缺省为当前时间 |

> **时间范围上限**：`from` 与 `to` 的跨度最多 **31 天**，超出会返回参数错误。查询更长区间请分段拉取。

---

## 1. 账单明细接口（分页）

`GET /api/v2/open/llm/bill/details`

### 额外 Query Parameters

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 否 | 页码，从 1 起，默认 1 |
| pageSize | int | 否 | 每页条数，默认 50，最大 100 |

### 成功响应

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "apiKeyName": "my-key",
        "apiKeySecret": "sk-xxxx",
        "modelName": "claude-sonnet-4-6",
        "packageUuid": "pkg-xxxx",
        "date": "2026-08-20",
        "hour": "14",
        "usageType": "inputs",
        "usageDetailType": "claude-sonnet-4-6[inputs]",
        "statValue": 12000,
        "unitPrice": 0.003,
        "priceScale": 1000,
        "totalPrice": 0.036,
        "discountValue": 1,
        "currencyScale": 1
      }
    ],
    "total": 128,
    "page": 1,
    "pageSize": 50
  }
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| list | array | 当前页的明细列表 |
| total | int | 时间范围内明细总条数 |
| page | int | 当前页码 |
| pageSize | int | 当前每页条数 |

`list` 单条明细字段：

| 字段名 | 类型 | 说明 |
|--------|------|------|
| apiKeyName | string | API Key 名称 |
| apiKeySecret | string | API Key |
| modelName | string | 模型名称 |
| packageUuid | string | 套餐标识 |
| date | string | 日期（`YYYY-MM-DD`） |
| hour | string | 小时（`00`~`23`） |
| usageType | string | 计费项（如 inputs / outputs / thinkings / cache_reads / cache_writes / multi_modal_images / reqCnt / total_amount） |
| usageDetailType | string | 计费项明细标签 |
| statValue | number | 该计费项的统计量 |
| unitPrice | number | 单价（每计价数量） |
| priceScale | int | 计价数量 |
| totalPrice | number | 该行费用 = statValue × unitPrice ÷ priceScale |
| discountValue | number | 折扣系数 |
| currencyScale | number | 汇率系数 |

---

## 2. 账单汇总接口（全量）

`GET /api/v2/open/llm/bill/summary`

### 成功响应

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [
      {
        "apiKeyName": "my-key",
        "apiKeySecret": "sk-xxxx",
        "modelName": "claude-sonnet-4-6",
        "packageUuid": "pkg-xxxx",
        "reqCnt": 320,
        "inputs": 1200000,
        "thinkings": 45000,
        "outputs": 380000,
        "multiModalImages": 12,
        "cacheReads": 90000,
        "cacheWrites": 30000,
        "totalAmount": 12.85
      }
    ]
  }
}
```

### 响应字段说明

`list` 单条汇总字段：

| 字段名 | 类型 | 说明 |
|--------|------|------|
| apiKeyName | string | API Key 名称 |
| apiKeySecret | string | API Key |
| modelName | string | 模型名称 |
| packageUuid | string | 套餐标识 |
| reqCnt | int | 请求次数 |
| inputs | int | 输入 token 数 |
| thinkings | int | 思考 token 数 |
| outputs | int | 输出 token 数 |
| multiModalImages | int | 多模态图片数 |
| cacheReads | int | 缓存读取 token 数 |
| cacheWrites | int | 缓存写入 token 数 |
| totalAmount | number | 总消费金额 |

---

## 错误响应

```json
{
  "code": 10002,
  "msg": "时间范围过大：最多支持 31 天，请缩小 from/to 跨度",
  "data": null
}
```

```json
{
  "code": 10005,
  "msg": "未授权",
  "data": null
}
```

```json
{
  "code": 90003,
  "msg": "账单取数失败",
  "data": null
}
```

## 请求示例

### cURL

```bash
# 汇总
curl -X GET "https://api.apiverse.ai/api/v2/open/llm/bill/summary?from=2026-08-01&to=2026-08-20" \
  -H "Authorization: Bearer your_api_key_here"

# 明细（分页）
curl -X GET "https://api.apiverse.ai/api/v2/open/llm/bill/details?from=2026-08-01&to=2026-08-20&page=1&pageSize=50" \
  -H "Authorization: Bearer your_api_key_here"
```

### Python

```python
import requests

base = "https://api.apiverse.ai/api/v2/open"
headers = {"Authorization": "Bearer your_api_key_here"}

# 汇总
r = requests.get(f"{base}/llm/bill/summary",
                 params={"from": "2026-08-01", "to": "2026-08-20"},
                 headers=headers)
print(r.json())

# 明细（分页遍历）
page = 1
while True:
    r = requests.get(f"{base}/llm/bill/details",
                     params={"from": "2026-08-01", "to": "2026-08-20",
                             "page": page, "pageSize": 100},
                     headers=headers)
    data = r.json()["data"]
    for row in data["list"]:
        print(row)
    if page * data["pageSize"] >= data["total"]:
        break
    page += 1
```

## 注意事项

1. 账单归属由 API Key 所属账户决定，仅返回本账户名下的大模型消费数据。
2. 明细接口按 `page/pageSize` 分页；`total` 为时间范围内的明细总条数，据此判断是否还有下一页。
3. 时间范围跨度上限为 31 天，超长区间请分段拉取。
4. 汇总接口一次性返回全部聚合行，数据量小，无需分页。
5. 该接口仅在开通大模型（LLM）能力的环境提供；未开通时返回错误提示。

## 错误码说明

| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 10002 | 参数错误（如时间范围过大 / `to` 早于 `from`） | 修正 `from`/`to`，跨度不超过 31 天 |
| 10005 | 未授权 | 检查 API Key 是否正确 |
| 90003 | 账单取数失败 / 账单暂不可用 | 稍后重试或联系技术支持 |