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`	查看密钥、映射和休眠状态
系统配置	`GET/PUT/DELETE /x-config`	管理模型映射、Level 路由、限速等
广播通知	`POST/DELETE /x-news`	发布系统或定向通知

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 .

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 参考

基础信息

端点总览

1. Provider 密钥管理 API

1.1 查询密钥

1.2 新增密钥

配置类型详解

1.3 更新密钥

1.4 删除密钥

1.5 配置与观测

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 管理

配置管理

定价覆盖

通知管理

相关文档