# 使用记录API文档

使用接入密钥查询当前账号的消耗、充值、退款和错误记录。本文件可交给 AI 编程助手完成接入。

## 接入准备

- API 站点地址：`https://geekapi.net`，本文中的地址已按下载站点填写。
- 将 `sk-你的令牌` 替换为“接入密钥”页面显示的完整密钥。
- 接口使用站点根路径 `/api/platform/logs`，无需在前面加 `/v1`。
- 无需浏览器登录或 Cookie；密钥必须有效、未过期且未停用。查询不消耗模型额度。
- 数据范围是密钥所属账号的全部记录，包含该账号其他令牌产生的记录，不能指定其他账号。

## 查询记录

```http
GET /api/platform/logs
Authorization: Bearer sk-你的令牌
```

```bash
curl 'https://geekapi.net/api/platform/logs?p=1&page_size=20&type=0' \
  -H 'Authorization: Bearer sk-你的令牌'
```

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `p` | `1` | 页码，从 1 开始，最大 999；超出范围时按边界值处理。 |
| `page_size` | `20` | 每页条数，范围 1–50；超出范围时按边界值处理。 |
| `type` | `0` | `0` 全部、`1` 充值、`2` 消耗、`5` 错误、`6` 退款；其他值按全部处理。 |

按时间倒序返回。根据 `data.total` 和 `data.page_size` 计算总页数，递增 `p` 逐页获取完整明细。

## 返回结构

```json
{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "items": [
      {
        "id": 7,
        "type": 5,
        "line_id": 115,
        "quota": 0,
        "cumulative_quota": 500000,
        "amount": "-",
        "cumulative_amount": "¥7.30",
        "billing_formula": "—",
        "billing": {},
        "endpoint_path": "/v1/chat/completions",
        "request_id": "req_example",
        "content": "请求处理失败，请重试"
      }
    ]
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `data.page`、`data.page_size`、`data.total` | 当前页、每页条数和记录总数。 |
| `data.items` | 当前页记录列表。 |
| `id`、`created_at` | 记录 ID 和 Unix 秒级时间戳。 |
| `type` | 记录类型，数值含义见查询参数。充值为成功，消耗和退款为完成，错误为失败。 |
| `model_name`、`line_id` | 调用模型和线路 ID；未记录线路时可能省略 `line_id`。 |
| `token_name` | 产生记录的令牌名称。 |
| `quota` | 本条记录的原始额度值，含义由 `type` 区分；不要将充值或退款当作消耗。 |
| `cumulative_quota` | 截至该时间的累计消耗额度，与使用记录页面口径一致；暂时无法计算时省略，不代表零。 |
| `amount`、`cumulative_amount` | 可直接展示的消耗金额、累计消耗，包含币种符号或点数单位。零消耗显示 `-`，未知额度显示 `--`。 |
| `billing_formula` | 可直接展示的完整计算公式，使用该次调用的计费快照；缺失或不适用时为 `—`。 |
| `billing` | 计费快照，可能包含单价、倍率、数量、秒数、缓存和补扣/退款信息；历史记录可能为空。 |
| `prompt_tokens`、`completion_tokens` | 输入和输出 Token 数。 |
| `use_time`、`is_stream` | 耗时（秒）和是否为流式请求。 |
| `endpoint_path` | 调用接口路径。 |
| `request_id`、`upstream_request_id` | 请求追踪编号，未记录时可能为空或省略。 |
| `content` | 日志内容，`type=5` 时为完整错误信息；未记录时可能为空。 |

金额和公式直接使用返回的展示字段，不要使用当前模型价格重新计算历史记录。进行数值计算时使用原始额度，不要解析金额文本。

可查询站点显示配置：

```bash
curl 'https://geekapi.net/api/platform/status'
```

配置位于 `data`。`quota_per_unit` 是每美元对应的额度；`quota_display_type=USD` 时金额为 `quota / quota_per_unit`，`CNY` 时再乘以 `price`，`TOKENS` 时直接显示点数，`CUSTOM` 时乘以 `custom_currency_exchange_rate` 并使用 `custom_currency_symbol`。累计消耗使用相同换算。

## 查询错误记录

```bash
curl 'https://geekapi.net/api/platform/logs?p=1&page_size=20&type=5' \
  -H 'Authorization: Bearer sk-你的令牌'
```

逐条读取 `content` 展示错误详情，保留换行。内容为空时显示“暂无错误信息”。

## 请求失败处理

- HTTP `401`：检查密钥是否正确、过期或停用；请求头使用 Bearer 格式。
- HTTP `429`：请求过于频繁，按响应提示等待后重试。
- 其他非 2xx 状态：查询暂不可用，读取响应中的 `message` 并适当重试。
- 失败响应包含 `success: false` 和 `message`；成功时读取 `data.items`，不要把查询失败当作空记录。
- 响应禁止缓存。