密钥管理 API

本页覆盖与密钥(Key)相关的所有端点，包括新增、更新、查询、删除与辅助工具。

提示：所有接口均需携带 Authorization: Bearer sk-Xvs…。

基础 URL：https://api.xaixapi.com

—

概览

列表/筛选：GET /x-keys、GET /x-keys/{id|L{n}|{provider}}
新增：POST /x-keys
更新：PUT /x-keys/{id}（等价 POST /x-keys/{id}）
删除：DELETE /x-keys/{id}
生成随机 API Key：GET /x-gkey
对称加解密工具（平台级密钥）：GET /x-ekey/{plain}、GET /x-dkey/{cipher}
查看密钥/映射/休眠情况：GET /x-conf

—

查询与筛选

GET /x-keys 支持查询参数：
- id 按密钥 ID
- level 按 Level（整数）
- provider 按 Provider（完整或特征，如 https://api.openai.com）
- page、size 分页（可选）
路径式筛选：
- GET /x-keys/{id} 按 ID 获取
- GET /x-keys/L{n} 按 Level 获取（如 L2）
- GET /x-keys/{provider} 按 Provider 获取（如 api.anthropic.com）

示例：

# 所有密钥（简要）
curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/x-keys

# Level=2 的密钥
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.xaixapi.com/x-keys?level=2"

# 指定 Provider 的密钥
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.xaixapi.com/x-keys?provider=https://api.openai.com"

—

新增密钥

端点：POST /x-keys
仅主账户或有权限的父级可添加；密钥将归属当前主账户（OID）。

请求体（常用字段）：

{
  "SecretKey": "sk-...",         // 上游服务商密钥（必填，至少20字符）
  "Name": "生产环境-OpenAI",      // 可选，展示名
  "Level": 1,                    // 负载池级别，用于路由/故障转移（必填）
  "Provider": "https://api.openai.com", // 上游 API Host/标识（必填，需为有效URL）
  "Status": true,                // 启用/禁用（默认 true）
  "Config": {                    // 可选，按 provider_type 定制
    "provider_type": "standard"  // 配置类型：standard/azure/vertex
  }
}

Config 字段详解

Config 字段用于配置特殊类型的 Provider（如 Azure OpenAI、Google Vertex AI）。根据 provider_type 不同，需要提供不同的配置参数。

1. 标准配置（Standard）

适用于标准 OpenAI 兼容的 Provider（OpenAI、Anthropic、Mistral、DeepSeek 等）。

{
  "SecretKey": "sk-...",
  "Name": "OpenAI 生产",
  "Level": 1,
  "Provider": "https://api.openai.com",
  "Status": true,
  "Config": {
    "provider_type": "standard"  // 可省略，默认为 standard
  }
}

2. Azure OpenAI 配置

适用于 Azure OpenAI Service。

{
  "SecretKey": "your-azure-api-key",
  "Name": "Azure OpenAI",
  "Level": 2,
  "Provider": "https://your-resource.openai.azure.com",
  "Status": true,
  "Config": {
    "provider_type": "azure",
    "model_mapping": {
      "gpt-4o": "gpt-4-deployment",      // 模型名 -> Deployment 名
      "gpt-4": "my-gpt4-deployment",
      "gpt-3.5*": "gpt35-turbo",         // 支持通配符
      "*": "default-deployment"          // 默认部署
    },
    "api_versions": {                    // 可选，不同端点的 API 版本
      "chat": "2025-01-01-preview",
      "embeddings": "2024-02-01",
      "responses": "2025-04-01-preview",
      "audio": "2025-03-01-preview",
      "images": "2025-04-01-preview"
    }
  }
}

Azure 配置说明：

Provider 应填写 Azure endpoint，如 https://your-resource.openai.azure.com
model_mapping 将标准模型名映射到 Azure 的 deployment 名称
api_versions 为各端点指定 API 版本（可选，留空使用系统环境变量）

3. Google Vertex AI 配置

