Manage API 参考

本文档基于当前后端代码同步整理，聚焦对外公开的 Manage 侧接口。

基础信息

• Base URL：https://api.xairouter.com
• 认证：Authorization: Bearer sk-Xvs...

export BASE_URL="https://api.xairouter.com"

端点总览

1) 子账户管理（/x-users / /x-dna）

1.1 创建子账户

POST /x-users

最小请求：

{
  "Name": "dev-account",
  "Email": "[email protected]",
  "CreditGranted": 100
}

常用可选字段：

• Alias、BillingEmail
• Rates
• RPM/RPH/RPD、TPM/TPH/TPD
• AllowIPs、AllowModels、AllowLevels
• Resources
• ModelLimits

限流字段语义

• RPM/RPH、TPM/TPH：短窗口限流。
• RPD/TPD：自然日额度，按服务端业务日期切日，不是滚动 24 小时。
• 命中短窗口限流后会进入独立 cooldown；若客户端持续重试，cooldown 会继续刷新。
• 命中 RPD/TPD 后，cooldown 只持续到当天结束；重复重试不会把恢复时间拖到次日以后。
• TPD 按成功请求后的实际 Token 用量累计；若某次成功请求刚好使当日额度超额，通常从下一次请求开始返回 429 TPD。
• ModelLimits 与用户级限流字段语义一致，但统计会归并到最终生效模型，避免模型别名或上游快照名分裂计数。

ModelLimits 示例：

{
  "gpt-5": {
    "RPM": 60,
    "RPH": 1000,
    "RPD": 5000,
    "TPM": 200000,
    "TPH": 2000000,
    "TPD": 10000000
  }
}

1.2 查询子账户与后代

• GET /x-users：直属子账户
• GET /x-dna：全部后代
• GET /x-users/{identifier}、GET /x-dna/{identifier}：路径筛选

查询参数：

• id、name、email、level、dna
• page、size
• order

路径 identifier 支持：

• 数字 ID
• 用户名
• 邮箱
• DNA（. 前缀）
• 前缀过滤：L{n}、G{n}、R{n}、T{n}、F{n}

1.3 更新子账户

PUT /x-users/{identifier} 或 POST /x-users/{identifier}

常用公开字段：

• 基础信息：Name、Email、Alias、BillingEmail、QRCode
• 状态：Status、Suspended
• 额度：CreditGranted、Days、Rates
• 限额：DailyLimit、HardLimit、SoftLimit、UserLimit、AutoQuota
• 速率：RPM/RPH/RPD、TPM/TPH/TPD
• ACL：Resources、AllowIPs、AllowModels、AllowLevels
• 映射/限速：ModelMapper、ModelLimits

Owner 扩展字段：Level、Role、Factor、LevelMapper。

1.4 删除子账户

DELETE /x-users/{identifier}

2) 后代账单（/x-bill）

GET /x-bill

查询参数：

• 日期：date/d
• 范围：start/s、end/e
• 天数：days
• 用户筛选：user/u

3) 自助轮换密钥（/x-self）

POST /x-self

{
  "confirm": "YYYY-MM-DD-ROTATE-SELF",
  "key": "sk-Xvs..."
}

• confirm 必须匹配当天日期规则
• key 可选，不传会自动生成

4) 仪表盘接口（/dashboard/*）

• GET /dashboard/status：权限与状态
• GET /dashboard/info：账户详情
• GET /dashboard/live：实时用量
• GET /dashboard/bill：当前账户账单
• GET /dashboard/logs：操作日志
• GET /dashboard/news：通知
• GET /dashboard/models：模型列表

说明：仅公开业务治理所需字段。后台内部账务订正字段与维护接口不在本页展示范围内。