常见场景
以下示例默认已设置:
export XSI_BASE_URL="https://api.example.com"
export OWNER_KEY="sk-Xvs..." # 租户所有者 Key:管理上游与租户配置
export ADMIN_KEY="sk-Xvs..." # 管理者 Key:管理子账号(可与 OWNER_KEY 相同)多上游与容灾
目标:OpenAI 主用,Azure OpenAI 备用;Claude 走 Anthropic;上游出错时自动切换。
# 1. 录入上游 Key:OpenAI → Level 1,Anthropic → Level 2,Azure → Level 4
curl -X POST "$XSI_BASE_URL/x-keys" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"Name": "openai-a", "Level": 1, "Provider": "https://api.openai.com", "SecretKey": "sk-proj-..."}'
curl -X POST "$XSI_BASE_URL/x-keys" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"Name": "openai-b", "Level": 1, "Provider": "https://api.openai.com", "SecretKey": "sk-proj-..."}'
curl -X POST "$XSI_BASE_URL/x-keys" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"Name": "anthropic", "Level": 2, "Provider": "https://api.anthropic.com", "SecretKey": "sk-ant-..."}'
curl -X POST "$XSI_BASE_URL/x-keys" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"Name": "azure", "Level": 4, "Provider": "https://my-res.openai.azure.com", "SecretKey": "...",
"config": {"provider_type": "azure", "model_mapping": {"gpt-6.2-sol": "gpt-prod"}}}'
# 2. 路由与切换
curl -X PUT "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"LEVEL_MAPPER": "gpt*=1, claude*=2", "SWITCH_OVER": "1=4"}'效果:同组的两个 OpenAI Key 轮询并互为重试;单个 Key 返回 STATUS_CODES 中的状态(默认 429、401、402、408、503、524)时自动休眠;整组持续失败时,Gear > 0 的账号临时切到 Level 4,1 小时后自动恢复。
为团队分发额度
# 为研发组创建子账号,初始额度 2000 元,并允许其再创建子账号
curl -X POST "$XSI_BASE_URL/x-users" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"Email": "[email protected]", "Name": "rd-team", "CreditGranted": 2000, "UserLimit": 100}'
# 追加额度,90 天有效
curl -X PUT "$XSI_BASE_URL/x-users/rd-team" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"CreditGranted": 500, "Days": 90}'
# 为全部 Level 2 的后代各发放 50 元(先预览)
curl -X POST "$XSI_BASE_URL/x-users/batch-credit" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"CreditGranted": 50, "Filters": {"level": 2}, "DryRun": true}'预算与限速
额度与限速只对 Role 2(严格)或 Role 3(订阅)账号生效,Role 由租户所有者设置:
curl -X PUT "$XSI_BASE_URL/x-users/rd-team" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"Role": 2, "DailyLimit": 200, "HardLimit": 3000, "RPM": 120, "TPM": 2000000}'为高成本模型设置全租户的模型级限额(模型名须为上游模型名的精确值):
curl -X PUT "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"MODEL_LIMITS": "{\"claude-opus-5-5\": {\"rpm\": 20, \"tpd\": 50000000}}"}'限制访问范围
curl -X PUT "$XSI_BASE_URL/x-users/42" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{
"AllowModels": "-*,+gpt-6*,+claude-sonnet-5-5",
"AllowIPs": "-*,+203.0.113.0/24,+10.0.0.5",
"Resources": "-*,+/v1/chat/completions,+/v1/responses,+/v1/embeddings"
}'-*,+a,+b 表示把范围完整替换为列出的项;不带前缀的列表会追加到已有范围。把模型白名单递归应用到整条分支(先预览):
curl -X PUT "$XSI_BASE_URL/x-users/rd-team" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"Scope": "tree", "AllowModels": "-*,+gpt-6*,+claude-sonnet-5-5", "DryRun": true}'模型平滑升级
为应用提供稳定的别名,升级时只改映射。账号会缓存别名的解析结果,因此要让变更立即作用于已在使用别名的账号,请用 POST /x-conf 的 ModelMapper(同步到全部后代);PUT /x-config 只更新租户配置:
curl -X PUT "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"MODEL_MAPPER": "gpt-latest=gpt-6.2-sol, claude-latest=claude-sonnet-5-5"}'模型故障时自动降级到备用模型:
curl -X PUT "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"MODEL_FAILOVER": "claude-opus-5-5=claude-sonnet-5-5"}'自定义价格
覆盖已有模型或新增模型(必须写出 Rates):
curl -X PUT "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"PRICING": "{\"ChatPricing\": {\"qwen3-coder-local\": {\"InputText\": 1, \"OutputText\": 4, \"Rates\": 1}}}"}'
curl "$XSI_BASE_URL/x-pricing" -H "Authorization: Bearer $OWNER_KEY" | jq '.data[] | select(.custom)'接入自建模型
vLLM、SGLang、Ollama 等 OpenAI 兼容服务可直接作为 Provider:
curl -X POST "$XSI_BASE_URL/x-keys" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"Name": "vllm-local", "Level": 5, "Provider": "http://10.0.0.20:8000", "SecretKey": "local-token-at-least-20chars"}'
curl -X PUT "$XSI_BASE_URL/x-config" -H "Authorization: Bearer $OWNER_KEY" -H "Content-Type: application/json" \
-d '{"LEVEL_MAPPER": "gpt*=1, claude*=2, qwen3-coder-local=5"}'再按上一节为 qwen3-coder-local 设置价格,即可像其他模型一样调用、限额与计费。PUT /x-config 会整体替换 LEVEL_MAPPER,请写出完整映射。
API 分销
root(运营方)
├─ 渠道 A:Rates 1.0
│ └─ 客户 A1:Rates 1.3 ← 差价 30% 归渠道 A
└─ 渠道 B:Rates 1.1,Factor 0.9# 以渠道 A 的 Key 为客户创建账号,Rates 不低于渠道自身
curl -X POST "$XSI_BASE_URL/x-users" -H "Authorization: Bearer $CHANNEL_A_KEY" -H "Content-Type: application/json" \
-d '{"Email": "[email protected]", "CreditGranted": 1000, "Rates": 1.3}'渠道 A 为客户划转 1000 元额度时,自身扣减 1000 ÷ 1.3 × 1.0 ≈ 769.23 元。
查看用量与排行
curl "$XSI_BASE_URL/x-bill?days=30" -H "Authorization: Bearer $ADMIN_KEY" \
| jq '.usage_users[] | {name, total_credit_used, top_cost_model}'发布通知与轮换 Key
# 通知某个子账号
curl -X POST "$XSI_BASE_URL/x-news/42" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{"title": "额度提醒", "content": "本月额度已使用 80%。", "days": 7}'
# 轮换自己的 Key
curl -X POST "$XSI_BASE_URL/x-self" -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
-d "{\"confirm\": \"$(date +%F)-ROTATE-SELF\"}"