Xikapi 接入文档

报错指南 ​

模型调用报错时，先把问题拆成四类：认证、地址、模型权限、请求参数。不要一上来更换模型或重写业务代码，先用最小请求确认基础链路。

最小验证请求 ​

OpenAI 兼容接口可以先用下面的请求测试：

bash
curl https://xikapi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XIKAPI_API_KEY" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      { "role": "user", "content": "Reply with ok only" }
    ]
  }'

把 YOUR_MODEL_ID 替换成 Xikapi 后台已经启用、且当前 API Key 有权限的模型。

常见状态码 ​

状态码常见原因处理方式
400请求字段不符合接口格式，参数不被模型支持检查 messages、input、contents 是否混用，去掉扩展参数后重试
401API Key 错误、缺失或被禁用确认使用 Xikapi Key，Header 为 Authorization: Bearer ...
403当前令牌没有权限调用该模型检查可用令牌分组、用户权限和模型启用状态
404地址或路径错误，或模型不存在SDK Base URL 只填基础地址，不要填完整接口路径
429速率限制、额度不足或上游繁忙降低并发，检查额度，增加重试和降级模型
500 / 502 / 503上游服务异常或临时不可用记录 request id、模型名和时间，稍后重试或切换备用模型

高频报错 ​

报错文本优先检查
Invalid API KeyKey 是否来自 Xikapi，是否复制完整，环境变量是否生效
model not found模型 ID 是否和后台完全一致，当前 API Key 是否有该模型权限
unsupported parameter当前模型是否支持工具调用、搜索、思考模式或结构化输出
context length exceeded输入是否超过上下文限制，是否需要切分、摘要或检索后再生成
timeout推理、搜索、长上下文任务是否需要更长超时
JSON 解析失败模型输出不是严格 JSON，建议使用结构化输出或增加后置校验

Base URL 怎么填 ​

不同工具对“Base URL”的定义不同，但 OpenAI 兼容 SDK 通常只填到 /v1：

text
https://xikapi.com/v1

不要把完整接口路径填进 SDK 的 Base URL：

text
https://xikapi.com/v1/chat/completions
https://xikapi.com/v1/responses

这些路径通常由 SDK 自动拼接。把完整路径填进去，常见结果是 404 或重复路径。

不同接口不要混用 ​

接口类型常见路径请求主体
OpenAI Chat Completions/v1/chat/completionsmessages
OpenAI Responses/v1/responsesinput
Anthropic Messages/v1/messagesmessages + max_tokens
Gemini Generate Content/v1beta/models/{model}:generateContentcontents + parts

如果把 Gemini 的 contents 发到 Chat Completions，或把 Responses 的 input 发到 Chat Completions，通常会得到参数错误。

排查顺序 ​

  1. 用最小请求测试 Key、地址、模型名。
  2. 确认当前 API Key 的令牌分组有模型权限。
  3. 去掉工具调用、联网搜索、思考模式、结构化输出等扩展参数后重试。
  4. 再逐项打开高级能力，确认是哪一个参数或能力导致失败。
  5. 生产环境记录模型名、状态码、响应体、request id、请求时间和用户标识，方便后续定位。

仍然失败时需要提供的信息 ​

向技术支持排查时，建议提供：

  • 请求时间和时区
  • 使用的模型 ID
  • 请求路径，例如 /v1/chat/completions
  • HTTP 状态码
  • 返回的错误文本
  • 是否为流式请求
  • 是否包含图片、工具调用、联网搜索或结构化输出

不要发送真实 API Key。需要展示 Header 时，保留前后几位即可。