Provider Key API

Provider Key API

Provider Key 是租户在上游服务商处持有的 API Key。XSI 按 Level 把 Key 分组成 Key 池,按模型把请求路由到对应的池。所有接口都要求调用者是租户所有者(ID == OID,root 也是所有者),并且只能看到和操作本租户的 Key;子账号调用返回 403 Only account owner can access this endpoint。

export XSI_BASE_URL="https://api.xsicontrol.com"   # 或你自己的 API 域名
export XSI_API_KEY="sk-Xvs..."                     # 租户所有者的 Key

上游 Key 以租户密钥加密存储,而租户密钥由所有者的 API Key 加密,因此这些接口必须使用所有者本人的 Key 调用。

接口一览

方法与路径说明
GET /x-keys列出 Key(支持过滤与分页)
GET /x-keys/{id}、/x-keys/L{level}、/x-keys/{provider 子串}按 ID、Level 或 Provider 过滤
POST /x-keys新增 Key
PUT /x-keys/{id}(或 POST)部分更新
DELETE /x-keys/{id}删除
POST /x-keys/{id}/sleep手动休眠 32 小时
POST /x-keys/{id}/wake唤醒休眠中的 Key

Key 对象

字段说明
IDKey ID
Name备注;也参与自动 Level 映射的服务商识别
Level所属 Key 池分组,默认 1
Provider上游基础 URL,例如 https://api.openai.com;可带路径前缀
SecretKey上游 Key 明文(仅 full 模式返回)
PartialKey上游 Key 的最后 20 个字符
Config服务商专属配置,见下文(仅 full 模式返回)
ProviderTypeConfig.provider_type 的值(为空时省略)
NoSleeptrue 时不参与自动休眠
Statustrue 启用,false 禁用
Sleeping、SleepMode是否休眠中;auto 或 manual
CreatedAt创建时间

查询 Key

curl "$XSI_BASE_URL/x-keys?fields=summary&level=1&page=1&size=50" \
  -H "Authorization: Bearer $XSI_API_KEY"
参数说明
id、level精确匹配
providerProvider URL 子串匹配,例如 provider=api.openai.com
page、size分页,单页最多 8192 条
fieldssummary(或 list、lite)只返回摘要;省略时为 full,返回上游 Key 明文与解密后的 Config
日常查询请始终使用 fields=summary,只在确需导出明文时使用 full。
  • 响应始终是数组,ID 不存在时返回 [];结果按 ID 升序。
  • 带过滤或分页参数时返回 X-Total-Count,分页时另有 X-Page、X-Per-Page、X-Total-Pages。
  • 路径写法 /x-keys/L2 按 Level 过滤,/x-keys/openai 按 Provider 子串过滤;路径写法不分页。

新增 Key

curl -X POST "$XSI_BASE_URL/x-keys" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "openai-main",
    "Level": 1,
    "Provider": "https://api.openai.com",
    "SecretKey": "sk-proj-..."
  }'
字段必填说明
Provider是http 或 https URL,必须包含主机;不能指向 XSI 自身
SecretKey是上游 Key,至少 20 个字符
Level否分组,省略或为 0 时为 1
Name否备注
NoSleep否免自动休眠
config否服务商专属配置
  • 新建的 Key 总是启用状态;如需禁用,创建后再 PUT {"Status": false}。
  • 同一个上游 Key 可以重复录入(例如放入多个 Level)。

响应:

{
  "Action": "add",
  "Key": {"ID": 12, "Name": "openai-main", "Level": 1, "Provider": "https://api.openai.com", "PartialKey": "...", "Status": true},
  "Message": "Key added successfully",
  "AutoMapping": {"added": ["gpt*", "o*"], "removed": []}
}

自动 Level 映射

新增或更新 Key 后,若该 Level 还没有任何 LEVEL_MAPPER 条目,XSI 会按服务商自动写入模型模式,例如 https://api.openai.com → gpt*、o*、chatgpt*、text-embedding*、tts*、whisper*;https://api.anthropic.com → claude*;https://api.x.ai → grok*;https://api.deepseek.com → deepseek*。服务商按 Provider 精确匹配(需逐字一致,不带结尾斜杠),其次按 Name 匹配。识别不出且这是租户唯一的 Level 时,写入 *=<Level>。写入结果出现在响应的 AutoMapping 中,可随时通过《租户配置 API》调整。

服务商配置 config

