用量 — U-Token 通用币 Docs

鉴权

这些端点供服务端调用。使用 Authorization: Bearer <API_KEY> 或 x-api-key 鉴权。请把 Key 保存在自己的后端。

一把 Key 可以查看账户用量，不限于它自己发出的调用。同一买家的多把 Key 共用一个钱包，对账通常用 scope=account。scope=key 只看当前这把 Key。按 request_id 回查始终是账户级：同一买家另一把 Key 产生的请求也能查到。

一行代表什么

这里只有已经计费的调用。被拒绝、被限流，或在计费前中断的调用没有行。结算是异步的：LLM 用量通常在数秒内出现，媒体任务在任务完成后出现。查不到表示这次没有计费，或结算还没完成。不要用这个接口统计失败率。

charge 是这笔调用记到账户上的消费，单位是 credits。official_price 是该笔的牌价合计；没有存牌价的历史行返回 null。

kind 由请求 id 推断。媒体任务 id 以 tsk 开头（kind 为 media），LLM 调用以 aitk- 开头（kind 为 llm）。kind 是开放取值：不认识的过滤值不会匹配任何行，响应里不认识的值应跳过。媒体行的 request_id 就是任务 id，可直接用于 GET /v1/media/tasks/{id}。按 token 计费的媒体会填写 tokens，按次计费的各项为 0。

对账主键是 request_id（原调用响应头 x-aitoken-request-id，或媒体任务 id）。

金额是保留 6 位小数的十进制字符串。token 是整数。时间是 UTC ISO 8601。to 不包含在窗口内。

明细

GET/v1/account/usage

返回当前 Key 或整个账户的已计费记录，新的在前。

curl "https://u-token.ai/v1/account/usage?scope=account&from=2026-09-22T00:00:00Z&to=2026-09-23T00:00:00Z&limit=2" \
  -H "Authorization: Bearer sk-你的KEY"

名称	位置	必填	说明
`scope`	query	否	`key`（默认）或 `account`。其它取值返回 `400`。
`from`	query	否	窗口起点，ISO 8601 或 unix 秒。默认是 `to` 往前 24 小时。
`to`	query	否	窗口终点，不包含该时刻。ISO 8601 或 unix 秒。默认是当前时间。
`model`	query	否	精确模型 ID。
`channel`	query	否	精确渠道 ID，`standard` 或 `flex`。
`kind`	query	否	精确种类。`llm` 与 `media` 匹配对应行，其它值匹配不到行。
`limit`	query	否	每页条数，1–500 的整数。默认 100。
`cursor`	query	否	上一页返回的 `next_cursor`。

from 必须早于 to，窗口最长 31 天。

