Router API
Router API
XSI 是协议原生的路由器:它不把请求翻译成某种“统一格式”,而是保持每个上游协议的请求与响应语义,只在必要处改写模型名、路径与上游凭证。因此官方 SDK、Codex、Claude Code 等客户端只需替换 base_url 与 API Key。
export XSI_BASE_URL="https://api.xsicontrol.com" # 或你自己的 API 域名
export XSI_API_KEY="sk-Xvs..."请求如何被处理
每个模型请求依次经过以下步骤:
- 认证:解析调用方 Key,检查账号状态与认证失败频率。
- 账号准入:IP 白名单 → 账号状态、冻结、日/月额度、余额、账号级 RPM/TPM → 资源(路径)白名单。
- 模型解析:从请求体(或 URL)读取模型名,按
MODEL_MAPPER等规则映射为上游模型。 - 模型准入:模型白名单(
AllowModels)与模型级限额(MODEL_LIMITS)。 - 选择上游:按模型确定 Level(分组),在该组的 Key 池中按粘性会话或轮询选择一个 Key。
- 转发:改写路径与上游鉴权头后转发;上游返回可重试错误时,在向客户端写出任何字节之前自动换 Key 重试。
- 计量与结算:从响应(含 SSE 流)中旁路读取用量,按价格表结算。
OpenAI 兼容接口
除下文标注“本地处理”的路径外,XSI 会把任何路径与方法转发给选中 Key 的上游,因此上游支持的接口(如 /v1/batches、/v1/fine_tuning/*、/v1/vector_stores、/v1/completions)都可以直接使用。下表列出 XSI 有专门处理的接口:
| 能力 | 方法与路径 | 说明 |
|---|---|---|
| Chat Completions | POST /v1/chat/completions | 支持粘性会话 |
| Responses | POST /v1/responses | 支持粘性会话;也可通过 WebSocket 连接,见《WebSocket 与实时接口》 |
| Responses 压缩 | POST /v1/responses/compact | XSI 强制 Accept: application/json |
| Responses 子资源 | GET /v1/responses/{id}、POST /v1/responses/{id}/cancel、GET /v1/responses/{id}/input_items | 与创建请求走同一粘性路径;GET 不计费 |
| Embeddings | POST /v1/embeddings | 按 usage.prompt_tokens 计费 |
| 图片生成与编辑 | POST /v1/images/generations、POST /v1/images/edits、POST /v1/images/variations | 按张或按 Token 计费,见下文 |
| 视频生成 | POST /v1/videos/generations、GET /v1/videos/{request_id} | 异步任务,见下文 |
| 音频 | POST /v1/audio/transcriptions、/v1/audio/translations、/v1/audio/speech | 转录与翻译未指定模型时按 whisper-1 路由 |
| Moderations | POST /v1/moderations | 未指定模型时按 omni-moderation-latest 路由 |
| Files | /v1/files、/v1/files/{id} | 列表请求无模型,使用伪模型名 files 做分组映射 |
| Threads | /v1/threads、/v1/threads/{id}/... | 集合路径使用伪模型名 thread,子路径以线程 ID 作为路径模型值 |
| Realtime | GET /v1/realtime(WebSocket)、POST /v1/realtime/calls、POST /v1/realtime/client_secrets | 见《WebSocket 与实时接口》 |
| Live | POST /v1/live/sessions、WebSocket /v1/live/sessions | 见《WebSocket 与实时接口》 |
| 模型列表 | GET /v1/models | 本地处理,见查询接口 |
关于 /v1 前缀
- 本地处理的路由(模型列表、余额、Realtime、Live、视频、DeepSeek 工具与文件)同时接受带与不带
/v1的写法。 - 转发路由能否省略
/v1取决于上游的路径映射。对api.openai.com,XSI 会把/chat/completions、/responses、/embeddings、/models、/images/*、/audio/*、/files、/batches、/fine_tuning、/realtime、/moderations补全为/v1/...。 - 新接入请始终使用
/v1/...。
示例:Chat Completions
curl "$XSI_BASE_URL/v1/chat/completions" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6.2-sol",
"messages": [{"role": "user", "content": "用一句话介绍 XSI"}],
"stream": true,
"stream_options": {"include_usage": true}
}'Chat Completions 流式请求建议设置 stream_options.include_usage。上游流中没有 usage 时,XSI 会按实际输出与会话内容估算用量。
示例:Responses
curl "$XSI_BASE_URL/v1/responses" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-6.2-sol", "input": "只回复 OK"}'from openai import OpenAI
client = OpenAI(base_url="https://api.xsicontrol.com/v1", api_key="sk-Xvs...")
resp = client.responses.create(model="gpt-6.2-sol", input="只回复 OK")
print(resp.output_text)图片
- 定价表中同时以 Token 计价的图片模型(如
gpt-image-2、gpt-image-2.6-*)按 Token 计费。 - 其他图片模型按
ImgPricing计费:尺寸单价 × n + 输入图单价 × 输入图数。默认尺寸为1024x1024;grok-imagine*系列按resolution(如1k、2k)计价。
curl "$XSI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-image-2.6-flare", "prompt": "a lighthouse at dawn", "size": "1024x1024"}'视频
视频生成是异步流程:
POST /v1/videos/generations创建任务。XSI 会把响应中的上游request_id替换为一个签名令牌(形如vjob_...),令牌绑定创建它的 XSI 账号与上游 Key。- 使用同一个 XSI 账号的 Key 原样轮询
GET /v1/videos/{request_id}。令牌不属于当前账号或已被篡改时返回400 invalid video request_id;创建任务的上游 Key 已不可用时返回503 video generation account unavailable。
- 视频创建请求不会自动重试,以免重复生成;任何 2xx 响应都视为创建成功并计费。
- 计费:
duration(1–15 秒,默认 6)× 分辨率单价(默认480p)+ 输入图片数(image、reference_images)× 输入图单价。
curl "$XSI_BASE_URL/v1/videos/generations" \
-H "Authorization: Bearer $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "grok-imagine-video", "prompt": "waves on a quiet beach", "duration": 6, "resolution": "720p"}'Anthropic 兼容接口
| 能力 | 方法与路径 |
|---|---|
| Messages | POST /v1/messages |
| Token 计数 | POST /v1/messages/count_tokens |
| Files | /v1/files(带 anthropic-beta: files-api-... 请求头) |
- 鉴权可使用
x-api-key或Authorization;XSI 转发给 Anthropic 时只保留一个x-api-key(上游 Key)。 /v1/messages支持粘性会话,有利于提示缓存命中。count_tokens的响应不含 usage,不产生 Token 费用。
curl "$XSI_BASE_URL/v1/messages" \
-H "x-api-key: $XSI_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "你好"}]
}'import anthropic
client = anthropic.Anthropic(base_url="https://api.xsicontrol.com", api_key="sk-Xvs...")
msg = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024,
messages=[{"role": "user", "content": "你好"}])
print(msg.content[0].text)Gemini 原生接口
模型写在 URL 中的路径都按 Gemini 原生协议处理:
/v1beta/models/{model}:generateContent
/v1beta/models/{model}:streamGenerateContent?alt=sse
/v1beta/models/{model}:countTokens
/v1beta/models/{model}:embedContent同样支持 /v1beta1/models/、/v1alpha/models/、/v1/models/{model}:... 前缀,以及包含 /publishers/google/models/{model} 的 Vertex 风格路径。
- 以 URL 中的模型为准,请求体中的
model被忽略;模型映射会直接改写 URL。 - 鉴权使用
x-goog-api-key或Authorization,不支持?key=。 - 路径含
streamGenerateContent、带?alt=sse或Accept: text/event-stream时按流式处理。 - 用量从
usageMetadata读取。
curl "$XSI_BASE_URL/v1beta/models/$GEMINI_MODEL:generateContent" \
-H "x-goog-api-key: $XSI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents": [{"parts": [{"text": "你好"}]}]}'$GEMINI_MODEL 应为运营方已在定价表中配置、且你的账号有权使用的 Gemini 模型。
DeepSeek 接口
使用 DeepSeek 上游时,XSI 透传 DeepSeek 的全部接口,包括 Anthropic 格式(/anthropic/v1/messages)、联网搜索与抓取、OCR、语音合成与识别、文件以及余额查询。所有路径带不带 /v1 均可。
| 接口 | 路径 | 计费模型 |
|---|---|---|
| 对话 | POST /v1/chat/completions、/v1/responses、/v1/messages | deepseek-flash 等 |
| 网页搜索 / 抓取 | POST /v1/tools/search、/v1/tools/fetch | deepseek-search、deepseek-fetch |
| OCR | POST /v1/tools/ocr | deepseek-ocr |
| 语音合成 / 识别 | POST /v1/tools/tts(亦可 WebSocket)、POST /v1/tools/asr | deepseek-tts、deepseek-asr |
| 文件 | POST/GET /v1/files、GET/DELETE /v1/files/{id} | 文档解析为 deepseek-files |
文件按用户隔离、工具接口的计费单位等细节见《DeepSeek 全家桶接入》。
xAI(Grok)接口
api.x.ai 上游按 OpenAI 兼容协议转发(Bearer 鉴权,不做路径映射)。Responses 输出中的 x_search_call 按搜索次数(Query 单价)计费;图片与视频规则见上文。
流式响应
- 以下任一条件成立即按流式处理:JSON 中
"stream": true、Accept: text/event-stream、路径含streamGenerateContent、查询参数stream=true或alt=sse。 - SSE 原样透传,XSI 仅在旁路解析用量;流式请求会以
Accept-Encoding: identity发往上游,避免压缩缓冲。 - 客户端中途断开时,已生成部分仍按实际用量结算。
- 上游响应头等待上限由
RESPONSE_HEADER_TIMEOUT_SECS控制,默认 1800 秒。
粘性会话
对 /v1/responses(含子资源)、*/chat/completions、*/messages,XSI 会把同一会话固定到同一个上游 Key,以提高提示缓存命中率。读取 /v1/responses/{id} 时,请携带与创建时相同的会话请求头并路由到同一 Level,才能回到创建它的上游账号(绑定按会话而非 response ID 保存)。会话标识按以下优先级读取:
- 请求头
session_id - 请求头
conversation_id - JSON 请求体的
prompt_cache_key - 请求头
session-id - 请求头
thread-id
未提供任何标识时,同一账号在同一 Level 上默认固定到同一个 Key。是否启用由运营方配置(STICKY_SCHEDULER、STICKY_LEVELS)。
自动重试与故障转移
XSI 在服务端完成重试;所有重试都失败时,客户端收到的是首次失败的上游响应(状态码与正文原样透传):
- 重试条件:仅 POST 请求;上游状态码满足
400 < status < 600且不在NO_RETRY_STATUS中。默认不重试400、403、404、405、413、421、422、499、500,因此401、402、408、409、429、502–504、524等会自动换 Key 重试。 - 次数:当前 Level 内最多 7 次;之后可在账号允许的其他 Level 上每组最多再试 3 次(视账号的路由模式而定)。
- 不重试:视频创建;DeepSeek 文件读取与删除等绑定上游账号的请求不会切换到其他 Key。
- Responses 创建返回
400且错误含not supported时(例如某个上游账号不支持该能力),XSI 只在同组内换 Key 重试,每个 Key 最多一次。
客户端的重试建议:
- 仅对
429、502、503与网络错误做有限次重试,使用指数退避加随机抖动。 - 不要自动重复提交图片、视频等非幂等生成请求。
- 记录状态码与响应正文,但不要记录完整的 API Key。
快速档位与服务等级
请求中的 speed(standard/fast/ultrafast)或 service_tier(priority/fast 视为 fast,ultrafast 视为 ultrafast,default/standard/flex 视为标准)会影响 Token 单价:
- 以上游响应中的
speed(Anthropic 为usage.speed)或service_tier为准;响应未给出时按请求值计费。 - fast:Token 费 × 模型的
FastTokenMultiplier。 - ultrafast:Token 费 × 6。
- 倍率只作用于 Token 费用,不作用于按次或按单位计价的部分;
flex按标准价计费。
查询接口
| 方法与路径 | 说明 | 认证 |
|---|---|---|
GET /v1/models(亦可 /models、/dashboard/models) | 模型目录 | API Key |
GET /user/balance(亦可 /v1/user/balance) | 以 DeepSeek 格式返回当前账号余额 | API Key |
GET /x-pricing | 价格目录,见《价格目录 API》 | 可选 |
GET /dashboard/* | 账号状态与用量,见《账号与用量 API》 | API Key |
GET /v1/models
{"object": "list", "data": [{"id": "gpt-6.2-sol", "object": "model", "owned_by": "xai"}]}返回运营方价格表中的全部模型(对话、图片、视频、音频、Rerank 等),按名称排序。列表不按账号的模型白名单过滤;账号能否调用某个模型以实际请求的准入结果为准。
GET /user/balance
适用于任何上游,不限于 DeepSeek:
{
"is_available": true,
"balance_infos": [
{"currency": "CNY", "total_balance": "110.00", "granted_balance": "0.00", "topped_up_balance": "110.00"}
]
}is_available 为 true 表示余额大于 0 且账号未被冻结。
模型名解析
请求中的模型名按以下顺序解析,取第一个命中项:
- 运营方临时故障替换(
MODEL_FAILOVER) - 账号级
ModelMapper(精确,再通配) - 租户级
MODEL_MAPPER(精确,再通配) - 模糊匹配:模型已在价格表中则原样使用;否则在同家族、同模态中选择版本最接近的已定价模型
- 原样使用
/v1/models 中的名称为准。限制
| 项目 | 默认值 |
|---|---|
| 请求体(解压后) | 200 MiB(REQUEST_BODY_LIMIT_BYTES) |
| Realtime calls / Live HTTP 请求体 | 4 MiB |
| WebSocket 单帧 | 16 MiB |
| WebSocket 单连接时长 | 60 分钟(WS_MAX_CONN_DURATION) |
| 上游响应头等待 | 1800 秒(RESPONSE_HEADER_TIMEOUT_SECS) |