账号与用量 API

账号与用量 API

export XSI_BASE_URL="https://api.xsicontrol.com"   # 或你自己的 API 域名
export XSI_API_KEY="sk-Xvs..."

接口一览

方法与路径范围权限说明
GET /dashboard/status当前账号任意账号身份、余额与能力标记
GET /dashboard/info当前账号任意账号配置、限额与额度明细
GET /dashboard/live当前账号任意账号info 加当日、当月实时用量
GET /dashboard/bill当前账号任意账号按日期统计的账单与模型明细
GET /dashboard/logs当前账号的管理操作管理者操作日志
GET /dashboard/news当前账号任意账号系统、分组与个人通知
GET /x-bill后代账号管理者汇总账单与账号排行
  • /dashboard/* 走模型调用同一入口,接受 Authorization、x-api-key 或 x-goog-api-key;/x-bill 只接受 Authorization。
  • 账号因余额不足被冻结、或超出日/月额度时,GET /dashboard/* 仍然可用,便于查看原因。
  • 另有 GET /dashboard/models(与 /v1/models 相同的模型目录,但冻结或超额时仍可访问)。其他 /dashboard/* 路径返回 404;/dashboard/* 没有 /v1 写法。

账号状态

curl "$XSI_BASE_URL/dashboard/status" -H "Authorization: Bearer $XSI_API_KEY"
字段说明
object固定为 user_status
id、name、alias、email、dna账号标识与在账号树中的谱系路径
public_key公开标识(pk-Xvs...),用于推荐注册等场景
balance当前可用余额(CNY)
role、factor计费档位与价格系数
manage是否具备管理者权限(可管理子账号)
owner是否为租户所有者
plan_follows_parent套餐与价格是否跟随父账号
suspended是否因余额不足被冻结
user_api_balance管理者权限所需的最低余额
user_min_balance冻结阈值(低于此余额将暂停调用)
support_qr_url支持二维码地址(可能省略)

账号信息

curl "$XSI_BASE_URL/dashboard/info" -H "Authorization: Bearer $XSI_API_KEY"

object 为 user_info,主要字段:

字段说明
id、name、alias、email、billing_email、dna账号标识
level、tier、role、factor路由分组、等级、计费档位与价格系数
balance可用余额
credit_used累计已用额度
credit_balance额度明细数组,元素为 {amount, balance, reference, granted_at, expires_at};每笔额度有独立的有效期
daily_limit、hard_limit、soft_limit日额度、月额度(超出即拒绝)、月度参考值(不参与准入)
rpm、rph、rpd、tpm、tph、tpd账号级请求数与 Token 限速;999999999999999999 表示不限
user_limit、user_n可创建的子账号上限与已创建数量
requests累计请求数
resources资源(路径)白名单,为空表示不限
allow_ips、allow_models、allow_levelsIP、模型与 Level 白名单(为空时省略)
model_limits模型级限额 {model: {rpm, rph, rpd, tpm, tph, tpd}}
model_mapper、level_mapper账号级映射(包含运行时解析缓存)
create_at创建时间(字段名如此)

实时用量

curl "$XSI_BASE_URL/dashboard/live" -H "Authorization: Bearer $XSI_API_KEY"

在 /dashboard/info 的全部字段之外(object 为 user_live),增加 daily_usage 与 monthly_usage。这两个对象的字段名为 PascalCase:

字段说明
Requests请求数
Prompt、Completion、Reasoning输入、输出、推理 Token
CreditUsed已用额度(CNY)
Find、PageN、QueryN文件检索次数、页数、搜索/工具调用次数
ImageN、ImageCost、SizeHigh、SizeMedium、SizeLow图片数量、费用与尺寸档位分布
CachedDetails、PromptDetails、CompletionDetails缓存与模态明细
ModelUsage按模型名拆分的同结构对象

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

历史账单

GET /dashboard/bill                                   # 今天
GET /dashboard/bill?date=2026-11-18                   # 指定一天
GET /dashboard/bill?start=2026-11-01&end=2026-11-18   # 区间(含两端)
GET /dashboard/bill?days=7                            # 今天及之前 7 天,共 8 个自然日
参数别名说明
dated单日,优先级最高
starts、start_date起始日期
ende、end_date结束日期,默认今天
days—向前追溯的天数
  • 日期格式错误返回 400 Invalid date format. Please use YYYY-MM-DD format。
  • 查询跨度超过 30 天按一次 XAPI_FEE 计费;超过 3 年时起点截断为 3 年前,并额外计费 5 次。

响应结构

/dashboard/bill 与 /x-bill 共用以下结构(object 为 bill_info):

字段说明
daily_costs[]按日期升序:timestamp、date、line_items[]({name, cost, usage},按模型拆分)、当日 total_*、usage_analysis、token_summary
usage_summary整个区间按模型汇总,值为 {model_stats, usage_analysis, token_summary}
total_requests、total_credit_used请求数与费用合计
total_prompt、total_completion、total_reasoningToken 合计
total_find、total_page_n、total_query_n文件检索、页数、搜索与工具调用合计
total_image_n、total_size_high、total_size_medium、total_size_low图片合计
total_cached_details、total_prompt_details、total_completion_details明细合计(可能省略)
token_summaryinput_total、input_uncached、cache_read、cache_write、cache_related、output_total、reasoning_output、processed_total
{
  "object": "bill_info",
  "daily_costs": [
    {
      "timestamp": 1763395200,
      "date": "2026-11-18",
      "total_requests": 24,
      "total_prompt": 18200,
      "total_completion": 3600,
      "total_credit_used": 1.42,
      "line_items": [{"name": "gpt-6.2-sol", "cost": 1.42, "usage": {}}]
    }
  ],
  "usage_summary": {"gpt-6.2-sol": {}},
  "total_requests": 24,
  "total_prompt": 18200,
  "total_completion": 3600,
  "total_reasoning": 0,
  "total_credit_used": 1.42,
  "token_summary": {"input_total": 18200, "cache_read": 6400, "output_total": 3600, "processed_total": 21800}
}

管理调用费以模型名 XAPI 出现在账单中。

后代账号用量

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

统计当前账号之下全部后代账号,不包含当前账号本身。需要管理者权限,本身不收取管理调用费。

参数说明
date/d、start/s/start_date、end/e/end_date、days同 /dashboard/bill
user/u过滤后代:数字 ID、账号名、邮箱(含 @)、DNA 前缀(以 . 开头),或 L<n>/G<n>/R<n>/T<n>/F<x>(按 Level、Gear、Role、Tier、Factor)。不属于后代或无匹配时返回 404 User not found

跨度超过 3 年时截断为 36 个月;后代账号超过 8192 个时只统计前 8192 个。

在共用结构之外,/x-bill 增加 usage_users,只包含区间内有请求的账号,按费用从高到低排序:

字段说明
id、name、alias、email账号标识
top_cost_model、top_request_model费用最高、请求最多的模型
total_*、token_summary该账号的各项合计
usage_analysis.request_percentage、usage_analysis.cost_percentage占全部后代的请求与费用百分比(两位小数)

操作日志

GET /dashboard/logs?page=1&size=24

需要管理者权限。

参数说明
page页码,从 1 开始
size每页条数,1–100,默认 24

响应为 {logs, total, page, size, has_more}。每条日志包含 id、timestamp、pid、parent_name、action、user_id、user_name、details、ip、user_agent。

action 取值:add_user、update_user、delete_user、get_users、add_key、update_key、delete_key、sleep_key、wake_key、create_news、rotate_self、auto_config。每个账号保留最近 10 条操作日志;删除账号等敏感操作另行留存。

通知

curl "$XSI_BASE_URL/dashboard/news" -H "Authorization: Bearer $XSI_API_KEY"
{"sys_news": [], "user_news": [], "dna_news": []}
字段来源
sys_newsroot 发布的系统公告
user_news发给当前账号的个人通知;读取一次后即被清除
dna_news发给当前账号所在分组(DNA 完全相同的账号,即同一父账号的直接子账号)的通知

每条通知为 {title, content, created_at, expires_at, created_by},已过期的不会返回。发布通知见《账号管理 API》。

选择接口

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

相关文档