常见问题
接入
Base URL 应该写到哪一级?
API 域名本身不含 /v1。OpenAI SDK 与多数 OpenAI 兼容客户端填写 https://<API 域名>/v1;Anthropic SDK 与 Claude Code 填写 https://<API 域名>;Gemini SDK 填写 https://<API 域名>。出现 404 时,通常是少写或多写了 /v1。
为什么返回 401?
You didn't provide an API key...:没有携带 Key,或 Key 不是sk-Xvs开头的 51 位字符串。Unauthorized:Key 不存在或已被轮换。Insufficient balance...:余额低于冻结阈值,账号刚被冻结,充值后恢复。
如果错误正文是上游服务商的 JSON 格式,说明请求可能被直接发到了官方地址,请检查 base_url。
为什么提示模型无权使用,或者实际调用的模型和请求的不一样?
403 Access denied: You are not authorized to use the '<model>' model:账号设置了模型白名单。- XSI 会按
MODEL_MAPPER改写模型;未在价格表中的模型名还会被模糊匹配到同家族、版本最接近的已定价模型。请使用GET /v1/models或价格目录中的准确名称。
流式输出卡住或一次性返回?
通常是反向代理缓冲了响应。Nginx 需关闭 proxy_buffering,并把 proxy_read_timeout 设得足够长;经过 CDN 时注意其响应超时。见《反向代理》。
开源项目不支持配置 base_url 怎么办?
多数 SDK 支持通过环境变量设置地址(如 OPENAI_BASE_URL、ANTHROPIC_BASE_URL)。确实无法配置时,只能修改项目源码中的 API 地址。
计费与额度
如何计费?
按上游返回的真实用量实时扣费,币种为人民币:
扣费 = 原价 × 用量 × 模型 Rates × 账号 Rates × 账号 Factor 价格表记录服务商原币种的原价,美元标价模型的 Rates 默认为 7。账号的最终单价可通过 GET /x-pricing(携带 Key)的 final 字段查看。详见《计费与价格》。
失败的请求收费吗?
上游直接返回错误、且没有产生用量的普通 HTTP 请求不收费。被白名单或模型级限额拒绝的 POST、无法解析的请求体、调用了未定价的模型,会收取一次 XAPI_FEE(默认 ¥0.012),在账单中显示为 XAPI。中断或失败的请求按协议与已取得的用量结算:可靠的上游用量优先,缺失部分按已观察到的内容与会话历史估算;上游已接受的输入也可能产生费用。
额度有有效期吗?
有。每笔额度有独立的到期时间:充值额度默认 1 年,注册赠金 1 个月,子账号获得的划转额度沿用来源额度的到期时间。可在 GET /dashboard/info 的 credit_balance 中查看。
账户还有余额,为什么提示余额不足或被暂停?
余额不高于冻结阈值(USER_MIN_BALANCE − 0.01,部署模板为 ¥1.99)时,账号暂停调用:请求中首次发现余额不足返回 401,已被后台结算冻结时返回 429。充值后余额高于阈值即自动恢复。
限额与限速
为什么设置了 RPM / DailyLimit 却没有生效?
额度与限速只对 Role 2(严格)和 Role 3(订阅)账号生效。由 INIT_USERS 创建的 root 为 Role 0;单租户自助注册账号继承 root 的 Role(通常为 0),多租户注册默认 Role 1;子账号继承父账号。请由租户所有者把需要限制的账号设为 Role 2。
429 之后要等多久恢复?
| 命中的限制 | 恢复 |
|---|---|
RPM、TPM | 约 1 分钟 |
RPH、TPH | 约 1 小时 |
RPD、TPD、DailyLimit | 次日零点(服务器时区) |
HardLimit | 次月 |
RPD/TPD 是自然日额度,不是滚动 24 小时。请求数在通过准入时计数,已准入但上游失败的请求同样计入,冷却期内被拒绝的请求不会重复消耗配额;Token 在请求完成后累计,因此超额通常从下一次请求开始返回 429。客户端应使用指数退避,避免持续重试。
为什么调用 /x-users 返回 403?
管理子账号需要同时满足:TPD > 800000000、具备子账号能力(UserLimit > 0 或已有子账号)、余额高于 USER_API_BALANCE(默认 ¥100)。错误正文会说明缺少哪一项。GET /dashboard/status 的 manage 字段可提前判断。
子账号为什么不能再创建下级账号?
父账号(非 root)自身的 UserLimit 小于 64 时,它创建的子账号 UserLimit 固定为 0,只能使用服务,不能继续分发。
部署
控制台无法登录,浏览器提示跨域错误?
XSI 不发送 CORS 响应头,控制台跨域调用 API 依赖反向代理为 API 域名添加 CORS 头并直接应答 OPTIONS 预检。参照《反向代理》的 Nginx 示例配置。
请求返回 500 No available key?
请求模型对应的 Level 中没有可用 Key:检查 LEVEL_MAPPER 是否把该模型映射到了正确的 Level,以及该 Level 的 Key 是否全部被禁用或处于休眠。可在配置管理控制台的“模型服务”或 GET /x-conf 中查看休眠与禁用的 Key。
修改了 docker-compose.yml 中的 root Key,为什么旧 Key 仍然有效?
INIT_USERS 只创建不存在的账号,不会更新已有账号。轮换 root Key 请调用 POST /x-self,确认短语为 <日期>-ROTATE-ROOT。
如何调整默认模型价格?
推荐使用租户 PRICING 覆盖,立即生效且无需重启;修改 api/pricing.json 需要重新构建或挂载文件并重启。见《计费与价格》。
如何扩展到多台服务器?
所有实例连接同一 PostgreSQL 与 Redis,设置 SINGLE_MODE=false,在负载均衡器后运行即可。见《运维》。
授权
XSI 可以免费使用吗?
个人非商业使用(学习、研究、实验与自用)免费。企业生产使用及其他商业用途(包括个人运营的收费 API 或付费服务)需取得商业授权,标准费用为人民币 2,400 元/授权主体/年。详见商业授权说明。
可以去掉控制台中的 XSI 署名吗?
不可以。所有使用者(包括商业授权方)都须保留 XSI by XABC Labs 署名与原项目链接;有登录页的应用在登录页展示即可。可以自定义品牌名、布局与样式。详见 NOTICE。
可以关闭控制台顶部的广播和右侧的推广卡片吗?
控制台默认的顶部广播位与推广卡片由 XABC Labs 提供内容,用于支持 XSI 的持续开发与运营,也是 XSI 能免费提供给个人使用的前提。免费使用时请原样保留,不要移除、隐藏、替换或修改它们;这项约束让我们能够持续免费地提供和维护 XSI。需要调整或关闭的企业,可以在商业授权中约定。
不想自己部署,有托管服务吗?
- xsirouter.com:XSI 官方运营的 AI API 服务,注册即可调用。
- xsicontrol.com:XSI 多租户云服务,使用自己的上游 Key,无需部署。