账号管理 API

账号管理 API

账号管理接口适用于需要分配独立 API Key、额度或访问限制的服务。可用性由当前账号权限决定；GET /dashboard/status 返回 manage: true 时可以使用本页接口。

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

接口一览

identifier 推荐使用账号 ID，也支持账号名或邮箱。所有查询和修改都限制在当前账号可管理的范围内。

创建账号

POST /x-users

最小请求：

{
  "Email": "[email protected]",
  "CreditGranted": 20
}

Name 可以省略，由系统自动生成。常用字段：

模型限速示例：

{
  "ModelLimits": {
    "gpt-5*": {
      "rpm": 60,
      "rph": 1000,
      "rpd": 5000,
      "tpm": 200000,
      "tph": 2000000,
      "tpd": 10000000
    }
  }
}

RPD 和 TPD 按服务端业务日期切换，不是滚动 24 小时窗口。

查询账号

curl "$BASE_URL/x-users?page=1&size=20" \
  -H "Authorization: Bearer $API_KEY"

支持的常用查询参数：

分页信息通过响应头返回：

X-Total-Count
X-Total-Pages
X-Page
X-Per-Page

/x-users 只返回直属账号；需要查询全部下级账号时使用 /x-dna。

更新账号

PUT /x-users/{identifier}

curl -X PUT "$BASE_URL/x-users/42" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "CreditGranted": 10,
    "RPM": 120,
    "TPD": 5000000,
    "AllowModels": "gpt-5*"
  }'

正数 CreditGranted 增加额度，负数扣减额度。更新额度时可以同时传入 Days 指定新增额度的有效天数。其他可更新字段与创建字段基本一致；权限不能超过当前账号自身的可用范围。

AllowIPs、AllowModels 和 Resources 在更新时使用逗号分隔字符串；模型白名单支持通配符。例如：

{
  "AllowIPs": "203.0.113.10,203.0.113.11",
  "AllowModels": "gpt-5*,text-embedding-*",
  "Resources": "/v1/chat/completions,/v1/responses"
}

删除账号

curl -X DELETE "$BASE_URL/x-users/42" \
  -H "Authorization: Bearer $API_KEY"

删除前应确认账号不再被使用。成功删除后，该账号 API Key 立即失效，剩余额度按服务端规则退回。

批量调整额度

POST /x-users/batch-credit

{
  "IDs": [42, 43, 44],
  "CreditGranted": 10,
  "Days": 30,
  "DryRun": true
}

• CreditGranted 必须是非零数；正数增加、负数扣减。
• 建议先使用 DryRun: true 预览，再以 false 正式执行。
• 响应逐项给出 applied 或 skipped 状态，并汇总父账号和下级账号的额度变化。

后代账号用量统计

/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 相同的整体统计字段，并增加 usage_users：

每个 usage_users 项包含：

简化响应示例：

{
  "object": "bill_info",
  "daily_costs": [
    {"date": "2026-07-18", "total_requests": 80, "total_credit_used": 5.68}
  ],
  "usage_summary": {"gpt-5": {}},
  "total_requests": 80,
  "total_prompt": 64000,
  "total_completion": 12000,
  "total_credit_used": 5.68,
  "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。

轮换当前 API Key

POST /x-self

{
  "confirm": "2026-07-18-ROTATE-SELF"
}

confirm 中的日期必须是服务端当天日期。成功后响应只显示一次新 Key，旧 Key 立即失效；请先准备好安全的更新流程。

相关文档

• Router API
• Provider Key API