API 参考
XSI 在同一个 HTTP 入口上提供两类接口:
- 数据面(Router API):模型调用。XSI 保持 OpenAI、Anthropic、Gemini 等上游协议的原生语义,替换
base_url与 API Key 即可接入。 - 控制面(Management API):账号、额度、上游 Key、租户配置与价格目录,路径统一以
/x-或/dashboard/开头。
本参考的每个字段、默认值与错误文本均以源码为准(api/ 目录)。
基础地址
export XSI_BASE_URL="https://api.xsicontrol.com" # XSI Control;自行部署时替换为你的 API 域名
export XSI_API_KEY="sk-Xvs..."XSI_BASE_URL 不含 /v1。模型接口通常写作 $XSI_BASE_URL/v1/...;SDK 中的 base_url 一般设为 $XSI_BASE_URL/v1(Anthropic SDK 设为 $XSI_BASE_URL)。
认证
所有接口都使用 XSI 账号的 API Key。Key 以 sk-Xvs 开头,总长 51 个字符;格式不符的 Key 会在查库前被拒绝。
| 接口类型 | 接受的凭证位置 |
|---|---|
模型调用与 /dashboard/* | Authorization: Bearer <key>、x-api-key: <key>、x-goog-api-key: <key>(按此顺序取第一个非空值) |
| DeepSeek 语音合成 WebSocket | 额外接受子协议 Sec-WebSocket-Protocol: tts, bearer.<key> |
管理接口 /x-* | 仅 Authorization 头(推荐 Bearer <key>,也接受裸 Key) |
| 公开接口 | GET /x-pricing、/x-sign/*、GET /healthz 无需认证 |
- 不支持在查询参数中传递 Key(例如 Gemini 风格的
?key=)。 - XSI 在转发前会剥离调用方的全部凭证头(
Authorization、x-api-key、x-goog-api-key、api-key、Cookie等)以及客户端 IP 相关的转发头,再按上游类型写入上游 Key。调用方的 XSI Key 永远不会发送给模型服务商。 - 防暴力破解:同一 IP 在 1 分钟内认证失败 12 次将被封禁 2 分钟,10 分钟内失败 48 次封禁 15 分钟,封禁期间返回
429;同一个无效 Key 在 90 秒内会被直接拒绝。
权限级别
| 级别 | 判定条件 | 典型接口 |
|---|---|---|
| 任意账号 | Key 有效且账号启用 | 模型调用、/dashboard/*、POST /x-self |
| 管理者(Manager) | root;或同时满足 TPD > 800000000、具备子账号能力(UserLimit > 0 或已有子账号)、余额高于 USER_API_BALANCE(默认 100) | /x-users、/x-dna、/x-bill、/x-news、/dashboard/logs |
| 租户所有者(Owner) | ID == OID,root 也是 Owner | /x-keys、/x-config、/x-conf、/x-info |
| root | DNA == "." | 系统公告、注册域名策略 |
GET /dashboard/status 返回的 manage 字段即“管理者”判定结果,owner 字段即“租户所有者”判定结果。
通用约定
- 编码:请求与响应均为 UTF-8。模型接口请正确设置
Content-Type: application/json或multipart/form-data,否则 XSI 不会读取请求体中的model,模型映射与模型权限也无法生效。 - 压缩请求体:支持
Content-Encoding: gzip、deflate、br、zstd,XSI 解压后再转发。 - 请求体上限:默认 200 MiB,由
REQUEST_BODY_LIMIT_BYTES调整。XSI 在认证前检查声明的Content-Length,读取时再按解压后的大小检查,超过时返回413。Realtime calls 与 Live 建会另有 4 MiB 上限。 - 日期:查询参数使用
YYYY-MM-DD,按服务器时区(部署模板默认Asia/Shanghai)解释;响应中的时间为 RFC 3339。 - 货币:余额、扣费与价格均以人民币(CNY)计。
- 管理接口字段名:
/x-users、/x-keys、/x-conf的请求与响应使用 Go 字段名(PascalCase,例如CreditGranted);/dashboard/*、/x-info、/x-pricing使用 snake_case。请严格按本参考的大小写书写字段名。 - 分页:账号与 Key 列表支持
page与size,单页最多 8192 条,并返回X-Total-Count,分页时另有X-Page、X-Per-Page、X-Total-Pages;/dashboard/logs的size为 1–100,总数在 JSON 正文中返回。 - 管理调用费:部分管理查询会按
XAPI_FEE(默认 ¥0.012)扣费,并以模型名XAPI计入账单,见各接口说明。
错误格式
- XSI 自身产生的错误为
text/plain单行文本(例如Unauthorized),HTTP 状态码表达错误类别。 - 上游返回的错误原样透传,保留上游的状态码与 JSON 结构。
- 注册接口
/x-sign与配置接口/x-config返回 JSON 结构的结果。
完整的状态码与错误文本见《错误码》。
端点索引
数据面
| 端点 | 文档 |
|---|---|
POST /v1/chat/completions、/v1/responses、/v1/messages、/v1/embeddings、/v1/images/*、/v1/audio/*、/v1/videos/*、Gemini /v1beta/models/* 等 | Router API |
| Responses WebSocket、Realtime、Live、DeepSeek TTS | WebSocket 与实时接口 |
GET /v1/models、GET /user/balance | Router API |
控制面
| 端点 | 说明 | 文档 |
|---|---|---|
GET /dashboard/status、/info、/live、/bill、/logs、/news | 当前账号状态与用量 | 账号与用量 API |
GET /x-bill | 后代账号用量与排行 | 账号与用量 API |
/x-users、/x-dna、/x-users/batch-credit、/x-self、/x-news | 子账号、额度与公告 | 账号管理 API |
/x-keys | 上游 Provider Key | Provider Key API |
/x-config、/x-conf、/x-info | 租户配置与运行时控制 | 租户配置 API |
GET /x-pricing | 价格目录 | 价格目录 API |
/x-sign | 自助注册 | 注册 API |
/x-notify/* | 支付网关通知 | 支付通知 API |
GET /healthz | 健康检查,返回 OK | — |