Admin API 参考

Admin API 为主账户（Owner）提供完整的系统配置能力，包括 Provider 密钥池管理、模型映射、Level 路由、定价覆盖和广播通知。所有端点均需主账户权限。

基础信息

基础 URL： https://api.xaixapi.com

认证方式： 所有请求需携带主账户 API Key

Authorization: Bearer sk-Xvs...

权限要求： 仅主账户（isOwner=true）可调用

前端控制台： Admin Console / 生产环境

端点总览

功能模块	端点	说明
Provider 密钥管理	`GET/POST/PUT/DELETE /x-keys`	管理上游 AI Provider 密钥池
	`GET /x-conf`	查看密钥、映射和休眠状态
	`POST /x-conf`	批量配置管理（级联更新所有后代用户）
系统配置	`GET/PUT/DELETE /x-config`	管理模型映射、Level 路由、限速等
广播通知	`POST/DELETE /x-news`	发布系统或定向通知

核心概念详解

在使用 Admin API 之前，理解以下核心概念对于正确配置系统至关重要。

ModelMapper（模型映射）

作用： 将用户请求的模型名称重定向到另一个模型，实现模型替换和成本优化。

工作原理：

用户请求 gpt-3.5-turbo → 系统实际调用 gpt-4o-mini
对用户完全透明，用户感知不到模型被替换
支持通配符匹配（如 gpt-3.5* 匹配所有 gpt-3.5 系列）

典型使用场景：

成本优化 - 将昂贵模型映射到便宜模型

o1-preview=gpt-4o        # 将 o1 请求降级到 gpt-4o
gpt-4-turbo=gpt-4o-mini  # 成本节约 90%

平滑迁移 - 逐步切换到新模型

gpt-4=gpt-4o             # 全部切换到新版本

模型统一 - 统一使用特定模型

gpt-3.5*=gpt-4o-mini     # 所有 3.5 请求统一到 mini
claude-3-haiku=gpt-4o-mini

配置方式：

# 通过 POST /x-conf 配置（级联更新到所有后代用户）
curl -X POST https://api.xaixapi.com/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"ModelMapper": "gpt-3.5*=gpt-4o-mini, o*=gpt-4o"}'

# 或通过 PUT /x-config 配置（仅更新 Owner）
curl -X PUT https://api.xaixapi.com/x-config \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"MODEL_MAPPER": "gpt-3.5*=gpt-4o-mini"}'

注意事项：

✅ 级联更新：通过 /x-conf 配置会自动同步到所有后代用户
✅ 智能合并：不会覆盖用户自定义的其他映射
⚠️ 计费影响：映射后按目标模型计费，注意成本变化
⚠️ 能力差异：确保目标模型能力满足业务需求

LevelMapper（Level 映射）

作用： 定义模型到 Level（负载池）的路由规则，控制请求流向哪个 Provider 密钥池。

工作原理：

Level 是密钥分组的概念，每个密钥属于一个 Level
LevelMapper 定义"哪些模型应该使用哪个 Level 的密钥"
系统根据模型名称匹配规则，选择对应 Level 的密钥池

Level 编号约定：

Level 1: 主力 Provider（如 OpenAI 官方）
Level 2: 备用 Provider（如中转服务）
Level 3: 冷备 Provider（如 Azure OpenAI）
Level 4+: 特殊 Provider（如 Vertex AI）

典型使用场景：

按服务商分流

gpt-4*=1                 # OpenAI 模型走 Level 1（官方密钥）
claude*=2                # Claude 模型走 Level 2（中转密钥）
gemini*=3                # Gemini 走 Level 3（Vertex AI）

按成本分级

gpt-4o=1                 # 高成本模型走官方
gpt-4o-mini=2            # 低成本模型走中转

按可靠性分级

o1*=1                    # 关键模型走最稳定的 Provider
*=2                      # 其他模型走普通 Provider

配置方式：

# 通过 POST /x-conf 配置（系统级配置，所有后代用户共享）
curl -X POST https://api.xaixapi.com/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"LevelMapper": "gpt-4*=1, claude*=2, gemini*=3"}'

重要特性：

🔒 系统级配置：所有后代用户共享 Owner 的 LevelMapper，无法单独覆盖
🔄 自动补全：添加密钥时，系统会根据 Provider 自动补全 LevelMapper
🎯 通配符匹配：支持 gpt-4*、claude-3-* 等模式
🔀 配合 SwitchOver：Level 故障时自动切换到备用 Level

