StoneRoll AI 平台文档

Appearance

令牌模型用量查询 ​

按令牌（KEY）维度查询该令牌在指定时间窗口内、按模型聚合的用量，供外部对账系统定时拉取：

  • 每个模型的请求数量
  • 每个模型的总输入 / 输出 token
  • 每个模型的缓存命中 token（读 / 写，v3 新增）
  • 每个模型的输入合计 token（含缓存，跨协议归一口径，v3 新增）
  • 每个模型的消费额度（quota）与退款额度（金额对账用）

调用方持被查令牌本身调用（key 即接口鉴权凭证）。

接口定义 ​

text
GET /api/log/token/usage
Authorization: Bearer <你的令牌 key>
  • 与模型调用使用同一 key、同一 Authorization 头格式（sk- 前缀可带可不带）
  • 该接口只读，不产生用量、不扣费

请求示例（curl） ​

查询固定窗口（2026-08-25 00:00:00 ~ 01:00:00，东八区）：

bash
curl -s -G "https://stonerollai.com/api/log/token/usage" \
  --data-urlencode "start=2026-08-25 00:00:00" \
  --data-urlencode "end=2026-08-25 01:00:00" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx"

定时增量拉取（最近 1 小时，Linux）：

bash
END=$(date '+%Y-%m-%d %H:%M:%S')
START=$(date -d '-1 hour' '+%Y-%m-%d %H:%M:%S')
curl -s -G "https://stonerollai.com/api/log/token/usage" \
  --data-urlencode "start=${START}" \
  --data-urlencode "end=${END}" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx"

macOS / BSD 的 date 用法：date -v-1H '+%Y-%m-%d %H:%M:%S'。 参数值含空格，示例使用 --data-urlencode 自动编码；手工拼 URL 时空格需写成 %20。

请求参数（Query） ​

参数类型必填说明
startstring是窗口起点，格式 YYYY-MM-DD HH:MM:SS（东八区），包含
endstring是窗口终点，格式同上，不包含
  • 两个参数均必填
  • 窗口为左闭右开 [start, end)：end 时刻的数据归属下一窗口，定时增量拉取不重不漏
  • 单次查询跨度最长 7 天，超出返回提示
  • 查询前服务端会预估命中行数，超过 200,000 行时拒绝执行并提示缩小窗口（响应 message 携带实际预估行数）

响应 ​

HTTP 200，标准信封：

json
{
  "success": true,
  "message": "",
  "data": {
    "token": {
      "token_id": 74,
      "token_name": "reconciliation-key-01",
      "user_id": 37
    },
    "start_timestamp": 1787587200,
    "end_timestamp": 1787590800,
    "models": [
      {
        "model_name": "kimi-k3",
        "request_count": 1579,
        "prompt_tokens": 1234567,
        "cache_tokens": 234567,
        "cache_creation_tokens": 12345,
        "input_tokens_total": 1481479,
        "completion_tokens": 234567,
        "quota": 9876543,
        "refund_count": 2,
        "refund_quota": 1234
      },
      {
        "model_name": "glm-5.2",
        "request_count": 633,
        "prompt_tokens": 234567,
        "cache_tokens": 34567,
        "cache_creation_tokens": 0,
        "input_tokens_total": 234567,
        "completion_tokens": 34567,
        "quota": 4567890,
        "refund_count": 0,
        "refund_quota": 0
      }
    ],
    "summary": {
      "request_count": 2212,
      "prompt_tokens": 1469134,
      "cache_tokens": 269134,
      "cache_creation_tokens": 12345,
      "input_tokens_total": 1716046,
      "completion_tokens": 269134,
      "quota": 14444433,
      "refund_count": 2,
      "refund_quota": 1234
    }
  }
}

字段说明：

