Admin API 参考

本文档基于当前后端代码（api/main.go + api/handler/*.go）整理，仅包含对外公开的 Admin 接口。

基础信息

Base URL：https://api.xaicontrol.com
认证：Authorization: Bearer sk-Xvs...
权限：Owner 角色可访问本页全部端点

export BASE_URL="https://api.xaicontrol.com"

端点总览

模块	方法	端点	说明
密钥管理	GET	`/x-keys`	查询密钥（支持筛选/分页）
密钥管理	GET	`/x-keys/{id}`	筛选
密钥管理	POST	`/x-keys`	新增密钥
密钥管理	PUT/POST	`/x-keys/{id}`	更新密钥
密钥管理	DELETE	`/x-keys/{id}`	删除密钥
配置观测	GET	`/x-conf`	获取 Owner 配置与密钥状态摘要
配置批量	POST	`/x-conf`	批量更新配置
配置 CRUD	GET/PUT/POST/DELETE	`/x-config`	Owner 配置读写删
用户详情	GET	`/x-info?user={id或name}`	查看指定用户详细信息

1) 密钥管理（`/x-keys`）

1.1 查询密钥

GET /x-keys

查询参数：

id：按 Key ID
level：按 Level
provider：按 Provider
page、size：分页

路径筛选：

/x-keys/123
/x-keys/L2
/x-keys/api.openai.com

响应为数组；分页信息在 Header： X-Total-Count、X-Page、X-Per-Page、X-Total-Pages。

curl -H "Authorization: Bearer $API_KEY" \
  "${BASE_URL}/x-keys?page=1&size=20&level=2"

1.2 新增密钥

POST /x-keys

{
  "Name": "OpenAI 主池",
  "Level": 1,
  "Provider": "https://api.openai.com",
  "SecretKey": "sk-xxxxxxxxxxxxxxxxxxxx",
  "Status": true,
  "config": {
    "provider_type": "standard"
  }
}

1.3 更新密钥

PUT /x-keys/{id} 或 POST /x-keys/{id}

可更新字段：Name、Level、Provider、SecretKey、Status、config。

1.4 删除密钥

DELETE /x-keys/{id}

2) 批量配置（`/x-conf`）

2.1 获取配置

GET /x-conf

返回核心字段：

Resources
LevelMapper
ModelMapper
ModelFailover
ModelLimits
SwitchOver
SleepingKeys
DisabledKeys
UserMinBalance
UserApiBalance

2.2 批量更新

POST /x-conf

常用字段：

Resources
LevelMapper
ModelMapper
ModelFailover
ModelLimits

ModelLimits 支持对象或字符串命令（如 * 清空、-model 删除）。

3) 配置 CRUD（`/x-config`）

3.1 获取配置

GET /x-config

返回 configs 对象，包含 MODEL_MAPPER、MODEL_FAILOVER、LEVEL_MAPPER、SWITCH_OVER、RESOURCES、MODEL_LIMITS、PRICING 等。

3.2 更新配置

PUT /x-config 或 POST /x-config

请求体按 map[string]string 解析，建议所有值使用字符串。

3.3 删除配置键

DELETE /x-config

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

4) 用户详情（`/x-info`）

GET /x-info?user={id或name}

user 必填
仅允许查询当前 Owner 体系下用户
返回余额、限额、ACL、映射与用量等详情

本页仅包含公开管理接口，内部维护/订正用途接口不对外开放。