𝐘𝐀𝐈

用量统计 API

用量统计 API

用量统计 API 提供当前账号的实时与历史用量，以及后代账号的汇总、明细和排行。

export BASE_URL="https://api.xaicontrol.com"
export API_KEY="sk-Xvs..."

接口一览

方法与路径统计范围说明
GET /dashboard/live当前账号当天、当月实时累计
GET /dashboard/bill当前账号按日期统计趋势与模型明细
GET /x-bill后代账号汇总趋势、模型明细与账号排行

所有接口均使用：

Authorization: Bearer sk-Xvs...

当前账号实时用量

curl "$BASE_URL/dashboard/live" \
  -H "Authorization: Bearer $API_KEY"

响应在账号信息之外提供：

字段说明
daily_usage当天实时累计
monthly_usage当月实时累计
Requests请求数
Prompt输入 Token
Completion输出 Token
Reasoning推理 Token
CreditUsed已用额度
ModelUsage按模型拆分的请求、Token 和额度

实时接口适合仪表盘轮询；需要历史趋势时使用 /dashboard/bill。

当前账号历史用量

GET /dashboard/bill
GET /dashboard/bill?date=2026-07-18
GET /dashboard/bill?start=2026-07-01&end=2026-07-18
GET /dashboard/bill?days=7

不传参数时返回当天用量。

参数说明
date指定一天，格式为 YYYY-MM-DD
start / end起止日期，包含边界日期
days最近一段时间
curl "$BASE_URL/dashboard/bill?start=2026-07-01&end=2026-07-18" \
  -H "Authorization: Bearer $API_KEY"

后代账号用量

/x-bill 统计当前账号之下的后代账号，不包含当前账号自身。调用账号需要具备账号管理能力。

GET /x-bill
GET /x-bill?date=2026-07-18
GET /x-bill?start=2026-07-01&end=2026-07-18
GET /x-bill?days=7
GET /x-bill?user=42&days=30

不传日期参数时返回当天用量。user 支持账号 ID、账号名或邮箱；不传时汇总全部后代账号。

curl "$BASE_URL/x-bill?start=2026-07-01&end=2026-07-18" \
  -H "Authorization: Bearer $API_KEY"

汇总响应

/dashboard/bill 和 /x-bill 使用相同的核心统计结构：

字段说明
daily_costs按天排列的用量；line_items 继续按模型拆分
usage_summary整个查询区间的模型汇总
total_requests总请求数
total_prompt总输入 Token
total_completion总输出 Token
total_reasoning总推理 Token
total_credit_used总使用额度
token_summary缓存、非缓存输入及输出 Token 汇总

简化响应示例：

{
  "object": "bill_info",
  "daily_costs": [
    {
      "date": "2026-07-18",
      "total_requests": 24,
      "total_prompt": 18200,
      "total_completion": 3600,
      "total_credit_used": 1.42,
      "line_items": [
        {"name": "gpt-5-nano", "cost": 1.42, "usage": {}}
      ]
    }
  ],
  "usage_summary": {"gpt-5-nano": {}},
  "total_requests": 24,
  "total_prompt": 18200,
  "total_completion": 3600,
  "total_reasoning": 0,
  "total_credit_used": 1.42,
  "token_summary": {
    "input_total": 18200,
    "output_total": 3600,
    "processed_total": 21800
  }
}

后代账号排行

/x-bill 在核心统计之外增加 usage_users，并按使用额度从高到低排列：

字段说明
id、name、alias、email账号标识
top_cost_model额度消耗最高的模型
top_request_model请求数最多的模型
total_requests该账号请求数
total_prompt、total_completion、total_reasoning该账号 Token 用量
total_credit_used该账号使用额度
usage_analysis.request_percentage占后代账号总请求数的百分比
usage_analysis.cost_percentage占后代账号总使用额度的百分比
{
  "usage_users": [
    {
      "id": 42,
      "name": "developer-a",
      "alias": "研发 A",
      "email": "[email protected]",
      "top_cost_model": "gpt-5",
      "top_request_model": "gpt-5-nano",
      "total_requests": 50,
      "total_prompt": 42000,
      "total_completion": 8000,
      "total_reasoning": 0,
      "total_credit_used": 3.52,
      "usage_analysis": {
        "request_percentage": 62.5,
        "cost_percentage": 61.97
      }
    }
  ]
}

没有产生请求的账号不会进入 usage_users。

选择接口

  • 看当前余额及当天、当月实时累计：/dashboard/live
  • 看当前账号某天、某个区间或按模型拆分：/dashboard/bill
  • 看全部后代账号的整体消耗与排行：/x-bill

相关文档

← 访问控制 (ACL)
XAI Control →