账号管理 API

账号管理 API

XSI 的账号组织为一棵树:每个账号都有父账号(PID)、所属租户(OID)和谱系路径(DNA)。管理接口只能作用于调用者自己的子树。概念说明见《账号体系》。

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

接口一览

方法与路径权限说明
POST /x-users管理者,且有剩余子账号名额创建直属子账号
GET /x-users、GET /x-users/{identifier}管理者查询直属子账号
GET /x-dna、GET /x-dna/{identifier}管理者查询全部后代账号
PUT /x-users/{identifier}(或 POST)管理者;本人可更新部分资料更新账号
POST /x-users/batch-credit管理者批量发放或扣回额度
DELETE /x-users/{identifier}管理者删除后代账号
POST /x-self任意账号轮换本人 API Key
POST /x-news、POST /x-news/{target}root / 管理者发布通知
DELETE /x-news、DELETE /x-news/{target}root / 管理者删除通知

管理者:root;或同时满足 TPD > 800000000、具备子账号能力(UserLimit > 0 或已有子账号)、余额高于 USER_API_BALANCE(默认 100)。不满足时返回 403,正文说明缺少哪一项,例如 Management access requires balance above 100.00.。GET /dashboard/status 的 manage 字段可用于预先判断。

字段名:请求体使用 PascalCase 字段名(如 CreditGranted、AllowModels)。更新接口对未知字段返回 400 Unknown field: X;多数已知字段在大小写或类型不正确时会被静默忽略(CreditGranted 与 DryRun 例外,会返回 400),请严格按本页书写。

创建子账号

curl -X POST "$XSI_BASE_URL/x-users" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Email": "[email protected]",
    "Name": "dev-a",
    "Alias": "研发 A",
    "CreditGranted": 200,
    "RPM": 60,
    "TPM": 200000
  }'
字段必填说明
Email是登录与通知邮箱,全局唯一,≤ 128 字节
Name否账号名,全局唯一;2–63 字节,仅含字母、数字、_、-,至少一个字母。省略时生成 c_ 加 10 位随机字符
Alias否显示名,规则同 Name;不合法时由邮箱生成
BillingEmail否账单邮箱,可填多个(,、; 或空白分隔,总长 ≤ 256);默认同 Email
CreditGranted否初始额度(以子账号计价),至少为 USER_MIN_BALANCE(默认 1),省略时也会发放该最低额度
Rates否价格倍率,取 max(请求值, 父账号 Rates)
Factor否价格系数。父账号是租户所有者时取 max(请求值, 父账号 Factor),否则等于父账号的值
RPM、RPH、RPD、TPM、TPH、TPD否账号级限速,每项取 min(请求值, 父账号的值);省略或小于 1 时继承父账号
UserLimit否该子账号可再创建的子账号数;默认 0。父账号非 root 且自身 UserLimit < 64 时强制为 0
FundingType否仅租户所有者可用:subscription(订阅额度)或 payg(按量额度)
SecretKey否指定子账号的 Key(必须是合法的 51 位 sk-Xvs Key),省略时自动生成

以下属性从父账号继承,创建时传入也不会生效,需要时在创建后通过更新接口调整:Level、Gear、Role、DailyLimit、Resources、AllowIPs、AllowModels、AllowLevels、ModelLimits、ModelMapper、LevelMapper。HardLimit 与 SoftLimit 按初始余额自动计算。

额度来源:

  • 调用者是租户所有者时,额度直接发放,不扣减调用者余额;有效期默认 1 年。
  • 调用者是普通管理者时,额度从调用者余额中划转:调用者扣减 CreditGranted ÷ 子.Rates × 父.Rates,子账号获得的额度保留来源额度的有效期与资金类型。余额不足返回 403 Insufficient balance。

响应(200):

{
  "Action": "add",
  "User": {
    "ID": 123,
    "SecretKey": "sk-Xvs...",
    "Updates": {"Name": "dev-a", "Level": 1, "Rates": 1, "CreditBalance": [], "UserLimit": 0}
  }
}

SecretKey 只在创建响应中返回一次,同时会通过欢迎邮件发送到子账号的 Email。请妥善保存。

状态码正文原因
400Invalid email address邮箱不合法
400Name: 4-63 chars, at least 1 letters账号名不合法(实际下限为 2 字节)
400Invalid funding type ...FundingType 取值错误
403Only owner can specify FundingType非租户所有者指定了资金类型
403Sub-user limit reached / Management access requires remaining sub-user quota.子账号名额已满
403Insufficient balance划转额度不足
409User already exists账号名或邮箱已被使用

查询账号

GET /x-users                      # 直属子账号
GET /x-dna                        # 全部后代
GET /x-dna?level=2&page=1&size=50&order=desc
GET /x-users/42                   # 按 ID
GET /x-dna/[email protected]      # 按邮箱
GET /x-dna/.1.5.                  # 按 DNA 前缀
GET /x-dna/L2                     # Level 2 的全部后代