多数服务商只需 Provider 与 SecretKey:XSI 按 Provider 主机名自动选择路径映射与鉴权方式,支持的主机见《支持的服务商》。需要额外信息的服务商通过 config.provider_type 指定:

Azure OpenAI / Azure AI

{
  "Name": "azure-eastus",
  "Level": 3,
  "Provider": "https://my-resource.openai.azure.com",
  "SecretKey": "<azure-api-key>",
  "config": {
    "provider_type": "azure",
    "model_mapping": {"gpt-6.2-sol": "my-gpt-deployment", "text-embedding-3-*": "embed-deployment"},
    "api_versions": {"chat": "2025-04-01-preview", "responses": "preview"}
  }
}
  • model_mapping:模型名到 deployment 的映射,支持通配。
  • api_versions:按接口类型(chat、responses、embeddings、images、audio、realtime)指定 api-version;未配置时使用环境变量 AZURE_AI_APIVERSION_<TYPE>。
  • Provider 主机含 .azure.com 时按 Azure OpenAI 路径改写;否则按 Azure AI 推理接口(/models/chat/completions)。
  • 鉴权头为 api-key。

Google Vertex AI

{
  "Name": "vertex",
  "Level": 4,
  "Provider": "https://aiplatform.googleapis.com",
  "SecretKey": "vertex-service-account-placeholder",
  "config": {
    "provider_type": "vertex",
    "base_url": "https://aiplatform.googleapis.com/v1/projects/my-project/locations/global",
    "project_id": "my-project",
    "client_email": "[email protected]",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
  }
}
  • 四个字段均必填。XSI 用服务账号签发 JWT 换取访问令牌(缓存 59 分钟),private_key 加密存储。
  • SecretKey 字段仍须填写至少 20 个字符,可用占位值。

兼容 OpenAI Live 的上游

"provider_type": "openai-live" 允许非 api.openai.com 的 Key 承接 Live 会话。

其他 provider_type 取值没有特殊行为,按普通 Provider 处理。

更新 Key

curl -X PUT "$XSI_BASE_URL/x-keys/12" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Level": 2, "NoSleep": true}'
  • 可更新 Name、Level、Provider、SecretKey、NoSleep、Status、config,只修改请求中出现的字段。
  • config 为整体替换;传 {} 会清空配置。
  • "Status": true 同时唤醒休眠中的 Key;"Status": false 禁用并使其退出轮询。
  • 更新后同样会执行自动 Level 映射。

删除 Key

curl -X DELETE "$XSI_BASE_URL/x-keys/12" -H "Authorization: Bearer $XSI_API_KEY"

物理删除。删除前请确认同一 Level 中仍有可用 Key,并检查 LEVEL_MAPPER 中是否仍有指向该 Level 的条目。

休眠与唤醒

机制触发时长
自动休眠上游返回 STATUS_CODES 中的状态(默认 429,401,402,503,408,524),且该 Level 有多个 Key、Key 的 Level > 0、未设置 NoSleepKEY_BACK 分钟(默认 60)
手动休眠POST /x-keys/{id}/sleep固定 32 小时
唤醒POST /x-keys/{id}/wake,或 PUT {"Status": true}立即
自动禁用 / 删除上游返回 AUTO_DISABLE_KEY_STATUS / AUTO_DELETE_KEY_STATUS 中的状态(默认关闭)禁用直到手动启用;删除后需重新录入
  • Level 中只剩一个可用 Key 时不会自动休眠它,并会唤醒同组中自动休眠的 Key。
  • 自动禁用与自动删除不会作用于同一 Level 中最后一个启用的 Key。
  • 已禁用的 Key 不能手动休眠(409);未休眠的 Key 不能唤醒(409 Key is not sleeping.)。

错误

状态码正文
400Provider is required、Provider must be a valid URL、Secret key must be at least 20 characters long、config.provider_type must be a string、Invalid Key ID.
403Only account owner can access this endpoint、Provider ... is not allowed (self-reference)
404Key not found.
409Disabled key cannot be manually slept.、Key is not sleeping.
500Failed to decrypt key(请使用所有者本人的 Key)

安全建议

  • 为不同服务商、环境或成本档位使用不同 Level,便于独立切换与观察。
  • 只授权所有者 Key 访问这些接口;所有者 Key 应存放在服务端或密钥管理系统中。
  • 查询时使用 fields=summary。full 模式、GET /x-conf 的休眠与禁用列表都会返回上游 Key 明文。
  • 定期轮换上游 Key:PUT /x-keys/{id} 更新 SecretKey 即可,无需重建。

相关文档