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 对象
| 字段 | 说明 |
|---|---|
ID | Key ID |
Name | 备注;也参与自动 Level 映射的服务商识别 |
Level | 所属 Key 池分组,默认 1 |
Provider | 上游基础 URL,例如 https://api.openai.com;可带路径前缀 |
SecretKey | 上游 Key 明文(仅 full 模式返回) |
PartialKey | 上游 Key 的最后 20 个字符 |
Config | 服务商专属配置,见下文(仅 full 模式返回) |
ProviderType | Config.provider_type 的值(为空时省略) |
NoSleep | true 时不参与自动休眠 |
Status | true 启用,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 | 精确匹配 |
provider | Provider URL 子串匹配,例如 provider=api.openai.com |
page、size | 分页,单页最多 8192 条 |
fields | summary(或 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、未设置 NoSleep | KEY_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.)。
错误
| 状态码 | 正文 |
|---|---|
400 | Provider 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. |
403 | Only account owner can access this endpoint、Provider ... is not allowed (self-reference) |
404 | Key not found. |
409 | Disabled key cannot be manually slept.、Key is not sleeping. |
500 | Failed to decrypt key(请使用所有者本人的 Key) |
安全建议
- 为不同服务商、环境或成本档位使用不同 Level,便于独立切换与观察。
- 只授权所有者 Key 访问这些接口;所有者 Key 应存放在服务端或密钥管理系统中。
- 查询时使用
fields=summary。full模式、GET /x-conf的休眠与禁用列表都会返回上游 Key 明文。 - 定期轮换上游 Key:
PUT /x-keys/{id}更新SecretKey即可,无需重建。