查询参数(仅用于 /x-users、/x-dna 本身):

参数说明
id、name、email、level精确匹配
dnaDNA 前缀匹配
page、size分页;单页最多 8192 条
orderdesc(或 id_desc)按 ID 降序,其余升序

路径标识(/x-users/{identifier}、/x-dna/{identifier}):数字为 ID;含 @ 为邮箱;以 . 开头为 DNA 前缀;L<n>、G<n>、R<n>、T<n>、F<x> 分别按 Level、Gear、Role、Tier、Factor 过滤;其他视为账号名。

响应:始终是账号对象数组,无匹配时返回 []。SecretKey、PublicKey、PartialKey、EncryptionKey 均以 "*" 脱敏。响应头包含 X-Total-Count,分页时另有 X-Page、X-Per-Page、X-Total-Pages。

每次调用 GET /x-users 或 GET /x-dna 都按 XAPI_FEE(默认 ¥0.012)计费。

更新账号

curl -X PUT "$XSI_BASE_URL/x-users/dev-a" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "CreditGranted": 100,
    "Days": 90,
    "DailyLimit": 50,
    "AllowModels": "gpt-6* claude-sonnet-5-5",
    "AllowIPs": "203.0.113.0/24"
  }'

定位目标:/x-users/{identifier} 或 /x-users?id=...、/x-users?name=...。数字 ID 全局查找后校验是否为调用者的后代;账号名与邮箱只在调用者的后代中查找。目标不在子树内返回 403 Forbidden(数字 ID)或 404 User not found。

可更新字段

字段谁可以设置说明
Email、Alias、BillingEmail、QRCode管理者;本人资料
InvoiceInfo仅本人发票抬头 {type, company_name, tax_no, registered_address, registered_phone, bank_name, bank_account, email}
CreditGranted管理者正数充值、负数扣回
Days、DaysExplicit管理者新增额度的有效天数,见下文
Status管理者(不能改自己)false 停用账号
DailyLimit、HardLimit、SoftLimit管理者日额度、月额度(CNY);SoftLimit 仅保存,不参与准入
RPM、RPH、RPD、TPM、TPH、TPD管理者账号级限速
UserLimit管理者子账号名额
Rates、Gear管理者价格倍率(不低于调用者)、路由模式(不高于调用者)
ModelLimits管理者模型级限额
Resources、AllowIPs、AllowModels、AllowLevels管理者白名单,见下文
ModelMapper管理者账号级模型映射
Scope、DryRun管理者批量收窄后代的白名单,见下文
FundingType仅租户所有者本次额度的资金类型
Level、Role、Factor、LevelMapper仅租户所有者路由分组、计费档位、价格系数、账号级 Level 映射

非租户所有者更新自己时,只能修改 Email、Alias、BillingEmail、InvoiceInfo、QRCode。

额度调整

  • 租户所有者:正数直接发放(不扣所有者余额),有效期为 now + Days(默认 365 天);负数直接从目标扣减,可扣至负数。
  • 普通管理者:每次更新收取一次 XAPI_FEE。正数从调用者余额划转(按 Rates 折算);负数把额度退回调用者,以目标余额为上限,并再收取一次 XAPI_FEE。Days 在此只是上限:新额度的到期时间不晚于调用者额度的最晚到期时间;不传 Days 时沿用来源额度的到期时间。
  • |CreditGranted| > 0.5 时会向目标发送额度变动邮件。
普通管理者的更新会重新对齐计划:普通管理者(非租户所有者)对后代执行任何常规更新时,即使只修改资料,也会把目标的 Level、Role、模型映射、Level 映射与支持二维码对齐为管理者自己的值;若目标与管理者的 Level 不同,还会先清空目标的正余额,跨 Level 扣回会被拒绝。请先确认目标的计划设置,避免误操作。

白名单语法

Resources、AllowIPs、AllowModels、AllowLevels 的值是字符串,项之间用逗号、分号或空白分隔:

写法含义
a b c追加这些项(不带前缀的裸列表为追加,不会移除已有项)
+x添加一项
-x删除一项
*恢复为父账号的范围
-*清空。组合写法 -*,+a,+b 可把范围完整替换为 a、b
  • AllowIPs 支持单个 IP 与 CIDR;回环地址始终可用。AllowLevels 清空后账号仍可使用自身的 Level。
  • AllowModels 支持 * 通配,例如 gpt-6*。
  • Resources 按路径前缀匹配,例如 /v1/chat/completions、/v1/responses。
  • 非租户所有者设置的范围会与调用者自身的范围取交集;不合法的项被跳过。

Scope 可一次收窄整棵子树:"Scope": "self" | "descendants" | "tree",仅支持 Resources 与 AllowModels;配合 "DryRun": true 可先预览影响范围。此路径对不合法的项直接报错。

ModelLimits

