𝐙𝐀𝐈

Provider Key API

Provider Key API

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

export BASE_URL="https://api.zairouter.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"

可选过滤参数：

参数说明
idKey ID
levelKey 分组
providerProvider 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、日志或工单。
  • 为云平台凭证设置最小权限和预算限制。

相关文档

← 访问控制 (ACL)
ZAI Control →