Responses API 完整指南

Responses API 是 xAI 推荐的 Grok 文本与多模态生成接口，适合文本生成、多轮对话、图像理解、工具调用、流式输出和结构化结果生成等场景。

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

https://xikapi.com

常用请求地址：

https://xikapi.com/v1/responses

为什么使用 Responses API

Responses API 适合新项目作为 Grok 默认接入方式。它支持可选的状态化交互，可以通过上一轮响应 ID 继续对话，也可以由服务端自行维护完整上下文。

它的常见优势包括：

• 支持文本、图像和工具调用
• 支持多轮对话
• 支持结构化输出
• 支持流式输出
• 支持搜索等服务端工具
• 与 OpenAI SDK 兼容度高

基础文本生成

curl https://xikapi.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XIKAPI_API_KEY" \
  -d '{
    "model": "grok-4.3-latest",
    "input": [
      {
        "role": "system",
        "content": "You are a precise technical documentation assistant. Keep answers concise and accurate."
      },
      {
        "role": "user",
        "content": "Explain in three sentences what Grok is best suited for"
      }
    ]
  }'

JavaScript：

import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "grok-4.3-latest",
  input: [
    {
      role: "system",
      content: "You are a precise technical documentation assistant. Keep answers concise and accurate."
    },
    {
      role: "user",
      content: "Introduce the Grok Responses API"
    }
  ],
});

console.log(response.output_text);

Python：

from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.3-latest",
    input=[
        {"role": "system", "content": "You are a precise technical documentation assistant. Keep answers concise and accurate."},
        {"role": "user", "content": "Introduce the Grok Responses API"},
    ],
)

print(response.output_text)

input 数组

input 可以传入系统、用户和助手消息。服务端可以选择每次传完整历史，也可以使用 previous_response_id 继续上一轮。

{
  "model": "grok-4.3-latest",
  "input": [
    { "role": "user", "content": "My system needs knowledge-base Q&A" },
    { "role": "assistant", "content": "You can split documents, retrieve relevant chunks, and use Grok to generate answers." },
    { "role": "user", "content": "What are good document chunking practices?" }
  ]
}

多轮对话

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

{
  "model": "grok-4.3-latest",
  "input": [
    { "role": "user", "content": "Summarize this contract" },
    { "role": "assistant", "content": "This contract mainly covers scope of services, fees, and breach clauses." },
    { "role": "user", "content": "Focus on payment risks" }
  ]
}

方式二：使用上一轮响应 ID。

{
  "model": "grok-4.3-latest",
  "previous_response_id": "resp_xxx",
  "input": [
    { "role": "user", "content": "Expand on the second point" }
  ]
}

max_output_tokens

max_output_tokens 控制单次响应最多生成多少 token。生产环境建议显式设置，避免输出过长导致成本不可控。

{
  "model": "grok-4.3-latest",
  "max_output_tokens": 1024,
  "input": [
    { "role": "user", "content": "Write a product description in fewer than 100 words" }
  ]
}

temperature

temperature 用于控制输出随机性。值越低，输出越稳定；值越高，表达越发散。

{
  "model": "grok-4.3-latest",
  "temperature": 0.2,
  "input": [
    { "role": "user", "content": "Classify this text as complaint, inquiry, or praise" }
  ]
}

图像输入

支持视觉输入的 Grok 模型可以接收 input_image 和 input_text 内容块。

{
  "model": "grok-4.3-latest",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_image",
          "image_url": "data:image/png;base64,BASE64_IMAGE_DATA",
          "detail": "high"
        },
        {
          "type": "input_text",
          "text": "Analyze the main content of this image"
        }
      ]
    }
  ]
}

工具调用

工具调用让 Grok 在需要外部信息或业务动作时返回工具调用请求，由你的服务端或 xAI 服务端工具执行。

{
  "model": "grok-4.3-latest",
  "tools": [
    {
      "type": "function",
      "name": "get_order_status",
      "description": "Check order status",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "Order ID"
          }
        },
        "required": ["order_id"],
        "additionalProperties": false
      }
    }
  ],
  "input": [
    { "role": "user", "content": "Check the status of order A1001" }
  ]
}

流式输出

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

curl https://xikapi.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XIKAPI_API_KEY" \
  -d '{
    "model": "grok-4.3-latest",
    "stream": true,
    "input": [
      {
        "role": "user",
        "content": "Write a short article about API integration"
      }
    ]
  }'

错误处理

常见错误包括：

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

接入建议

• API Key 只放在服务端
• 生产环境显式设置 max_output_tokens
• 多轮状态由服务端自行决定是否托管
• 图像和长文档任务注意请求体大小
• 工具调用结果必须经过权限校验
• 所有 xAI 兼容请求地址统一使用 https://xikapi.com/v1/...