与 ModelMapper 的区别：

配置	作用	影响范围	是否可覆盖
ModelMapper	模型名称替换	级联更新	用户可自定义
LevelMapper	路由到 Level	系统级共享	用户不可覆盖

ModelFailover（模型故障转移）

作用： 定义模型级别的故障转移策略，当主模型不可用时自动切换到备用模型。

工作原理：

主模型请求失败（如密钥失效、限流、服务不可用）
系统自动重试备用模型列表
按顺序尝试，直到成功或所有备用模型都失败

配置格式：

主模型=备用模型1|备用模型2|备用模型3

典型使用场景：

高可用保障

gpt-4o=gpt-4o-mini|gpt-4-turbo
claude-3-opus=claude-3-sonnet|gpt-4o

成本降级

o1-preview=gpt-4o|gpt-4o-mini    # 昂贵模型失败时降级

跨服务商容错

gpt-4o=claude-3-opus              # OpenAI 故障时切换到 Anthropic

配置方式：

curl -X POST https://api.xaixapi.com/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"ModelFailover": "gpt-4o=gpt-4o-mini|gpt-4-turbo"}'

与 SwitchOver 的区别：

配置	级别	触发条件	切换对象
ModelFailover	模型级	模型请求失败	切换到备用模型
SwitchOver	Level级	Level 所有密钥失效	切换到备用 Level

SwitchOver（Level 切换）

作用： 定义 Level 级别的故障转移，当某个 Level 的所有密钥都不可用时，自动切换到备用 Level。

工作原理：

Level 1 的所有密钥都失效/休眠
系统自动将请求转发到 Level 2
Level 2 的密钥处理请求

配置格式：

主Level=备用Level

典型使用场景：

多层容错

1=2                      # Level 1 故障时切换到 Level 2
2=3                      # Level 2 故障时切换到 Level 3

官方到中转

1=2                      # 官方 API 故障时切换到中转服务

主备架构

1=2, 2=1                 # Level 1 和 2 互为备份

配置方式：

curl -X PUT https://api.xaixapi.com/x-config \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"SWITCH_OVER": "1=2, 2=3"}'

多层容错示例：

配置：1=2, 2=3
流程：请求 → Level 1（失败）→ Level 2（失败）→ Level 3（成功）

ModelLimits（模型限速）

作用： 为特定模型设置速率限制，防止超出 Provider 的速率限制或控制成本。

限速维度：

RPM - Requests Per Minute（每分钟请求数）
RPH - Requests Per Hour（每小时请求数）
RPD - Requests Per Day（每天请求数）
TPM - Tokens Per Minute（每分钟 Token 数）
TPH - Tokens Per Hour（每小时 Token 数）
TPD - Tokens Per Day（每天 Token 数）

典型使用场景：

匹配 Provider 限制

{
  "gpt-4o": {"rpm": 500, "tpm": 150000},    // 匹配 OpenAI Tier 2
  "claude-3-opus": {"rpm": 50, "tpm": 40000} // 匹配 Anthropic 限制
}

成本控制

{
  "o1-preview": {"rpm": 10, "rpd": 100}      // 限制昂贵模型使用
}

公平调度

{
  "gpt-4o": {"rpm": 100},                    // 防止单个用户占用过多资源
  "gpt-4o-mini": {"rpm": 500}
}

配置方式：

# 方式 1: 通过 POST /x-conf（级联更新到所有后代用户）
curl -X POST https://api.xaixapi.com/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "ModelLimits": {
      "gpt-4o": {"rpm": 30, "tpm": 90000},
      "claude-3-opus": {"rpm": 20, "tpm": 60000}
    }
  }'

# 方式 2: 通过 PUT /x-config（仅更新 Owner）
curl -X PUT https://api.xaixapi.com/x-config \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"MODEL_LIMITS": "{\"gpt-4o\": {\"rpm\": 30}}"}'

限速优先级：

用户级 ModelLimits > Owner ModelLimits > 系统默认限制

清空限速：

# 清空所有限速
curl -X POST https://api.xaixapi.com/x-conf \
  -d '{"ModelLimits": "*"}'

