Xikapi 接入文档

Responses API 完整指南 ​

Responses API 是 OpenAI 新一代统一生成接口，适合文本生成、多轮对话、图像输入、结构化输出、工具调用和代理工作流等场景。

在 Xikapi 中，请使用 OpenAI 兼容路径，并将请求域名替换为：

text
https://xikapi.com

常用请求地址：

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

为什么优先使用 Responses API ​

相比旧的 Chat Completions，Responses API 更适合作为新项目的默认接口：

  • 统一文本、多模态、工具调用等能力
  • 更适合推理模型和代理型任务
  • 支持更清晰的输出结构
  • 可以通过 previous_response_id 串联多轮上下文
  • 与结构化输出、内置工具、函数调用配合更自然

基础文本生成 ​

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": "Write a product description in fewer than 100 words"
  }'

JavaScript：

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: "Write a product description in fewer than 100 words",
});

console.log(response.output_text);

Python：

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="Write a product description in fewer than 100 words",
)

print(response.output_text)

使用 instructions 控制行为 ​

instructions 适合放系统级要求，例如角色、语气、边界、格式约束。

bash
curl https://xikapi.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XIKAPI_API_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "instructions": "You are a precise technical documentation assistant. Keep answers concise and accurate.",
    "input": "Explain why API keys should not be stored in frontend code"
  }'

多轮对话 ​

Responses API 可以通过两种方式管理上下文：

方式一：客户端维护完整历史 ​

适合需要完全控制上下文的业务。

json
{
  "model": "gpt-5.4-mini",
  "input": [
    {
      "role": "user",
      "content": "My project is a knowledge-base Q&A system"
    },
    {
      "role": "assistant",
      "content": "You can build RAG with embedding models and a vector database."
    },
    {
      "role": "user",
      "content": "How should I chunk the documents?"
    }
  ]
}

方式二：使用 previous_response_id ​

适合简单串联上一轮响应。

bash
curl https://xikapi.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XIKAPI_API_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "previous_response_id": "resp_xxx",
    "input": "Expand on the second point"
  }'

图像输入 ​

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": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "What is in this image?" },
          {
            "type": "input_image",
            "image_url": "https://example.com/image.png"
          }
        ]
      }
    ]
  }'

结构化输出 ​

当业务需要稳定 JSON 时，建议使用结构化输出，而不是只在提示词中写“返回 JSON”。

json
{
  "model": "gpt-5.4-mini",
  "input": "Extract the name and email from this text: Jane Doe, email jane.doe@example.com",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "contact_info",
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "email": { "type": "string" }
        },
        "required": ["name", "email"],
        "additionalProperties": false
      }
    }
  }
}

工具调用 ​

工具调用适合让模型决定是否调用外部函数，例如查询订单、搜索知识库、获取天气等。

json
{
  "model": "gpt-5.4-mini",
  "input": "Check the shipping status for order A1001",
  "tools": [
    {
      "type": "function",
      "name": "get_order_status",
      "description": "Check order shipping status",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "Order ID"
          }
        },
        "required": ["order_id"],
        "additionalProperties": false
      }
    }
  ]
}

模型返回工具调用后，你的服务端执行函数，再把结果提交回模型生成最终回答。

流式输出 ​

聊天、长文本生成和前端实时展示通常需要流式输出。

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": "Write a short article about integrating an AI API",
    "stream": true
  }'

实现流式输出时需要注意：

  • 前端逐段拼接文本
  • 用户中断时取消请求
  • 服务端记录完整输出
  • 异常时提供重试或重新生成

错误处理 ​

常见错误包括：

状态码含义排查方向
400请求参数错误检查 JSON、模型名、字段类型
401鉴权失败检查 API Key 是否正确
403权限不足检查模型权限或账户权限
429触发限流降低并发、增加重试、检查额度
500/503服务异常稍后重试，记录请求 ID

建议生产环境增加：

  • 超时设置
  • 指数退避重试
  • 请求日志
  • 错误码映射
  • 模型降级策略

与 Chat Completions 的区别 ​

对比项Responses APIChat Completions
推荐程度新项目优先旧项目兼容
输入结构更统一，支持多种内容项以 messages 为核心
工具调用更适合代理和复杂工具链也支持，但形态较旧
多模态更统一按模型和接口分散
多轮状态可结合 previous_response_id通常手动维护 messages

接入建议 ​

  • 新项目默认使用 Responses API
  • 已有 Chat Completions 项目可以逐步迁移
  • 需要稳定 JSON 时使用结构化输出
  • 需要外部系统能力时使用工具调用
  • 所有 OpenAI 兼容请求地址统一使用 https://xikapi.com/v1/...