字段说明
data.token令牌核对信息（token_id / token_name / user_id），供外部系统落库比对
data.start_timestamp / end_timestamp实际生效的窗口（unix 秒），与请求的 start / end（东八区）一一对应
models[].model_name模型名；空字符串 "" 表示无模型名的日志条目（一并纳入以保证总量平衡）
models[].request_count该模型计费成功的请求数
models[].prompt_tokens / completion_tokens该模型总输入 / 输出 token（prompt 口径见下方「输入 token 口径」）
models[].cache_tokens该模型缓存命中（读） token 合计（v3 新增）
models[].cache_creation_tokens该模型缓存写 token 合计（无缓存写的模型为 0；v3 新增）
models[].input_tokens_total输入合计（含缓存读 + 缓存写，跨协议归一口径），对账输入总量以此为准（v3 新增）
models[].quota该模型消费额度（正数）
models[].refund_count / refund_quota该模型退款条数与退款额度（正数，为冲抵额）
models 排序按 request_count 降序
summary全模型合计（校验和用）

净消耗 = quota − refund_quota（按模型或用 summary 均可）。

输入 token 口径（v3 起提供归一字段） ​

prompt_tokens 的语义随通道协议而不同（平台按协议原样落库，不改历史数据）：

通道协议prompt_tokens 含义缓存位置
OpenAI 兼容 / Gemini 等已含缓存命中（缓存是其子集）cache_tokens
Claude 协议（Anthropic 语义）不含缓存（净输入）读在 cache_tokens，写在 cache_creation_tokens

因此不同来源的 prompt_tokens 直接相加没有一致口径。跨协议对账请使用归一字段：

text
input_tokens_total = anthropic 语义行：prompt_tokens + cache_tokens + cache_creation_tokens
                     其余语义行：    prompt_tokens（已含缓存，不重复加）
  • 同一模型混走两种协议时，input_tokens_total 已按行归一后求和，可直接对账
  • 需要净输入（不含缓存）时：净输入 ≈ input_tokens_total − cache_tokens − cache_creation_tokens（仅 anthropic 语义行严格成立；OpenAI 语义行的 prompt 本就含缓存，减出的是净输入下界）
  • 金额（quota）计费不受此影响：平台计费已按协议归一，v3 前后金额口径不变

错误 ​

HTTPsuccess场景
200false参数问题：缺 start / end、格式错误、start ≥ end、跨度超过 7 天、命中行数超过 200,000；message 说明原因
401false未提供令牌 / 令牌无效 / 令牌已被禁用
403false令牌所属用户被禁用
429false触发限流
500false数据库错误

注意：过期、额度耗尽的令牌仍可查询（对账需要历史可查）；只有显式禁用（或所属用户被禁）才拒绝。

频率建议 ​

  • 接口启用限流保护，超频返回 429
  • 对账定时任务建议：间隔 ≥ 1 秒、按小时窗口增量拉取
  • 窗口衔接：本轮 end = 下轮 start，正好接上左闭右开约定

额度（quota）换算 ​

quota 为平台统一计费单位，换算美元：

text
USD = quota / quota_per_unit

quota_per_unit 公开可查：GET /api/status → data.quota_per_unit（默认 500000）。建议每次任务开始时取一次并随结果落库。

变更约定与记录 ​

  • 响应字段只增不改不删；新增字段视为兼容变更
  • 聚合口径变更会同步更新本文档并标注版本
  • 接口无分页：单令牌使用的模型数量有限，全量返回
  • 需要按行的明细数据时，使用日志明细导出（含同口径的 缓存读 / 缓存写 / 输入合计 列）
版本日期变更
v32026-09-01行级与 summary 新增 cache_tokens / cache_creation_tokens / input_tokens_total（跨协议输入归一口径，见「输入 token 口径」）；既有字段含义不变
v22026-08-25start / end 改为必填日期字符串（YYYY-MM-DD HH:MM:SS，东八区）；新增跨度 ≤ 7 天与单次 200,000 行保护
v12026-08-25首次发布

StoneRoll AI · 平台文档