{
  "scope": "account",
  "from": "2026-09-22T00:00:00Z",
  "to": "2026-09-23T00:00:00Z",
  "currency": "credits",
  "credits_per_usd": "100",
  "data": [
    {
      "request_id": "aitk-3f2c",
      "kind": "llm",
      "model": "claude-sonnet-5",
      "channel": "flex",
      "channel_name": "订阅号直供",
      "tokens": {
        "input": 1834,
        "output": 412,
        "cached": 1200,
        "cache_write": 0,
        "cache_write_1h": 0
      },
      "charge": "0.263400",
      "official_price": "0.752571",
      "status": 200,
      "key": { "id": 1042, "name": "prod-us", "key_masked": "sk-abcd…9f3c" },
      "created_at": "2026-09-22T13:05:41Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0wOS0yMlQxMjo1ODowM1oiLCJpIjo3MTIzNDV9"
}

scope=account 包含已删除或已停用 Key 的历史行。每行都带 key.id、key.name 和 key.key_masked。

游标翻页

结果按 created_at 倒序，相同时按 id 倒序。把 next_cursor 作为 cursor 传入即可翻到下一页。没有更多行时 next_cursor 为 null。不要使用 offset：游标锚在某一行上，翻页期间新落入的更晚记录不会把后面的页挤偏。

curl "https://u-token.ai/v1/account/usage?scope=account&cursor=eyJ0IjoiMjAyNi0wOS0yMlQxMjo1ODowM1oiLCJpIjo3MTIzNDV9" \
  -H "Authorization: Bearer sk-你的KEY"

篡改过的游标返回 400。

汇总

GET/v1/account/usage/summary

与明细使用同一窗口和过滤条件，对同一批已计费记录做汇总。

curl "https://u-token.ai/v1/account/usage/summary?scope=account&from=2026-09-22T00:00:00Z&to=2026-09-23T00:00:00Z&group_by=model" \
  -H "Authorization: Bearer sk-你的KEY"

名称	位置	必填	说明
`scope`	query	否	与明细相同。默认 `key`。
`from`	query	否	时间窗规则与明细相同。
`to`	query	否	时间窗规则与明细相同。
`model`	query	否	精确模型 ID。
`channel`	query	否	精确渠道 ID。
`kind`	query	否	精确种类。不认识的值匹配不到行。
`group_by`	query	否	`day`（默认）、`model` 或 `key`。其它取值返回 `400`。

day 按 UTC 日期分桶（YYYY-MM-DD），没有调用的日期不出现。model 按 (model, channel) 分桶。key 分桶带 key。scope=key 时只有当前这把 Key 的一个桶。total 是整个窗口的合计，不是单个桶。把明细翻完求和后，calls、各项 token 和 charge 应与 total 一致。

{
  "scope": "account",
  "from": "2026-09-22T00:00:00Z",
  "to": "2026-09-23T00:00:00Z",
  "group_by": "model",
  "currency": "credits",
  "credits_per_usd": "100",
  "data": [
    {
      "model": "claude-sonnet-5",
      "channel": "flex",
      "calls": 1830,
      "tokens": {
        "input": 3120044,
        "output": 611203,
        "cached": 1988000,
        "cache_write": 0,
        "cache_write_1h": 0
      },
      "charge": "482.113200"
    }
  ],
  "total": {
    "calls": 2011,
    "tokens": {
      "input": 3200000,
      "output": 640000,
      "cached": 1988000,
      "cache_write": 0,
      "cache_write_1h": 0
    },
    "charge": "540.220100"
  }
}

按请求查

GET/v1/account/usage/{request_id}

返回当前买家账户下的一行。响应体与明细里的单个对象相同。

名称	位置	必填	说明
`request_id`	path	是	原调用的 `x-aitoken-request-id`，或媒体任务 id。

curl https://u-token.ai/v1/account/usage/aitk-3f2c \
  -H "Authorization: Bearer sk-你的KEY"

404 表示这个账户下没有该 id 的已计费行。未知 id、其他买家的 id，以及结算尚未完成，都是这个结果。刚产生的调用请稍后重试，再判断它是否不存在。响应不会区分这几种情况。

错误

每个响应都带 x-aitoken-request-id。这些端点不走 LLM 账户限流。三个用量接口共用每把 Key 每分钟 120 次的额度。超出后返回 429，并带 draft-6 的 RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset。参见速率限制。

HTTP 状态	`error.type`	`error.code`	含义
`400`	`invalid_request_error`	`VALIDATION`	`scope`、时间窗、过滤、`limit`、`group_by` 或游标不合法。超过 31 天时错误说明里会写明上限。
`401`	`authentication_error`		Key 缺失、无效或已停用。响应体与 `GET /v1/models` 一致。
`404`	`not_found`	`usage_not_found`	本账户没有这笔已计费记录，也可能是尚未结算。
`429`	`rate_limit_error`	`usage_rate_limit`	这把 Key 在当前这一分钟里的用量查询超过 120 次。按 `RateLimit-*` 退避。
`503`	`internal_error`	`usage_unavailable`	用量读取失败。响应体包含 `error.request_id`。空的 `data` 数组不是读取失败。

鉴权

一行代表什么

明细

游标翻页

汇总

按请求查

错误

On this page