# NianFeng 用量查询 API · 接口文档

**版本** v1 · **Base URL** `https://api.nianfeng.tech` · **格式** JSON(UTF-8)· **属性** 只读

面向 AI Agent(飞书机器人等)与自动化程序的只读用量查询接口。调用方以**账号访问令牌**认证,仅能查询该账号自身名下所有 API Key 的用量,无法访问其他账号数据。

---

## 快速开始

```
curl "https://api.nianfeng.tech/report/usage?range=yesterday&by=model" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

---

## 认证

除文档与健康检查外,所有请求必须携带请求头:

```
Authorization: Bearer <ACCESS_TOKEN>
```

| 项 | 说明 |
|---|---|
| 令牌类型 | 账号访问令牌(Access Token) |
| 获取方式 | 控制台 → 个人设置(`/profile`)→「访问令牌」→ 生成 |
| 权限范围 | 只读;仅限该令牌所属账号自身的用量数据 |
| 注意 | 不是 `sk-` 开头的模型调用密钥;令牌重新生成后旧值立即失效 |

---

## 端点总览

| 方法 | 路径 | 认证 | 说明 |
|---|---|---|---|
| GET | `/report/usage` | 必须 | 查询账号用量汇总 |
| GET | `/report` | 无需 | 返回本文档(Markdown) |
| GET | `/report/health` | 无需 | 存活探测,返回 `{"ok": true}` |

---

## GET /report/usage

查询当前账号在指定时间段内的消费汇总,按指定维度聚合,结果按金额降序排列。

### 查询参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `range` | string | 否 | `today` | 预设时间段:`today` 今天 / `yesterday` 昨天 / `7d` 近 7 天 / `30d` 近 30 天 / `mtd` 本月至今 |
| `start` | string | 否 | — | 自定义起始时间,`YYYY-MM-DD` 或 Unix 秒。提供 `start`/`end` 时忽略 `range` |
| `end` | string | 否 | 当前时刻 | 自定义结束时间,`YYYY-MM-DD`(**含当天**)或 Unix 秒 |
| `by` | string | 否 | `model` | 聚合维度:`model` 按模型 / `token` 按 API Key / `token_model` 按 Key × 模型 |

- 时区:日期均按东八区(UTC+8)解析与返回。
- 非法参数值不报错,回退默认(`range`→`today`,`by`→`model`)。

### 响应字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `account` | string | 账号用户名 |
| `by` | string | 实际生效的聚合维度 |
| `currency` | string | 固定 `USD` |
| `range.label` | string | 时间段标签(`today`/`yesterday`/`7d`/`30d`/`mtd`/`custom`) |
| `range.start` / `range.end` | int | 起止时间,Unix 秒 |
| `range.start_time` / `range.end_time` | string | 起止时间,`YYYY-MM-DD HH:MM`(UTC+8) |
| `total.usd` | number | 时段总消费(美元) |
| `total.requests` | int | 总请求数 |
| `total.prompt_tokens` | int | 输入 token 总量 |
| `total.completion_tokens` | int | 输出 token 总量 |
| `items[]` | array | 聚合明细,按 `usd` 降序 |
| `items[].model` | string | 模型名。`by=model` 或 `token_model` 时返回 |
| `items[].token` | string | API Key 名称。`by=token` 或 `token_model` 时返回;未命名 Key 显示 `(default)` |
| `items[].usd` | number | 该项消费(美元) |
| `items[].requests` | int | 该项请求数 |
| `items[].prompt_tokens` / `items[].completion_tokens` | int | 该项输入 / 输出 token |

### 请求示例

```
GET /report/usage?range=yesterday&by=model        # 昨天,按模型
GET /report/usage?range=mtd&by=token              # 本月至今,按 Key
GET /report/usage?start=2026-08-01&end=2026-08-27&by=token_model
```

### 响应示例(200)

```json
{
  "account": "lijin",
  "by": "model",
  "currency": "USD",
  "range": {
    "label": "yesterday",
    "start": 1787760000,
    "end": 1787846400,
    "start_time": "2026-08-27 00:00",
    "end_time": "2026-08-28 00:00"
  },
  "total": { "usd": 12.34, "requests": 42, "prompt_tokens": 51200, "completion_tokens": 8300 },
  "items": [
    { "model": "claude-opus-5", "usd": 8.02, "requests": 20, "prompt_tokens": 30100, "completion_tokens": 5100 },
    { "model": "gpt-5.5",       "usd": 4.32, "requests": 22, "prompt_tokens": 21100, "completion_tokens": 3200 }
  ]
}
```

时段内无消费时 `total` 各项为 0,`items` 为空数组。

---

## 错误

出错时返回 JSON:`{"error": "<描述>"}`

| HTTP 状态码 | 含义 | 处理建议 |
|---|---|---|
| 401 | 缺少或无效的访问令牌 | 检查 `Authorization: Bearer` 头;确认使用账号访问令牌而非 `sk-` 调用密钥;令牌重新生成后旧值失效 |
| 404 | 路径不存在 | 检查请求路径 |
| 502 | 服务端查询失败 | 稍后重试,持续出现请联系管理员 |

---

## 说明与限制

- 数据实时:统计基于网关计费日志,请求完成即可查到。
- 金额为网关计费口径,单位美元。
- 本接口为只读查询,不产生模型调用,不消耗账号额度。
- 访问令牌等同账号身份凭证,请妥善保管,不要提交到公开仓库。