Xikapi 接入文档

模型选择与能力对照 ​

选择模型时，不建议只看“最强”或“最新”，而应该根据任务类型、上下文长度、响应速度、成本预算、稳定性和输出格式要求综合判断。

在 Xikapi 中调用 OpenAI 兼容接口时，请将请求域名设置为：

text
https://xikapi.com

API 路径继续使用 OpenAI 兼容的 /v1/... 后缀，例如：

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

新手先确认 ​

如果只是想先跑通一次调用，先不要纠结哪个模型最强，按下面顺序检查：

要确认的内容正确做法常见误区
API Key使用 Xikapi 控制台创建的 API Key把 OpenAI 官网 Key 填到 Xikapi 地址里
Base URLSDK 中填写 https://xikapi.com/v1写成完整的 /chat/completions 或 /responses
模型名填 Xikapi 后台已启用的模型 ID只看官方模型名，后台没有启用
接口类型新项目优先 Responses API，旧项目可继续 Chat Completions把 Responses 参数发到 Chat Completions
权限分组确认当前令牌有该模型权限管理后台能看到模型，但调用令牌不可用

可以先用一个轻量文本模型验证 Key、地址和模型名都正确，再测试推理、视觉、工具调用、结构化输出等高级能力。

常见模型类型 ​

类型适合场景典型能力
通用对话模型客服、问答、写作、办公助手多轮对话、总结、改写、信息抽取
推理模型数学、复杂规划、代码分析、严谨决策更强的逻辑推理和多步骤问题处理
多模态模型图片理解、截图分析、票据识别同时处理文本和图像输入
代码模型代码生成、重构、调试、测试生成理解项目上下文并生成代码
嵌入模型RAG、语义搜索、推荐、去重将文本转为向量，用于相似度检索
语音模型语音转文字、文字转语音、实时语音助手音频输入输出、转录、朗读
图像模型生成图片、编辑图片、视觉创意文生图、图像编辑、风格转换

按场景选择 ​

场景推荐能力说明
聊天机器人通用对话模型 + Responses API优先选择响应稳定、成本可控的模型
智能客服对话模型 + 工具调用 + RAG需要接入订单、知识库、工单等外部系统
代码助手代码模型或强推理模型适合代码生成、解释、重构和单元测试
长文总结长上下文文本模型关注上下文窗口和输出长度限制
文档问答嵌入模型 + RAG + 对话模型先检索相关内容，再让模型生成答案
图片理解多模态模型适合截图、票据、商品图、图表理解
结构化抽取支持结构化输出的模型建议配合 JSON Schema 使用
语音助手语音模型或实时模型关注延迟、音色、转录准确率
批量分类轻量模型优先考虑成本和吞吐量

选择模型时关注什么 ​

1. 任务复杂度 ​

简单分类、改写、摘要可以使用轻量模型；复杂推理、代码分析、长链路规划应使用推理能力更强的模型。

2. 输入输出模态 ​

如果任务包含图片、音频或文件，需要选择支持对应输入类型的模型。纯文本模型无法直接理解图片或音频。

3. 上下文长度 ​

长文档、长对话、代码仓库分析会消耗大量上下文。上下文越长，成本和延迟通常越高。

4. 成本预算 ​

生产环境建议准备“主模型 + 降级模型”策略：

  • 高价值请求使用强模型
  • 普通请求使用轻量模型
  • 批量任务使用低成本模型
  • 失败或超时时自动降级

5. 输出稳定性 ​

如果业务依赖稳定 JSON，建议使用结构化输出，而不是只靠提示词要求“请返回 JSON”。

推荐接入策略 ​

新项目 ​

优先使用 Responses API：

bash
curl https://xikapi.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XIKAPI_API_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "Explain in three sentences when vector databases are useful"
  }'

旧项目 ​

如果已有 Chat Completions 接入，可以继续兼容使用：

bash
curl https://xikapi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XIKAPI_API_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      { "role": "user", "content": "Explain what RAG is" }
    ]
  }'

SDK 调用 ​

如果 SDK 支持 baseURL，建议显式配置为 Xikapi 地址：

javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XIKAPI_API_KEY,
  baseURL: "https://xikapi.com/v1",
});

const response = await client.responses.create({
  model: "gpt-5.4-mini",
  input: "Give me a checklist for choosing a model",
});

console.log(response.output_text);
python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_XIKAPI_API_KEY",
    base_url="https://xikapi.com/v1",
)

response = client.responses.create(
    model="gpt-5.4-mini",
    input="Give me a checklist for choosing a model",
)

print(response.output_text)

常见排错 ​

现象优先检查
401、Invalid API KeyKey 是否来自 Xikapi，是否复制完整，前后是否有空格
404SDK 的 baseURL 是否只到 /v1，不要把完整接口路径写进去
model not found模型 ID 是否和 Xikapi 后台完全一致，当前令牌是否有权限
unsupported parameter当前接口或模型不支持该参数，例如把 Responses 的字段发到 Chat Completions
返回不是稳定 JSON改用结构化输出或 JSON Schema，不要只靠提示词约束
请求很慢或超时推理、长上下文、工具调用任务要设置更长超时，并准备降级模型

最佳实践 ​

  • 能用轻量模型解决的问题，不要默认使用最强模型
  • 对生产环境固定模型版本，避免模型升级导致行为变化
  • 对关键任务建立评测集，升级模型前先测试
  • 对长文本任务先切分、压缩或检索，再生成
  • 对结构化数据使用 JSON Schema 或函数调用
  • 对成本敏感业务增加缓存和模型降级策略