Provider Key API

Provider Key API 用于管理模型服务所需的上游凭证，仅主账号管理员可以调用。

export BASE_URL="https://api.xairouter.com"
export API_KEY="sk-Xvs..."

接口一览

方法与路径	说明
`GET /x-keys?fields=summary`	查询 Provider Keys
`GET /x-keys/{id}?fields=summary`	查询指定 Key
`POST /x-keys`	新增 Key
`PUT /x-keys/{id}`	更新 Key
`DELETE /x-keys/{id}`	删除 Key
`POST /x-keys/{id}/sleep`	暂停 Key
`POST /x-keys/{id}/wake`	恢复 Key

查询 Keys

推荐始终使用 fields=summary，响应不会返回完整 Provider Secret 或敏感配置。

curl "$BASE_URL/x-keys?fields=summary&page=1&size=20" \
  -H "Authorization: Bearer $API_KEY"

可选过滤参数：

参数	说明
`id`	Key ID
`level`	Key 分组
`provider`	Provider URL
`page` / `size`	分页

摘要响应：

[
  {
    "ID": 42,
    "Name": "OpenAI Primary",
    "Level": 1,
    "Provider": "https://api.openai.com",
    "PartialKey": "...last-20-characters",
    "NoSleep": false,
    "Status": true,
    "Sleeping": false,
    "CreatedAt": "2026-07-18T08:00:00Z"
  }
]

分页信息通过 X-Total-Count、X-Total-Pages、X-Page 和 X-Per-Page 响应头返回。

新增 Key

POST /x-keys

curl -X POST "$BASE_URL/x-keys" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "OpenAI Primary",
    "Level": 1,
    "Provider": "https://api.openai.com",
    "SecretKey": "sk-provider-secret-xxxxxxxx",
    "Status": true,
    "NoSleep": false,
    "config": {"provider_type": "standard"}
  }'

字段	必填	说明
`Provider`	是	上游 HTTPS Base URL；不能指向当前 Router 自身
`SecretKey`	是	上游服务凭证，至少 20 个字符
`Name`	否	便于识别的备注名称
`Level`	是	Key 分组，使用正整数
`Status`	是	是否启用；正常使用时设为 `true`
`NoSleep`	否	是否禁止系统自动休眠该 Key
`config`	否	Provider 类型及云平台所需的附加参数

标准 OpenAI、Anthropic 等 Bearer/API-Key 服务通常使用 provider_type: standard。Azure、AWS、Vertex 等云平台所需字段以控制台表单为准；不要在日志中记录 SecretKey 或敏感 config。

更新 Key

PUT /x-keys/{id}

只提交需要修改的字段：

curl -X PUT "$BASE_URL/x-keys/42" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "OpenAI Production",
    "Status": true,
    "NoSleep": true
  }'

如需轮换上游凭证，提交新的 SecretKey。更新成功后，Router 会刷新相应的 Key 缓存与调度状态。

暂停与恢复

curl -X POST "$BASE_URL/x-keys/42/sleep" \
  -H "Authorization: Bearer $API_KEY"

curl -X POST "$BASE_URL/x-keys/42/wake" \
  -H "Authorization: Bearer $API_KEY"

sleep 立即将 Key 移出正常调度。
wake 清除休眠状态并安排恢复。
若希望长期停用，请通过更新接口设置 Status: false。

删除 Key

curl -X DELETE "$BASE_URL/x-keys/42" \
  -H "Authorization: Bearer $API_KEY"

删除操作不可撤销。删除前应确认同一 Level 仍有可用 Key，避免该分组无可用上游。

安全建议

使用 fields=summary 查询列表。
每个环境使用独立的 Provider Key。
定期轮换上游凭证，并及时停用不再使用的 Key。
不要把 Provider Secret 写入前端代码、URL、日志或工单。
为云平台凭证设置最小权限和预算限制。

Provider Key API

Provider Key API

接口一览

查询 Keys

新增 Key

更新 Key

暂停与恢复

删除 Key

安全建议

相关文档