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
rootDNA == "."系统公告、注册域名策略

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 TTSWebSocket 与实时接口
GET /v1/models、GET /user/balanceRouter 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 KeyProvider Key API
/x-config、/x-conf、/x-info租户配置与运行时控制租户配置 API
GET /x-pricing价格目录价格目录 API
/x-sign自助注册注册 API
/x-notify/*支付网关通知支付通知 API
GET /healthz健康检查,返回 OK—