{"ModelLimits": {"gpt-6.2-sol": {"rpm": 30, "tpm": 400000}}}
  • 键必须是上游模型名的精确值(映射后的名称),不支持通配符;价格表中不存在的模型会被忽略。
  • 内层键为小写 rpm、rph、rpd、tpm、tph、tpd。新条目中未给出的维度不限制;更新已有条目时,未给出的维度保持原值。
  • 限额只对 Role 2(严格)与 Role 3(订阅)账号生效,见《访问控制与限额》。

响应(200):{"Action": "update", "User": {"ID": 42, "Updates": {...}}},Updates 为更新后的完整快照。每次更新都会给目标写一条有效期 1 天的 “Account Update” 通知。

批量调整额度

curl -X POST "$XSI_BASE_URL/x-users/batch-credit" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"CreditGranted": 50, "Filters": {"level": 2}, "Order": "asc", "DryRun": true}'
字段说明
CreditGranted必填,非 0:正数发放,负数扣回(以子账号计价)
IDs目标 ID 列表(≤ 8192)。传 [] 不命中任何账号
Filtersid、name、email、dna(前缀)、level、gear、role、tier、factor
Orderdesc 按 ID 降序,其余升序
Days、DaysExplicit同更新接口
FundingType仅租户所有者
DryRuntrue 时只计算不写入
  • 目标范围是调用者的全部后代与 IDs、Filters 的交集。IDs 与 Filters 都不传时将命中全部后代(最多 8192 个,超过时返回 400 Too many target users),务必先用 DryRun 预览。
  • 扣回只按全额执行,余额不足的账号被跳过。
  • 普通管理者在某个账号上余额不足后,后续所有发放都会跳过,因此结果与 Order 有关。
  • 普通管理者整批只收取一次 XAPI_FEE。

响应:

{
  "Action": "batch_credit", "DryRun": false, "CreditGranted": 50,
  "RequestedCount": 3, "AppliedCount": 2, "SkippedCount": 1,
  "TotalChildDelta": 100, "TotalParentDelta": -100.012,
  "ParentBalanceBefore": 1000, "ParentBalanceAfter": 899.988, "ApiFee": 0.012,
  "Results": [{"ID": 7, "Name": "dev-a", "Status": "applied", "CreditGranted": 50, "ParentDelta": -50, "Balance": 150}]
}

Status 取值:applied、skipped_not_found、skipped_forbidden、skipped_parent_insufficient、skipped_invalid_rate、skipped_level_mismatch、skipped_parent_gear、skipped_child_insufficient、skipped_invalid_credit_state。

删除账号

curl -X DELETE "$XSI_BASE_URL/x-users/dev-a" -H "Authorization: Bearer $XSI_API_KEY"
  • root 可删除任意账号,其他管理者只能删除自己的后代。
  • 删除为硬删除且不级联:被删账号的子账号保留在原子树中,仍可由上层祖先管理。
  • 被删账号的正余额按 Rates 折算退回调用者,欠款从调用者扣除,并收取一次 XAPI_FEE。目标 TPD ≤ 800000000,或调用者不是租户所有者且 Level 不同时,正余额不退回。
  • 会向被删账号发送通知邮件。

响应:{"Action": "delete", "User": {"ID": 42, "Name": "dev-a", "Email": "...", "Rates": 1, "CreditBalance": [...]}}。

轮换本人 Key

curl -X POST "$XSI_BASE_URL/x-self" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"confirm\": \"$(date +%F)-ROTATE-SELF\"}"
字段说明
confirm必填确认短语:<服务器本地日期 YYYY-MM-DD>-ROTATE-SELF;root 账号为 ...-ROTATE-ROOT
key可选,指定新的 51 位 sk-Xvs Key;省略时自动生成
  • 旧 Key 立即失效,新 Key 在响应中返回,并发送到本人的 Email 与 BillingEmail。
  • 成功轮换后 10 分钟内不能再次轮换:429 API Key was regenerated recently. Please try again later.(带 Retry-After: 600)。
{"success": true, "message": "Self key rotated successfully",
 "rotate": {"action": "rotate_self", "id": 42, "name": "dev-a", "email": "...", "key": "sk-Xvs...", "timestamp": "..."}}

通知公告

curl -X POST "$XSI_BASE_URL/x-news/dev-a" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "维护通知", "content": "今晚 23:00 切换上游。", "days": 3}'
路径对象权限
/x-news全部账号(系统公告)仅 root
/x-news/{ID、账号名或邮箱}指定账号目标须为调用者的后代
/x-news/.{DNA}DNA 完全等于该值的账号(即同一父账号的直接子账号)DNA 中须包含调用者
  • 请求体:title(可选)、content(必填)、days(1–32,超出范围按 32)。
  • 同一对象最多保留最近 8 条。
  • DELETE 相同路径会删除该对象下的全部通知。
  • 账号通过 GET /dashboard/news 读取,个人通知读取一次后即被清除。

相关文档