Responses API 可以通过一条连接到 /v1/responses 的长生命周期 WebSocket 连接来调用，无需在每个轮次新建 HTTP 请求。收到首个响应后，后续轮次只需发送新的输入项以及 previous_response_id；服务端会在已打开的套接字内存中保留先前状态。

该模式同时支持 Zero Data Retention（ZDR）和 store=false，因为延续对话无需访问持久化存储。

适用场景

WebSocket 模式面向包含大量连续 tool call 的智能体工作负载，例如编码智能体、编排循环，以及任何需要与模型往返数十次的任务。

每个轮次都会跳过建立连接，并且只重新发送新输入而非完整对话；在较长的运行过程中，这会累积出显著收益。我们针对包含大量 tool call 的智能体工作负载进行的内部基准测试显示，与使用相同 previous_response_id 串联的重复 HTTP 请求相比，我们测得端到端延迟最多降低约 20%。

建立连接并发送首个轮次

WebSocket 升级成功后，客户端通过发送 response.create 消息发起每个轮次。请求体的结构与 Responses 创建请求体相同，但不包含 stream 和 background 等仅用于传输的字段（响应始终以事件形式通过套接字流式返回）。

import json
import os
from websocket import create_connection

ws = create_connection(
    "wss://api.x.ai/v1/responses",
    header=[
        f"Authorization: Bearer {os.environ['XAI_API_KEY']}",
    ],
)

ws.send(
    json.dumps(
        {
            "type": "response.create",
            "model": "grok-4.7",
            "store": False,
            "input": [
                {
                    "type": "message",
                    "role": "user",
                    "content": [{"type": "input_text", "text": "Find fizz_buzz()"}],
                }
            ],
            "tools": [],
        }
    )
)

import WebSocket from "ws";

const ws = new WebSocket("wss://api.x.ai/v1/responses", {
  headers: {
    Authorization: \`Bearer \${process.env.XAI_API_KEY}\`,
  },
});

ws.on("open", () => {
  ws.send(
    JSON.stringify({
      type: "response.create",
      model: "grok-4.7",
      store: false,
      input: [
        {
          type: "message",
          role: "user",
          content: [{ type: "input_text", text: "Find fizz_buzz()" }],
        },
      ],
      tools: [],
    })
  );
});

ws.on("message", (data) => {
  console.log(JSON.parse(data.toString()));
});

使用预热参数 `generate: false`

如果已经知道后续轮次需要的 tool、指令或系统消息，可以通过发送 response.create 并设置 generate: false 来预热连接。服务端会准备请求状态，但不会运行模型，因此不会返回输出。预热仍会生成响应 ID，之后可以通过 previous_response_id 基于该 ID 串联，使实际生成轮次更快启动。

继续运行

每个后续轮次都发送新的 response.create，并包含：

previous_response_id — 此链中上一响应的 ID。
input — 仅包含当前轮次的新项（通常是 tool 输出和下一条用户消息）。不要重新发送之前的历史；服务端已有这些内容。

ws.send(
    json.dumps(
        {
            "type": "response.create",
            "model": "grok-4.7",
            "store": False,
            "previous_response_id": "resp_123",
            "input": [
                {
                    "type": "function_call_output",
                    "call_id": "call_123",
                    "output": "tool result",
                },
                {
                    "type": "message",
                    "role": "user",
                    "content": [{"type": "input_text", "text": "Now optimize it."}],
                },
            ],
            "tools": [],
        }
    )
)

ws.send(
  JSON.stringify({
    type: "response.create",
    model: "grok-4.7",
    store: false,
    previous_response_id: "resp_123",
    input: [
      {
        type: "function_call_output",
        call_id: "call_123",
        output: "tool result",
      },
      {
        type: "message",
        role: "user",
        content: [{ type: "input_text", text: "Now optimize it." }],
      },
    ],
    tools: [],
  })
);

socket 上的串联方式

previous_response_id 的行为与 HTTP 相同，但 WebSocket 路径额外提供了内存内快捷方式。每条打开的连接都会在其专属缓存中保存最近一次响应的状态。从该响应继续可完全避免访问存储，这正是 WebSocket 模式能安全搭配 store=false 和 ZDR 使用的原因。

如果引用较早的 previous_response_id，而它已不在连接缓存中：

使用 store=true 时，服务端可能从持久化状态中恢复它，但会失去内存内延迟优势。
使用 store=false 或处于 ZDR 下时，没有可读取的后备存储，该轮次会因 previous_response_not_found 而失败。

失败的轮次（4xx 或 5xx）会从 Connection Cache 中清除对应的 previous_response_id，避免重试从损坏状态继续。

连接限制与行为

事件类型和顺序与现有 Responses 流式格式完全相同。
单个连接会串行处理轮次；在一个 response.create 正在进行时发送第二个，只会排队，不会进行多路复用。
需要并行轮次？请打开多个连接。
单个连接最多可保持 25 分钟。之后服务端会关闭连接，需要重新连接。

重新连接

套接字断开时（网络瞬断、部署或达到 25 分钟上限），请打开新连接并选择适用的恢复方式：

如果使用了 store=true 且仍有有效的响应 ID，只需在新套接字上使用 previous_response_id 和新的输入项继续。
否则（例如 store=false 或遇到 previous_response_not_found），请完全移除 previous_response_id，并通过发送下一轮的完整输入上下文开始新的链。

错误

有几类错误响应是 WebSocket 模式特有的，值得显式处理。

`previous_response_not_found`

当请求的 previous_response_id 不在连接缓存中，且无法从存储中恢复时返回（例如 ZDR、store=false，或因先前失败被清除）。

{
  "type": "error",
  "status": 400,
  "error": {
    "code": "previous_response_not_found",
    "message": "Previous response with id 'resp_abc' not found.",
    "param": "previous_response_id"
  }
}

`websocket_connection_limit_reached`

服务端即将关闭已达到最长 25 分钟的连接前会发送此错误。请打开新的 WebSocket，并使用上述任一模式重新连接。

{
  "type": "error",
  "status": 400,
  "error": {
    "type": "invalid_request_error",
    "code": "websocket_connection_limit_reached",
    "message": "Responses websocket connection limit reached (25 minutes). Create a new websocket connection to continue."
  }
}

最后更新：2026 年 9 月 2 日