Responses API 是与 xAI 模型交互的推荐方式。下面将它与旧版 Chat Completions API 进行对比：

功能	Responses API	Chat Completions API（Deprecated）
Stateful Conversation	通过 `previous_response_id`	Stateless，必须重新发送完整历史
Server-side Storage	Response 存储 30 天	不存储，需要自行管理历史
Reasoning Model	完整支持 encrypted reasoning content	不返回 reasoning content
Agent Tool	原生支持 Tool（Search、Code Execution、MCP）	仅支持 Function Calling
计费优化	自动缓存对话历史	每个请求都按完整历史计费
未来功能	所有新能力优先在此提供	Legacy Endpoint，更新有限

主要 API 变化

参数映射

Chat Completions	Responses API	说明
`messages`	`input`	Message object array
`max_tokens`	`max_output_tokens`	生成 token 的最大数量
—	`previous_response_id`	继续已存储的对话
—	`store`	控制 Server-side Storage（默认值：`true`）
—	`include`	请求其他数据，例如 `reasoning.encrypted_content`

Response 结构

两个 API 的 response 格式不同：

Chat Completions在 choices[0].message.content 中返回内容：

{
  "id": "chatcmpl-123",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you?"
    }
  }]
}

Responses API在 output array 中返回带类型的 item：

{
  "id": "resp_123",
  "output": [{
    "type": "message",
    "role": "assistant",
    "content": [{
      "type": "output_text",
      "text": "Hello! How can I help you?"
    }]
  }]
}

多轮对话

使用 Chat Completions 时，每个请求都必须重新发送完整对话历史。使用 Responses API 时，可以通过 previous_response_id继续对话：

# First request
response = client.responses.create(
    model="grok-4",
    input=[{"role": "user", "content": "What is 2+2?"}],
)

# Continue the conversation - no need to resend history
second_response = client.responses.create(
    model="grok-4",
    previous_response_id=response.id,
    input=[{"role": "user", "content": "Now multiply that by 10"}],
)

迁移路径

从 Chat Completions 迁移到 Responses API 很直接。下面介绍各 SDK 的代码更新方式：

Vercel AI SDK

将 xai()替换为xai.responses() 中返回内容：

  model: xai('grok-4'),
  model: xai.responses('grok-4'),

OpenAI SDK（JavaScript）

将 client.chat.completions.create替换为client.responses.create，并将 messages替换为input 中返回内容：

const response = await client.chat.completions.create({
const response = await client.responses.create({
    messages: [
    input: [
        { role: "user", content: "Hello!" }
    ],
});

OpenAI SDK（Python）

将 client.chat.completions.create替换为client.responses.create，并将 messages替换为input 中返回内容：

response = client.chat.completions.create(
response = client.responses.create(
    messages=[
    input=[
        {"role": "user", "content": "Hello!"}
    ],
)

cURL

将 endpoint 从 /v1/chat/completions替换为/v1/responses，并将 messages替换为input 中返回内容：

curl https://api.x.ai/v1/chat/completions \
curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{ "model": "grok-4", "messages": [{"role": "user", "content": "Hello!"}] }'
  -d '{ "model": "grok-4", "input": [{"role": "user", "content": "Hello!"}] }'

这适用于大多数使用场景。如果有特殊集成，请参阅 Responses API 文档获取详细指导。

模型能力

与 Chat Completions API 对比