适用于 Google Cloud Vertex AI。

{
  "SecretKey": "sk-placeholder-51chars-xxxxxxxxxxxxxxxxxxxxxxxx",  // Vertex 仍需51字符占位
  "Name": "Vertex AI",
  "Level": 3,
  "Provider": "https://us-central1-aiplatform.googleapis.com",   // 占位 URL
  "Status": true,
  "Config": {
    "provider_type": "vertex",
    "base_url": "https://us-central1-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}",
    "project_id": "my-gcp-project",
    "client_email": "[email protected]",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----\n"
  }
}

Vertex AI 配置说明：

Provider 和 SecretKey 作为占位符，需符合格式要求
base_url 包含项目和区域信息
project_id Google Cloud 项目 ID
client_email 服务账号邮箱
private_key 服务账号私钥（PEM 格式，系统会自动清理空格并加密存储）

行为说明：

Config 中的敏感字段（如 Vertex private_key）会在入库前自动清理并加密存储
新增成功后，系统会尝试基于 Provider 自动补全 LEVEL_MAPPER 中的模型匹配项（智能模式与相似度匹配），便于请求自动路由到该 Level
Provider URL 不能自引用（不能指向当前系统）
系统会自动刷新 Redis 缓存和内存结构

标准 Provider 示例：

curl -X POST https://api.xaixapi.com/x-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "sk-live-...",
    "Name": "OpenAI 主池",
    "Level": 1,
    "Provider": "https://api.openai.com",
    "Status": true
  }'

Azure OpenAI 示例：

curl -X POST https://api.xaixapi.com/x-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "your-azure-key",
    "Name": "Azure GPT-4",
    "Level": 2,
    "Provider": "https://your-resource.openai.azure.com",
    "Status": true,
    "Config": {
      "provider_type": "azure",
      "model_mapping": {
        "gpt-4o": "gpt-4-deployment",
        "gpt-3.5*": "gpt35-turbo"
      }
    }
  }'

Vertex AI 示例：

curl -X POST https://api.xaixapi.com/x-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "SecretKey": "sk-placeholder-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Name": "Vertex Gemini",
    "Level": 3,
    "Provider": "https://us-central1-aiplatform.googleapis.com",
    "Status": true,
    "Config": {
      "provider_type": "vertex",
      "base_url": "https://us-central1-aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1",
      "project_id": "my-gcp-project",
      "client_email": "[email protected]",
      "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n"
    }
  }'

—

更新密钥

端点：PUT /x-keys/{id}（兼容 POST）
可更新字段：Name、Level、Status、Provider、Config 等。

示例：

curl -X PUT https://api.xaixapi.com/x-keys/123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Level": 2, "Status": true}'

—

删除密钥

端点：DELETE /x-keys/{id}

curl -X DELETE https://api.xaixapi.com/x-keys/123 \
  -H "Authorization: Bearer $API_KEY"

—

工具端点

生成随机 API Key：GET /x-gkey

curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/x-gkey

对称加密/解密（平台级，便于导入/备份敏感字段）：
- 加密：GET /x-ekey/{plain} → { "EncryptedKey": "..." }
- 解密：GET /x-dkey/{cipher} → { "DecryptedKey": "..." }

—

配置与观测

GET /x-conf 返回与当前主账户相关的：
- Resources 已允许的 API 路径
- LevelMapper/ModelMapper/ModelLimits/SwitchOver
- 正在休眠的密钥列表（含剩余休眠时间）
- 被禁用的密钥列表
- UserMinBalance/UserApiBalance 关键阈值

curl -H "Authorization: Bearer $API_KEY" \
  https://api.xaixapi.com/x-conf | jq .

—

最佳实践

将不同 Provider/费用层放入不同 Level，结合 LEVEL_MAPPER 做模型到 Level 的映射。
对易受限的上游设置多个密钥，利用系统轮询与自动休眠机制提升成功率。
使用 MODEL_LIMITS 控制昂贵模型的调用速率，避免突发费用。