账号管理 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。请妥善保存。
| 状态码 | 正文 | 原因 |
|---|---|---|
400 | Invalid email address | 邮箱不合法 |
400 | Name: 4-63 chars, at least 1 letters | 账号名不合法(实际下限为 2 字节) |
400 | Invalid funding type ... | FundingType 取值错误 |
403 | Only owner can specify FundingType | 非租户所有者指定了资金类型 |
403 | Sub-user limit reached / Management access requires remaining sub-user quota. | 子账号名额已满 |
403 | Insufficient balance | 划转额度不足 |
409 | User 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 | 精确匹配 |
dna | DNA 前缀匹配 |
page、size | 分页;单页最多 8192 条 |
order | desc(或 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时会向目标发送额度变动邮件。
白名单语法
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)。传 [] 不命中任何账号 |
Filters | id、name、email、dna(前缀)、level、gear、role、tier、factor |
Order | desc 按 ID 降序,其余升序 |
Days、DaysExplicit | 同更新接口 |
FundingType | 仅租户所有者 |
DryRun | true 时只计算不写入 |
- 目标范围是调用者的全部后代与
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读取,个人通知读取一次后即被清除。