# 删除特定模型限速
curl -X POST https://api.xaixapi.com/x-conf \
  -d '{"ModelLimits": "-gpt-4o, -claude-3-opus"}'

Resources（资源白名单）

作用： 限制用户可以访问的 API 端点，实现精细化权限控制。

典型使用场景：

仅允许聊天
```
/v1/chat/completions
```

禁止图像生成

/v1/chat/completions, /v1/embeddings, /v1/audio/speech

全功能访问

/v1/chat/completions, /v1/embeddings, /v1/images/generations, /v1/audio/*

配置方式：

# Owner 级配置
curl -X PUT https://api.xaixapi.com/x-config \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"RESOURCES": "/v1/chat/completions, /v1/embeddings"}'

# 用户级配置（通过 PUT /x-users/{id}）
curl -X PUT https://api.xaixapi.com/x-users/42 \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"Resources": "/v1/chat/completions"}'

权限继承：

子账户的 Resources 必须是父账户 Resources 的子集
子账户无法访问父账户未开放的端点

Provider 密钥管理

密钥状态：

正常（Status: true） - 密钥可用，正常参与负载均衡
禁用（Status: false） - 人工禁用，不参与请求
休眠（Sleeping） - 因多次失败自动休眠，一段时间后自动恢复

休眠机制：

密钥连续失败 N 次（如 3 次）触发休眠
休眠时间递增：5分钟 → 15分钟 → 30分钟 → ...
休眠期间不会使用该密钥
休眠结束后自动恢复，重新加入负载池

查看休眠密钥：

curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/x-conf | jq '.SleepingKeys'

删除所有休眠密钥（立即恢复）：

curl -X POST https://api.xaixapi.com/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"DelKeys": true}'

重新加载密钥：

# 异步重新加载所有密钥（刷新状态、配置等）
curl -X POST https://api.xaixapi.com/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"LoadKeys": true}'

配置优先级总结

全局配置（从高到低）：

用户级配置（User ModelMapper, ModelLimits, Resources）
Owner 级配置（Owner ModelMapper, ModelLimits）
系统级配置（LevelMapper, 系统默认限制）

请求路由流程：

用户请求模型 A
  ↓
应用用户 ModelMapper → 模型 B
  ↓
应用 Owner ModelMapper → 模型 C
  ↓
查询 LevelMapper → Level 2
  ↓
检查 ModelLimits → 通过
  ↓
从 Level 2 密钥池选择可用密钥
  ↓
发送请求到 Provider
  ↓
失败？应用 ModelFailover → 模型 D
  ↓
Level 2 所有密钥失效？应用 SwitchOver → Level 3

1. Provider 密钥管理 API

管理上游 AI Provider 密钥池，支持标准 Provider（OpenAI、Anthropic 等）、Azure OpenAI 和 Google Vertex AI。

1.1 查询密钥

端点： GET /x-keys

查询参数：

id - 按密钥 ID 筛选
level - 按 Level（负载池级别）筛选
provider - 按 Provider URL 筛选
page / size - 分页参数（可选）

路径筛选：

GET /x-keys/{id} - 按 ID 获取
GET /x-keys/L{n} - 按 Level 获取（如 L2）
GET /x-keys/{provider} - 按 Provider 获取（如 api.anthropic.com）

示例：

# 获取所有密钥
curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/x-keys

# 获取 Level 2 的密钥
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.xaixapi.com/x-keys?level=2"

# 获取指定 Provider 的密钥
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.xaixapi.com/x-keys?provider=https://api.openai.com"

响应示例：

{
  "success": true,
  "keys": [
    {
      "ID": 123,
      "Name": "OpenAI 生产",
      "Level": 1,
      "Provider": "https://api.openai.com",
      "Status": true,
      "CreatedAt": "2025-01-01T00:00:00Z",
      "UpdatedAt": "2025-01-15T10:00:00Z"
    }
  ]
}

1.2 新增密钥

端点： POST /x-keys

请求体字段：

{
  "SecretKey": "sk-...",              // 上游 API 密钥（必填，≥20字符）
  "Name": "生产环境-OpenAI",           // 展示名（可选）
  "Level": 1,                         // 负载池级别（必填，用于路由）
  "Provider": "https://api.openai.com", // 上游 API URL（必填）
  "Status": true,                     // 启用状态（默认 true）
  "Config": {                         // 特殊配置（可选）
    "provider_type": "standard"       // standard/azure/vertex
  }
}

配置类型详解

1) 标准配置（Standard）

适用于 OpenAI、Anthropic、Mistral、DeepSeek 等标准兼容 Provider。

{
  "SecretKey": "sk-...",
  "Name": "OpenAI 生产",
  "Level": 1,
  "Provider": "https://api.openai.com",
  "Status": true,
  "Config": {
    "provider_type": "standard"  // 可省略
  }
}

2) Azure OpenAI 配置

{
  "SecretKey": "your-azure-api-key",
  "Name": "Azure OpenAI",
  "Level": 2,
  "Provider": "https://your-resource.openai.azure.com",
  "Status": true,
  "Config": {
    "provider_type": "azure",
    "model_mapping": {
      "gpt-4o": "gpt-4-deployment",    // 模型名 → Deployment 名
      "gpt-3.5*": "gpt35-turbo",       // 支持通配符
      "*": "default-deployment"        // 默认部署
    },
    "api_versions": {                  // 可选，各端点的 API 版本
      "chat": "2025-01-01-preview",
      "embeddings": "2024-02-01",
      "responses": "2025-04-01-preview",
      "audio": "2025-03-01-preview",
      "images": "2025-04-01-preview"
    }
  }
}

3) Google Vertex AI 配置

{
  "SecretKey": "sk-placeholder-51chars-xxxxxxxxxxxxxxxxxxxxxxxx",
  "Name": "Vertex AI",
  "Level": 3,
  "Provider": "https://us-central1-aiplatform.googleapis.com",
  "Status": true,
  "Config": {
    "provider_type": "vertex",
    "base_url": "https://us-central1-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}",
    "project_id": "my-gcp-project",
    "client_email": "[email protected]",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----\n"
  }
}

示例：

# 添加标准 Provider
curl -X POST https://api.xaixapi.com/x-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "sk-live-...",
    "Name": "OpenAI 主池",
    "Level": 1,
    "Provider": "https://api.openai.com",
    "Status": true
  }'

# 添加 Azure OpenAI
curl -X POST https://api.xaixapi.com/x-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "your-azure-key",
    "Name": "Azure GPT-4",
    "Level": 2,
    "Provider": "https://your-resource.openai.azure.com",
    "Status": true,
    "Config": {
      "provider_type": "azure",
      "model_mapping": {"gpt-4o": "gpt-4-deployment"}
    }
  }'

行为说明：

新增成功后，系统自动基于 Provider 智能补全 LEVEL_MAPPER
Config 中的敏感字段（如 Vertex private_key）自动加密存储
Provider URL 不能自引用（不能指向当前系统）
自动刷新 Redis 缓存和内存结构

1.3 更新密钥

端点： PUT /x-keys/{id} 或 POST /x-keys/{id}

可更新字段： Name、Level、Status、Provider、Config 等

示例：

curl -X PUT https://api.xaixapi.com/x-keys/123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Level": 2, "Status": true}'

1.4 删除密钥

端点： DELETE /x-keys/{id}

curl -X DELETE https://api.xaixapi.com/x-keys/123 \
  -H "Authorization: Bearer $API_KEY"

1.5 配置与观测

端点： GET /x-conf

返回与当前主账户相关的：

Resources - 已允许的 API 路径
LevelMapper / ModelMapper / ModelLimits / SwitchOver
正在休眠的密钥列表（含剩余休眠时间）
被禁用的密钥列表
UserMinBalance / UserApiBalance - 关键阈值

curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/x-conf | jq .

响应示例：

{
  "Resources": {
    "/v1/chat/completions": {},
    "/v1/embeddings": {}
  },
  "LevelMapper": {
    "gpt-4*": 2,
    "claude*": 3
  },
  "ModelMapper": {
    "gpt-3.5*": "gpt-4o-mini"
  },
  "ModelFailover": {
    "gpt-4o": ["gpt-4o-mini"]
  },
  "ModelLimits": {
    "gpt-4o": {
      "rpm": 30,
      "tpm": 90000
    }
  },
  "SwitchOver": {
    "1": 2
  },
  "SleepingKeys": [
    {
      "ID": 123,
      "Name": "OpenAI Prod",
      "Level": 1,
      "Provider": "https://api.openai.com",
      "Status": false,
      "SleepTimes": 3
    }
  ],
  "DisabledKeys": [
    {
      "ID": 456,
      "Name": "OpenAI Test",
      "Level": 2,
      "Provider": "https://api.openai.com",
      "Status": false
    }
  ],
  "UserMinBalance": 1.0,
  "UserApiBalance": 0.5
}

1.6 批量配置管理

端点： POST /x-conf

功能概述： 主账户批量配置管理接口，支持一次性更新密钥、映射关系，并自动同步到所有后代用户。

重要特性：

批量同步 - ModelMapper、ModelLimits 的变更会自动应用到所有后代用户
系统级配置 - LevelMapper 为系统级配置，所有后代用户共享 Owner 的配置
智能合并 - 级联更新保留用户自定义配置，仅更新差量部分

请求体字段：

{
  "LoadKeys": true,                    // 重新加载密钥（异步）
  "LogEnable": true,                   // 系统日志开关
  "SaveCache": true,                   // 立即保存缓存
  "Resources": "/v1/chat/completions, /v1/embeddings",  // 资源白名单
  "LevelMapper": "gpt-4*=2, claude*=3",                 // Level 路由映射
  "ModelMapper": "gpt-3.5*=gpt-4o-mini, o*=gpt-4o",     // 模型映射（级联更新）
  "ModelFailover": "gpt-4o=gpt-4o-mini|gpt-4-turbo",   // 模型故障转移
  "ModelLimits": {                                       // 模型限速（级联更新）
    "gpt-4o": {"rpm": 30, "tpm": 90000}
  },
  "DelKeys": true                      // 删除所有休眠密钥
}

字段说明：

字段	类型	作用范围	说明
`LoadKeys`	boolean	Owner	重新加载该主账户的所有密钥（异步后台执行）
`LogEnable`	boolean	系统级	系统级日志开关（影响所有 Owner）
`SaveCache`	boolean	Owner	立即持久化用户缓存到 Redis
`Resources`	string	Owner	更新 Owner 的资源白名单
`ModelMapper`	string	级联	模型映射规则，自动同步到所有后代用户
`LevelMapper`	string	系统级	Level 路由规则（所有后代用户共享 Owner 的配置）
`ModelFailover`	string	Owner	模型故障转移策略
`ModelLimits`	object/string	级联	模型级限速，自动同步到所有后代用户
`DelKeys`	boolean	Owner	删除所有休眠密钥并恢复可用

ModelMapper 级联更新规则：

支持以下操作语法：

model1=target - 添加/更新映射
-model1 - 删除映射
-model1, model2=target - 组合操作

示例：

# 1. 基础配置更新
curl -X POST https://api.xaixapi.com/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ModelMapper": "gpt-3.5*=gpt-4o-mini, o*=gpt-4o",
    "LevelMapper": "gpt-4*=2, claude*=3"
  }'

# 2. 批量更新模型限速（影响所有后代用户）
curl -X POST https://api.xaixapi.com/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ModelLimits": {
      "gpt-4o": {"rpm": 30, "tpm": 90000},
      "claude-3-opus": {"rpm": 20, "tpm": 60000}
    }
  }'

# 3. 删除模型映射（级联删除所有后代用户的对应映射）
curl -X POST https://api.xaixapi.com/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ModelMapper": "-gpt-3.5*"
  }'

# 4. 清空模型限速
curl -X POST https://api.xaixapi.com/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ModelLimits": "*"
  }'

# 5. 重新加载密钥并保存缓存
curl -X POST https://api.xaixapi.com/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "LoadKeys": true,
    "SaveCache": true
  }'

# 6. 删除所有休眠密钥
curl -X POST https://api.xaixapi.com/x-conf \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"DelKeys": true}'

响应示例：

{
  "LoadKeys": "true",
  "ModelMapper": {
    "gpt-3.5*": "gpt-4o-mini",
    "o*": "gpt-4o"
  },
  "LevelMapper": {
    "gpt-4*": 2,
    "claude*": 3
  },
  "ModelLimits": {
    "gpt-4o": {
      "rpm": 30,
      "tpm": 90000
    }
  }
}

配置作用范围：

系统级配置（所有后代用户共享）：

LevelMapper - Level 路由规则，所有后代用户直接使用 Owner 的配置，无需同步

级联更新配置（自动传播到所有后代用户）：

ModelMapper - 后代用户的 ModelMapper 会继承新的映射规则
ModelLimits - 后代用户的 ModelLimits 会继承新的限速配置

注意事项：

级联更新是累加式的，不会删除用户自定义的其他映射
删除操作（如 -model）也会级联删除所有后代用户的对应映射
Root 用户的更新会影响所有非 Root 用户（Gear > 0）
LevelMapper 是系统级共享配置，后代用户无法自定义覆盖
配置更新后会自动刷新相关的故障转移策略

2. 系统配置 API

管理主账户级别的系统配置，包括模型映射、Level 路由、资源白名单、模型限速、定价覆盖等。

2.1 获取配置

端点： GET /x-config

curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/x-config | jq .

响应示例：

{
  "success": true,
  "oid": 1,
  "configs": {
    "MODEL_MAPPER": {"gpt-3.5*": "gpt-4o-mini"},
    "LEVEL_MAPPER": {"gpt-4*": 2, "claude*": 3},
    "SWITCH_OVER": {"1": 2},
    "RESOURCES": {"/v1/chat/completions": {}, "/v1/embeddings": {}},
    "MODEL_LIMITS": {"gpt-4o": {"rpm": 30, "tpm": 90000}},
    "EMAIL_SMTP": "smtp.gmail.com",
    "EMAIL_TLS": true,
    "PRICING": "{\"ChatPricing\":{\"gpt-4o\":{\"InputText\":3.5}}}"
  }
}

2.2 更新配置

端点： PUT /x-config 或 POST /x-config

Content-Type： application/json

可配置键：

配置键	说明	格式	示例
`MODEL_MAPPER`	模型映射	`原模型=目标模型`	`gpt-3.5=gpt-4o-mini, o=gpt-4o`
`LEVEL_MAPPER`	Level 映射	`模型=Level编号`	`gpt-4=2, claude=3`
`SWITCH_OVER`	Level 故障切换	`主Level=备Level`	`1=2, 2=3`
`RESOURCES`	资源白名单	逗号/空白分隔	`/v1/chat/completions, /v1/embeddings`
`MODEL_LIMITS`	模型限速	JSON 字符串/对象	见下方
`PRICING`	定价覆盖	JSON 字符串	见 2.3 节
`XAI_MAIL`	系统通知邮箱	字符串	`[email protected]`
`EMAIL_SMTP`	SMTP 服务器	字符串	`smtp.gmail.com`
`EMAIL_PORT`	SMTP 端口	字符串	`587`
`EMAIL_AUTH`	认证邮箱	字符串	`[email protected]`
`EMAIL_PASS`	邮箱密码	字符串	`password`
`EMAIL_TLS`	启用 TLS	字符串	`true`

示例：

curl -X PUT https://api.xaixapi.com/x-config \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "MODEL_MAPPER": "gpt-3.5*=gpt-4o-mini, o*=gpt-4o",
    "LEVEL_MAPPER": "gpt-4*=2, claude*=3",
    "SWITCH_OVER": "1=2, 2=3",
    "RESOURCES": "/v1/chat/completions, /v1/embeddings",
    "MODEL_LIMITS": "{\"gpt-4o\": {\"rpm\": 30, \"tpm\": 90000}}",
    "EMAIL_SMTP": "smtp.gmail.com",
    "EMAIL_TLS": "true"
  }'

MODEL_LIMITS 详解：

{
  "MODEL_LIMITS": {
    "gpt-4o": {"rpm": 30, "tpm": 90000},
    "claude-3-opus": {"rpm": 20, "tpm": 60000}
  }
}

或作为 JSON 字符串：

{
  "MODEL_LIMITS": "{\"gpt-4o\": {\"rpm\": 30, \"tpm\": 90000}}"
}

格式说明：

MODEL_MAPPER / LEVEL_MAPPER / SWITCH_OVER 为 k=v 逗号分隔格式，两侧自动 trim
RESOURCES 支持逗号/空白分隔，每项校验为合法路径
MODEL_LIMITS 可为 JSON 字符串或对象，对象模式支持增量覆盖

2.3 定价覆盖（PRICING）

主账户可通过 PRICING 配置键覆盖系统默认定价，仅需填写与默认不同的"差量"。

数据结构：

{
  "ChatPricing": {
    "<model>": {
      "InputText": 0,      // USD/1M tokens
      "OutputText": 0,
      "CachedText": 0,
      "CacheWrite": 0,
      "ReasonText": 0,
      "InputAudio": 0,
      "OutputAudio": 0,
      "InputImage": 0,
      "OutputImage": 0,
      "Rates": 1
    }
  },
  "ImgPricing": {
    "<model>": {
      "Call": 0,
      "Rates": 1,
      "Sizes": {"1024x1024": 0}
    }
  },
  "AudioPricing": {
    "<model>": {
      "Input": 0,
      "Output": 0,
      "Call": 0,
      "Rates": 1
    }
  },
  "RerankPricing": {
    "<model>": {"Input": 0, "Call": 0, "Rates": 1}
  },
  "CallPricing": {
    "<model>": {"Call": 0, "Rates": 1}
  },
  "FineTuningPricing": {
    "<base-model>": {"InputText": 0, "OutputText": 0, "Rates": 1}
  }
}

字段说明：

InputText / OutputText - USD/百万 tokens（输入/输出文本）
CachedText / CacheWrite - USD/百万 tokens（缓存读取/写入）
ReasonText - USD/百万 tokens（推理过程，如 o1 系列）
InputAudio / OutputAudio - USD/百万等价 tokens（音频）
InputImage / OutputImage - USD/百万等价 tokens（图像）
Rates - 模型级倍率（默认 1）
Call - USD/次（按调用计费）
Sizes - 图像尺寸单价（如 "1024x1024": 0.05）

示例：最小差量覆盖

my_pricing.json:

{
  "ChatPricing": {
    "gpt-4o": {
      "InputText": 3.5,
      "OutputText": 12,
      "Rates": 1
    }
  }
}

写入命令：

curl -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT https://api.xaixapi.com/x-config \
  -d "{\"PRICING\": $(jq -Rs . < my_pricing.json)}"

读取当前定价覆盖：

curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/x-config | jq -r '.configs.PRICING'

校验与限制：

JSON 大小 ≤ 128 KB
条目总数 ≤ 1024
拒绝未知字段
所有数值必须有限且非负

生效逻辑：

优先使用 Owner 覆盖值
未覆盖部分回退到系统默认（pricing.json）
与用户级 Rates / Factor 系数叠加计算

2.4 删除配置项

端点： DELETE /x-config

删除后恢复为系统默认值。

请求体：

{
  "keys": ["MODEL_MAPPER", "PRICING"]
}

示例：

# 清空定价覆盖，恢复系统默认
curl -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -X DELETE https://api.xaixapi.com/x-config \
  -d '{"keys": ["PRICING"]}'

3. 广播通知 API

发布系统级或定向用户通知，在 Manage 控制台横幅显示。

3.1 创建系统新闻

端点： POST /x-news

请求体：

{
  "title": "系统维护通知",
  "content": "系统将于明日凌晨 2:00-4:00 进行维护，期间服务可能中断。"
}

字段说明：

title - 通知标题（必填，最多 100 字符）
content - 通知内容（必填，最多 1000 字符）

示例：

curl -X POST https://api.xaixapi.com/x-news \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "系统维护通知",
    "content": "系统将于明日凌晨 2:00-4:00 进行维护。"
  }'

3.2 创建定向新闻

端点： POST /x-news/{target}

向指定用户或 DNA 路径下的用户发布通知。

路径参数：

{target} - 用户 ID、用户名、邮箱或 DNA 路径

示例：

# 向指定用户发送通知
curl -X POST https://api.xaixapi.com/x-news/42 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "账户余额提醒",
    "content": "您的账户余额不足 10 美元，请及时充值。"
  }'

# 向 DNA 路径下所有用户发送
curl -X POST https://api.xaixapi.com/x-news/.1.42. \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "团队通知",
    "content": "针对您所在团队的重要通知..."
  }'

3.3 删除新闻

端点： DELETE /x-news

请求体：

{
  "id": 123
}

示例：

curl -X DELETE https://api.xaixapi.com/x-news \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": 123}'

3.4 获取新闻列表

端点： GET /dashboard/news

详见 Manage API 参考。

使用场景

场景 1：添加标准 Provider

# 1. 添加 OpenAI Provider
curl -X POST https://api.xaixapi.com/x-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "sk-live-...",
    "Name": "OpenAI 主池",
    "Level": 1,
    "Provider": "https://api.openai.com",
    "Status": true
  }'

# 2. 系统自动补全 LEVEL_MAPPER（gpt* → Level 1）
# 3. 验证配置
curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/x-conf | jq '.LevelMapper'

场景 2：配置模型映射和限速

# 1. 设置模型映射（将 gpt-3.5 请求转发到 gpt-4o-mini）
# 2. 设置 Level 映射（gpt-4* 使用 Level 2）
# 3. 设置模型限速（gpt-4o 限制为 30 RPM）
curl -X PUT https://api.xaixapi.com/x-config \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "MODEL_MAPPER": "gpt-3.5*=gpt-4o-mini, o*=gpt-4o",
    "LEVEL_MAPPER": "gpt-4*=2, claude*=3",
    "MODEL_LIMITS": "{\"gpt-4o\": {\"rpm\": 30, \"tpm\": 90000}}"
  }'

场景 3：配置 Azure OpenAI

curl -X POST https://api.xaixapi.com/x-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "your-azure-key",
    "Name": "Azure GPT-4",
    "Level": 2,
    "Provider": "https://your-resource.openai.azure.com",
    "Status": true,
    "Config": {
      "provider_type": "azure",
      "model_mapping": {
        "gpt-4o": "gpt-4-deployment",
        "gpt-3.5*": "gpt35-turbo"
      },
      "api_versions": {
        "chat": "2025-01-01-preview"
      }
    }
  }'

场景 4：定制定价并发布通知

# 1. 创建定价差量文件
cat > my_pricing.json <<EOF
{
  "ChatPricing": {
    "gpt-4o": {"InputText": 3.5, "OutputText": 12}
  }
}
EOF

# 2. 上传定价覆盖
curl -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT https://api.xaixapi.com/x-config \
  -d "{\"PRICING\": $(jq -Rs . < my_pricing.json)}"

# 3. 发布系统通知
curl -X POST https://api.xaixapi.com/x-news \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "定价调整通知",
    "content": "GPT-4o 模型定价已更新，详情请查看账单页面。"
  }'

最佳实践

Provider 管理

按服务商分组 - 将同一服务商的密钥放入同一 Level
设置主备切换 - 使用 SWITCH_OVER 配置关键 Level 的备份
定期检查休眠密钥 - 使用 GET /x-conf 查看休眠状态
合理设置 Level - 按成本、速度、可靠性划分不同 Level

配置管理

模型映射用途 - 用于平滑迁移或成本优化（如将 o1 请求映射到 gpt-4o）
谨慎修改 RESOURCES - 错误配置可能导致 API 无法访问
MODEL_LIMITS 限制 - 为昂贵模型设置严格的速率限制
定期备份配置 - 使用 GET /x-config 导出配置

定价覆盖

差量原则 - 仅覆盖与系统默认不同的部分
版本控制 - 将定价 JSON 保存到文件并纳入版本控制
测试验证 - 更新后通过 /dashboard/bill 验证计费是否正确
文档记录 - 记录覆盖原因和时间，便于后续审计

通知管理

重要通知优先 - 系统级通知用于关键信息
内容简洁明了 - 避免过长的通知内容
及时清理过期通知 - 删除过期或无效的通知

Admin API 参考

基础信息

端点总览

核心概念详解

ModelMapper（模型映射）

LevelMapper（Level 映射）

ModelFailover（模型故障转移）

SwitchOver（Level 切换）

ModelLimits（模型限速）

Resources（资源白名单）

Provider 密钥管理

配置优先级总结

1. Provider 密钥管理 API

1.1 查询密钥

1.2 新增密钥

配置类型详解

1.3 更新密钥

1.4 删除密钥

1.5 配置与观测

1.6 批量配置管理

2. 系统配置 API

2.1 获取配置

2.2 更新配置

2.3 定价覆盖（PRICING）

2.4 删除配置项

3. 广播通知 API

3.1 创建系统新闻

3.2 创建定向新闻

3.3 删除新闻

3.4 获取新闻列表

使用场景

场景 1：添加标准 Provider

场景 2：配置模型映射和限速

场景 3：配置 Azure OpenAI

场景 4：定制定价并发布通知

最佳实践

Provider 管理

配置管理

定价覆盖

通知管理

相关文档