账号与用量 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_levels | IP、模型与 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 个自然日| 参数 | 别名 | 说明 |
|---|---|---|
date | d | 单日,优先级最高 |
start | s、start_date | 起始日期 |
end | e、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_reasoning | Token 合计 |
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_summary | input_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_news | root 发布的系统公告 |
user_news | 发给当前账号的个人通知;读取一次后即被清除 |
dna_news | 发给当前账号所在分组(DNA 完全相同的账号,即同一父账号的直接子账号)的通知 |
每条通知为 {title, content, created_at, expires_at, created_by},已过期的不会返回。发布通知见《账号管理 API》。
选择接口
- 当前余额与当日、当月实时累计:
/dashboard/live - 当前账号某天、某个区间或按模型拆分:
/dashboard/bill - 全部后代账号的整体消耗与排行:
/x-bill