Manage API 参考
Manage API 为用户提供完整的子账户管理和自助查询能力,包括创建、更新、删除子账户,查询账户状态、余额、用量、账单和操作日志。所有用户均可访问,但部分操作需要父账户权限。
基础信息
基础 URL: https://api.xaixapi.com
认证方式: 所有请求需携带 API Key
Authorization: Bearer sk-Xvs...
权限说明:
- 仪表盘查询端点:任何有效用户
- 子账户管理端点:仅父账户或祖先账户
前端控制台: Manage Console / 生产环境
端点总览
| 功能模块 | 端点 | 说明 |
|---|---|---|
| 子账户管理 | POST /x-users | 创建子账户 |
GET /x-users / GET /x-users/{identifier} | 查询子账户 | |
GET /x-dna / GET /x-dna/{identifier} | 查询后代账户 | |
PUT /x-users/{identifier} | 更新子账户(充值、配置等) | |
DELETE /x-users/{identifier} | 删除子账户 | |
| 仪表盘查询 | GET /dashboard/status | 用户状态 |
GET /dashboard/info | 用户详情 | |
GET /dashboard/bill | 用量账单 | |
GET /dashboard/logs | 操作日志 | |
GET /dashboard/news | 新闻通知 | |
GET /dashboard/conf | 系统配置 | |
GET /dashboard/models | 模型清单 |
1. 子账户管理 API
1.1 创建子账户
在您的账户下创建新的子账户。
端点: POST /x-users
权限: 需要父账户权限且满足余额/限额要求
请求体字段:
{
"Name": "subaccount-1", // 账户名(必填,4-63字符,至少1个字母)
"Email": "[email protected]", // 邮箱(必填)
"CreditGranted": 100, // 初始充值(必填,≥2美元)
"Alias": "生产环境账户", // 显示名(可选)
"BillingEmail": "[email protected]", // 账单邮箱(可选)
"Rates": 1.0, // 费率乘数(可选,≥父账户费率)
"Days": 180, // 余额有效期天数(可选,默认180)
"HardLimit": 1000, // 每月硬性限额(可选)
"SoftLimit": 800, // 每月软性限额(可选,达到后邮件提醒)
"AutoQuota": 0, // 自动配额(可选)
"RPM": 60, // 每分钟请求数限制(可选)
"RPH": 3600, // 每小时请求数限制(可选)
"RPD": 86400, // 每天请求数限制(可选)
"TPM": 150000, // 每分钟 Token 数限制(可选)
"TPH": 9000000, // 每小时 Token 数限制(可选)
"TPD": 216000000, // 每天 Token 数限制(可选)
"AllowIPs": "192.168.1.0/24 10.0.0.5", // IP 白名单(可选,空格/逗号分隔)
"AllowModels": "gpt-4* claude-*", // 模型白名单(可选,支持通配符)
"Resources": "/v1/chat/completions /v1/embeddings", // 资源白名单(可选)
"ModelLimits": { // 单个模型的速率限制(可选)
"gpt-4": {"rpm": 30, "tpm": 90000}
}
}
必填字段:
Name- 唯一账户名(4-63字符,至少1个字母)Email- 有效的电子邮件地址CreditGranted- 初始充值金额(≥2美元)
可选字段详解:
基础配置:
Alias- 显示名称(默认与 Name 相同)BillingEmail- 账单通知邮箱(默认与 Email 相同)Rates- 费率乘数(必须 ≥ 父账户费率,默认继承父账户)Days- 余额有效期天数(默认 180)
限额设置:
HardLimit- 每月硬性限额(达到后停止服务)SoftLimit- 每月软性限额(达到后邮件提醒)AutoQuota- 自动配额(自动充值功能)
速率限制:
RPM/RPH/RPD- 请求速率限制(每分钟/小时/天)TPM/TPH/TPD- Token 速率限制(每分钟/小时/天)
访问控制:
AllowIPs- IP 白名单(CIDR 格式,空格或逗号分隔)AllowModels- 模型白名单(支持通配符,如gpt-4*)Resources- 资源白名单(API 端点列表)
模型限速:
ModelLimits- 为特定模型设置独立速率限制(JSON 格式)
示例:
# 基础创建
curl -X POST https://api.xaixapi.com/x-users \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Name": "prod-account",
"Email": "[email protected]",
"CreditGranted": 500,
"Alias": "生产环境",
"RPM": 100,
"TPM": 200000
}'
# 完整配置
curl -X POST https://api.xaixapi.com/x-users \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Name": "dev-account",
"Email": "[email protected]",
"CreditGranted": 100,
"Alias": "开发环境",
"Rates": 1.0,
"Days": 30,
"HardLimit": 500,
"SoftLimit": 400,
"RPM": 60,
"TPM": 150000,
"AllowModels": "gpt-4o-mini claude-3-haiku*",
"AllowIPs": "192.168.1.0/24",
"ModelLimits": {
"gpt-4o-mini": {"rpm": 30, "tpm": 90000}
}
}'
响应示例:
{
"Action": "add",
"User": {
"ID": 42,
"SecretKey": "sk-Xvs...",
"Updates": {
"Name": "prod-account",
"Email": "[email protected]",
"CreditGranted": 500,
"Balance": 500,
"HardLimit": 500,
"SoftLimit": 400,
"Status": true,
"Level": 2,
"DNA": ".1.42."
}
}
}
1.2 查询子账户
查询一个或多个子账户的信息。
端点:
GET /x-users- 获取所有直属子账户GET /x-users/{identifier}- 获取指定用户GET /x-dna- 获取所有后代账户(包括子账户的子账户)GET /x-dna/{identifier}- 获取指定后代账户
查询参数:
id- 按用户 ID 筛选name- 按用户名筛选(支持部分匹配)email- 按电子邮件筛选level- 按级别筛选(0-9)dna- 按 DNA(层级路径)筛选page- 页码(默认: 1)size- 每页大小(默认: 100, 最大: 1000)
特殊路径过滤器:
使用路径参数时(如 /x-users/{identifier}),支持以下前缀:
L{n}- 按级别筛选(如/x-users/L2表示所有 2 级用户)G{n}- 按档位 (Gear) 筛选(如/x-users/G1)R{n}- 按角色 (Role) 筛选(如/x-users/R3)T{n}- 按层级 (Tier) 筛选(如/x-users/T2)F{n}- 按因子 (Factor) 筛选(如/x-users/F1.5).{dna}- 按 DNA 路径筛选(如/x-users/.1.42.){email}- 如果包含 @,则按电子邮件筛选(如/x-users/[email protected]){id}- 数字 ID(如/x-users/42){name}- 用户名(如/x-users/prod-account)
示例:
# 获取所有直属子账户
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users
# 按 ID 获取指定用户
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users/42
# 按用户名获取
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users/prod-account
# 按邮箱获取
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users/[email protected]
# 按级别筛选
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/x-users?level=2"
# 获取所有后代账户(分页)
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/x-dna?page=1&size=100"
# 使用路径特殊过滤器
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users/L2 # 所有 2 级用户
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users/.1.42. # DNA 路径下的用户
响应示例:
{
"success": true,
"users": [
{
"ID": 42,
"Name": "prod-account",
"Email": "[email protected]",
"Alias": "生产环境",
"Balance": 450.25,
"Level": 2,
"DNA": ".1.42.",
"Status": true,
"Rates": 1.0,
"HardLimit": 1000,
"SoftLimit": 800,
"CreatedAt": "2025-01-01T00:00:00Z"
}
],
"total": 1,
"page": 1,
"size": 100
}
1.3 更新子账户
更新现有子账户的配置、限制和余额。
端点: PUT /x-users/{identifier}
标识符 (Identifier): 可以是用户 ID、用户名或电子邮件
请求体字段(均为可选):
{
"CreditGranted": 100, // 充值金额(负数为扣款)
"Days": 30, // 余额有效期天数
"Status": true, // 启用/禁用账户
"Rates": 1.5, // 更新费率乘数
"HardLimit": 2000, // 更新月硬性限额
"SoftLimit": 1800, // 更新月软性限额
"AutoQuota": 100, // 自动配额
"RPM": 120, // 每分钟请求数
"RPH": 7200, // 每小时请求数
"RPD": 172800, // 每天请求数
"TPM": 300000, // 每分钟 Token 数
"TPH": 18000000, // 每小时 Token 数
"TPD": 432000000, // 每天 Token 数
"AllowModels": "gpt-4* claude-*", // 模型白名单
"AllowIPs": "192.168.1.0/24 10.0.0.5", // IP 白名单
"Resources": "/v1/chat/completions /v1/embeddings", // 资源白名单
"ModelLimits": { // 单个模型限速
"gpt-4": {"rpm": 30, "tpm": 90000}
}
}
特殊操作:
充值/扣款:
- 充值:
"CreditGranted": 100 - 扣款:
"CreditGranted": -50 - 自定义有效期:
"CreditGranted": 100, "Days": 90
白名单管理:
- 重置白名单:
"AllowModels": "*" - 从白名单移除:
"AllowModels": "-gpt-3.5-turbo" - 添加到白名单:
"AllowModels": "gpt-4o claude-3-opus"
示例:
# 充值并设置有效期
curl -X PUT https://api.xaixapi.com/x-users/42 \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"CreditGranted": 100, "Days": 30}'
# 扣款
curl -X PUT https://api.xaixapi.com/x-users/prod-account \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"CreditGranted": -50}'
# 更新模型白名单
curl -X PUT https://api.xaixapi.com/x-users/prod-account \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"AllowModels": "gpt-4* claude-3*"}'
# 更新速率限制
curl -X PUT https://api.xaixapi.com/x-users/42 \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"RPM": 200, "TPM": 500000}'
# 禁用账户
curl -X PUT https://api.xaixapi.com/x-users/42 \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"Status": false}'
# 批量更新(充值+限制+白名单)
curl -X PUT https://api.xaixapi.com/x-users/dev-account \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"CreditGranted": 200,
"Days": 60,
"HardLimit": 1000,
"RPM": 100,
"AllowModels": "gpt-4* claude-*",
"ModelLimits": {
"gpt-4o": {"rpm": 50, "tpm": 150000}
}
}'
1.4 删除子账户
删除子账户并退还其剩余余额到父账户。
端点: DELETE /x-users/{identifier}
权限: 仅父账户或主账户
行为说明:
- 剩余余额自动退还到父账户
- 扣除 0.2 美元手续费
- 退还余额默认有效期 180 天
- 删除后不可恢复
示例:
curl -X DELETE https://api.xaixapi.com/x-users/42 \
-H "Authorization: Bearer $API_KEY"
curl -X DELETE https://api.xaixapi.com/x-users/dev-account \
-H "Authorization: Bearer $API_KEY"
响应示例:
{
"Action": "delete",
"User": {
"ID": 42,
"Name": "dev-account",
"RefundedBalance": 49.8,
"TransactionFee": 0.2
},
"message": "User deleted successfully"
}
2. 仪表盘查询 API
2.1 用户状态
获取当前用户的基本状态信息,适合快速查询。
端点: GET /dashboard/status
权限: 任何有效用户
示例:
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/status
响应示例:
{
"object": "user_status",
"id": 42,
"dna": ".1.42.",
"name": "prod-account",
"email": "[email protected]",
"alias": "生产环境",
"public_key": "pk-...",
"balance": 450.25,
"manage": true, // 是否可访问 Manage 控制台
"admin": true // 是否可访问 Admin 控制台(仅主账户)
}
2.2 用户详情
获取详细的用户信息,包括余额明细、限制配置、用量统计和访问控制。
端点: GET /dashboard/info
权限: 任何有效用户
示例:
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/info
响应示例:
{
"object": "user_info",
"user": {
"id": 42,
"name": "prod-account",
"email": "[email protected]",
"alias": "生产环境",
"level": 1,
"gear": 1,
"role": 1,
"tier": 1,
"factor": 1.0,
"rates": 1.0,
"dna": ".1.42.",
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-01-15T10:00:00Z"
},
"balance": {
"total": 450.25,
"credits": [
{
"amount": 400.00,
"expires_at": "2025-02-15T00:00:00Z"
},
{
"amount": 50.25,
"expires_at": "2025-03-01T00:00:00Z"
}
]
},
"limits": {
"hard_limit": 5000,
"soft_limit": 4000,
"auto_quota": 0,
"rpm": 100,
"rph": 3600,
"rpd": 10000,
"tpm": 200000,
"tph": 6000000,
"tpd": 50000000
},
"usage": {
"today": {
"requests": 150,
"tokens": 450000,
"cost": 12.50
},
"month": {
"requests": 3500,
"tokens": 12500000,
"cost": 285.75
}
},
"restrictions": {
"allow_ips": ["192.168.1.0/24", "10.0.0.5"],
"allow_models": ["gpt-4*", "claude-3*"],
"resources": ["/v1/chat/completions", "/v1/embeddings"]
},
"model_limits": {
"gpt-4": {
"rpm": 30,
"tpm": 90000
},
"claude-3-opus": {
"rpm": 20,
"tpm": 60000
}
}
}
2.3 用量账单
获取用量统计和账单信息,支持日期范围查询。
端点: GET /dashboard/bill
权限: 任何有效用户
查询参数:
date或d- 指定日期(YYYY-MM-DD)start或s- 开始日期end或e- 结束日期days- 过去 N 天(从今天算起)
费用说明:
- 查询跨度 >30 天:计费 0.01 美元
- 查询跨度 >365 天:自动截断至一年,计费 0.05 美元
示例:
# 获取今日用量(默认)
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/bill
# 获取指定日期用量
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/bill?date=2025-01-15"
# 获取过去 30 天用量
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/bill?days=30"
# 按日期范围查询
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/bill?start=2025-01-01&end=2025-01-31"
响应示例:
{
"object": "list",
"data": [
{
"aggregation_timestamp": 1234567890,
"n_requests": 1000,
"n_context_tokens_total": 500000,
"n_generated_tokens_total": 100000,
"n_cached_tokens_total": 50000,
"usage_details": {
"gpt-4": {
"requests": 100,
"prompt": 50000,
"completion": 10000,
"cost": 3.5
},
"claude-3-opus": {
"requests": 50,
"prompt": 25000,
"completion": 5000,
"cost": 2.8
}
}
}
],
"total_usage": {
"requests": 10000,
"prompt_tokens": 5000000,
"completion_tokens": 1000000,
"cached_tokens": 500000,
"cost": 125.50
},
"query_fee": 0.01
}
2.4 操作日志
获取账户的操作日志记录,支持分页和筛选。
端点: GET /dashboard/logs
权限: 任何有效用户(通常仅查看自身范围)
查询参数:
page- 页码(默认: 1)size- 每页大小(默认: 24, 最大: 100)action- 按操作类型筛选target_id- 按目标 ID 筛选status- 按状态筛选
示例:
# 获取最近日志
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/logs
# 分页获取日志
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/logs?page=2&size=50"
# 筛选特定操作
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/logs?action=add_user"
响应示例:
{
"logs": [
{
"id": 123,
"action": "add_user",
"operator_id": 1,
"target_id": 42,
"details": "创建了用户,邮箱为: [email protected]",
"ip_address": "192.168.1.100",
"created_at": "2025-01-15 10:30:00",
"status": "success"
},
{
"id": 124,
"action": "update_user",
"operator_id": 1,
"target_id": 42,
"details": "充值 100 美元,有效期 30 天",
"ip_address": "192.168.1.100",
"created_at": "2025-01-15 10:35:00",
"status": "success"
}
],
"total": 150,
"page": 1,
"size": 24,
"has_more": true
}
常见 action 类型:
add_user- 创建用户update_user- 更新用户delete_user- 删除用户add_key- 添加密钥update_key- 更新密钥delete_key- 删除密钥rotate_self- 密钥轮换auto_config- 自动配置
2.5 新闻通知
获取系统新闻和用户通知。
端点: GET /dashboard/news
权限: 任何有效用户
示例:
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/news
响应示例:
{
"success": true,
"system_news": [
{
"id": 1,
"title": "系统更新通知",
"content": "系统将于...",
"created_at": "2025-01-15T10:00:00Z",
"expires_at": "2025-01-22T10:00:00Z"
}
],
"user_news": [
{
"id": 2,
"title": "账户余额提醒",
"content": "您的账户余额不足...",
"created_at": "2025-01-15T11:00:00Z",
"expires_at": "2025-02-15T11:00:00Z"
}
],
"dna_news": [
{
"id": 3,
"title": "团队通知",
"content": "针对您所在团队的重要通知...",
"created_at": "2025-01-15T12:00:00Z",
"expires_at": "2025-02-15T12:00:00Z"
}
]
}
新闻类型说明:
system_news- 系统级新闻(所有用户可见)user_news- 用户级新闻(指定用户)dna_news- DNA 组级新闻(指定 DNA 路径下的用户)
2.6 系统配置
获取全局关键阈值和配置参数。
端点: GET /dashboard/conf
权限: 任何有效用户
示例:
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/conf
响应示例:
{
"UserMinBalance": 1.0,
"UserApiBalance": 0.5,
"SystemVersion": "v2.5.0",
"Features": {
"sign_enable": true,
"safe_enable": true
}
}
2.7 模型清单
获取当前系统内置/代理可用的模型清单。
端点: GET /dashboard/models
权限: 任何有效用户
示例:
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/models
响应示例:
{
"models": [
{
"id": "gpt-4o",
"provider": "openai",
"context_window": 128000,
"max_output_tokens": 16384
},
{
"id": "claude-3-opus",
"provider": "anthropic",
"context_window": 200000,
"max_output_tokens": 4096
}
]
}
使用场景
场景 1:创建开发环境子账户
# 1. 创建子账户
curl -X POST https://api.xaixapi.com/x-users \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Name": "dev-env-001",
"Email": "[email protected]",
"CreditGranted": 10,
"Alias": "开发环境",
"HardLimit": 50,
"SoftLimit": 40,
"RPM": 30,
"AllowModels": "gpt-4o-mini claude-3-haiku*"
}'
# 2. 验证创建结果
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users/dev-env-001
场景 2:批量查询子账户状态
# 获取所有子账户
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-users
# 获取所有后代账户(包括子账户的子账户)
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/x-dna
# 筛选 Level 2 的账户
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/x-users?level=2"
场景 3:为子账户充值并更新限制
# 充值并更新配置
curl -X PUT https://api.xaixapi.com/x-users/dev-env-001 \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"CreditGranted": 50,
"Days": 30,
"HardLimit": 100,
"RPM": 60,
"AllowModels": "gpt-4* claude-*"
}'
场景 4:查看用量趋势和账单
# 查看今日用量
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/bill
# 查看本月用量
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/bill?days=30"
# 查看详细信息(余额、限制、用量)
curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/info
场景 5:监控和告警
# 定期检查账户余额
*/60 * * * * curl -H "Authorization: Bearer $API_KEY" \
https://api.xaixapi.com/dashboard/info | \
jq '.balance.total' | \
awk '{if($1<10) print "Low balance warning!"}'
# 检查操作日志
curl -H "Authorization: Bearer $API_KEY" \
"https://api.xaixapi.com/dashboard/logs?action=delete_user"
最佳实践
账户管理
- 分级管理 - 为不同环境(开发/测试/生产)创建独立账户
- 合理限额 - 设置 SoftLimit 和 HardLimit 避免意外超支
- 模型白名单 - 限制子账户只能使用特定模型
- 定期审计 - 定期查看子账户列表和用量
充值管理
- 按需充值 - 不要一次充值过多
- 设置有效期 - 为测试账户设置较短的有效期
- 保留余额 - 删除账户前先扣款以回收余额
用量监控
- 每日检查 - 查看今日用量避免异常
- 趋势分析 - 定期分析用量趋势优化成本
- 模型优化 - 根据用量数据选择合适的模型
- 缓存策略 - 对于
/dashboard/status和/dashboard/info,建议缓存 5-10 分钟
日志和审计
- 分页处理 - 操作日志可能很多,使用分页参数避免单次返回过多数据
- 日期范围 - 查询用量时,建议日期范围不超过 90 天以获得最佳性能
- 成本控制 - 频繁查询长时间范围的账单会产生额外费用,请合理设置查询周期
相关文档
- Admin API 参考 - Provider 密钥和系统配置 API
- Manage Console 使用指南 - Manage UI 操作说明
- 术语表 - Level、模型映射等概念说明