Manage API 参考

本文档按当前后端代码同步整理。

基础信息

• 启动模式域名：
  • SaaS 单租户：https://api.xairouter.com
  • BYOK 多租户：https://api.xaicontrol.com
• 文中示例统一使用 $BASE_URL，先按模式设置：

export BASE_URL="https://api.xairouter.com"      # SaaS
# export BASE_URL="https://api.xaicontrol.com"   # BYOK

• 认证：Authorization: Bearer sk-Xvs...
• Manage 权限判定与 GET /dashboard/status 的 manage 字段一致（余额、配额、账户状态等条件）

端点总览

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

代码行为要点：

• Name/Email 必须合法且唯一。
• CreditGranted 会按系统阈值校正（存在最小值/上限逻辑）。
• 子账户会继承父账户大量默认配置（ACL、限速、映射等）。

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}

响应体为数组，分页信息放在 Header： X-Total-Count、X-Page、X-Per-Page、X-Total-Pages。

1.3 更新子账户

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

当前代码中更新标识符按「ID 或用户名」解析。

常用字段：

• 基础信息：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}（ID 或用户名）

返回示例：

{
  "Action": "delete",
  "User": {
    "ID": 42,
    "Name": "dev-account",
    "Email": "[email protected]",
    "Rates": 1,
    "CreditBalance": []
  }
}

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

GET /x-bill

查询参数：

• 日期：date/d
• 范围：start/s、end/e（也支持 start_date、end_date）
• 天数：days
• 用户筛选：user/u（ID、用户名、邮箱、DNA、或 L/G/R/T/F 前缀）

返回是 bill_info 结构 + usage_users（后代用户汇总）。

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

POST /x-self

请求体：

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

说明：

• confirm 必须是当天日期拼接固定短语。
• key 可选；不传或不合法会自动生成新 key。

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

4.1 状态

GET /dashboard/status

关键字段：

• manage：是否允许 Manage 操作
• admin：是否 Owner
• user_api_balance、user_min_balance
• suspended

4.2 详情

GET /dashboard/info

返回扁平结构 user_info，包含：

• 余额：balance、credit_balance
• 限额：daily_limit、hard_limit、soft_limit
• 速率：rpm/rph/rpd/tpm/tph/tpd
• ACL：resources、allow_ips、allow_models、allow_levels
• 映射：model_mapper、level_mapper、model_limits

4.3 实时详情

GET /dashboard/live

在 /dashboard/info 基础上增加：

• daily_usage
• monthly_usage

4.4 当前账户账单

GET /dashboard/bill

参数与 /x-bill 的日期参数一致（date/start/end/days）。

返回 bill_info 结构，核心字段：

• daily_costs
• usage_summary
• total_credit_used
• total_requests

4.5 操作日志

GET /dashboard/logs

查询参数：

• page（默认 1）
• size（默认 24，最大 100）
• action、target_id、status

返回：

{
  "logs": [],
  "total": 0,
  "page": 1,
  "size": 24,
  "has_more": false
}

4.6 通知

GET /dashboard/news

字段名与代码一致：

• sys_news
• user_news
• dna_news

4.7 模型列表

GET /dashboard/models（等价别名：/v1/models、/models）

返回 OpenAI 风格：

{
  "object": "list",
  "data": [
    {"id":"gpt-4o","object":"model","owned_by":"xai"}
  ]
}

5) 常见错误码

• 401 Unauthorized：API Key 无效或缺失
• 403 Forbidden：无 Manage 权限或越权操作
• 404 Not Found：用户不存在
• 400 Bad Request：参数/字段格式错误

相关文档

• Admin API 参考
• Router 接口
• Manage Console 使用指南