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

权限: 任何有效用户

查询参数:

  • dated - 指定日期(YYYY-MM-DD)
  • starts - 开始日期
  • ende - 结束日期
  • 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"

最佳实践

账户管理

  1. 分级管理 - 为不同环境(开发/测试/生产)创建独立账户
  2. 合理限额 - 设置 SoftLimit 和 HardLimit 避免意外超支
  3. 模型白名单 - 限制子账户只能使用特定模型
  4. 定期审计 - 定期查看子账户列表和用量

充值管理

  1. 按需充值 - 不要一次充值过多
  2. 设置有效期 - 为测试账户设置较短的有效期
  3. 保留余额 - 删除账户前先扣款以回收余额

用量监控

  1. 每日检查 - 查看今日用量避免异常
  2. 趋势分析 - 定期分析用量趋势优化成本
  3. 模型优化 - 根据用量数据选择合适的模型
  4. 缓存策略 - 对于 /dashboard/status/dashboard/info,建议缓存 5-10 分钟

日志和审计

  1. 分页处理 - 操作日志可能很多,使用分页参数避免单次返回过多数据
  2. 日期范围 - 查询用量时,建议日期范围不超过 90 天以获得最佳性能
  3. 成本控制 - 频繁查询长时间范围的账单会产生额外费用,请合理设置查询周期

相关文档