如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

WebSockets

通过 WebSocket 连接由服务器管理的音频流。

选择您使用的 API,查看连接步骤和会话事件。

将服务器连接到 GPT-Live

我们建议使用 WebRTC 建立 GPT-Live 音频连接,包括服务器之间的连接。

GPT-Live 也支持 WebSocket。主 WebSocket 连接可双向传输音频和 JSON 事件。请将项目 API 密钥保存在您信任的服务器上。

本指南介绍如何将音频流发送到 GPT-Live。要监控或控制已有会话,请参阅服务器端控制。要将负责推理和工具调用的后端连接到 Responses API,请参阅 Responses WebSocket 模式。

进行身份验证并启动会话

  1. 连接到 wss://api.openai.com/v1/live/sessions,不要添加查询参数。使用 Authorization: Bearer $OPENAI_API_KEY 进行身份验证,并附上示例中所示的连接请求头。
  2. 将 session.start 作为第一条消息发送。在 session 对象中指定模型、对话指令、音频格式、音色和委派配置。
  3. 等待收到 session.started 后再发送音频或应用命令。该事件包含实际生效的会话配置和会话 ID。

下面的示例使用 Marin 音色、24 kHz 的 PCM16 音频,以及支持网页搜索的 Responses 后端。请保持对话指令简短。有关如何配置后端指令、工具和工具权限,请参阅委派与工具。

使用 SDK 传输音频流

如果使用 Node.js 22.6 或更高版本,请安装 openai 和 ws,安装命令为 npm install openai ws,然后将 TypeScript 示例保存为 client.mts。如果在 macOS 或 Linux 上使用 Python,请安装 openai[realtime],并将 Python 示例保存为 client.py。在服务器环境中设置 OPENAI_API_KEY。这些示例需要支持 Live 的 SDK 版本。示例从标准输入读取采样率为 24 kHz 的原始单声道 PCM16 音频,并将返回的音频以相同格式写入标准输出。请将输入流接到应用的音频采集端,将输出流接到播放端。日志和转写事件写入标准错误,以免破坏音频流。

如果使用 Go,请使用 Go 1.26 或更高版本,将示例保存为 main.go,使用 go mod init live-demo 初始化模块,然后安装 github.com/openai/openai-go/v3@v3.85.1,安装命令为 go get。如果使用 Java,请使用 Java 17 或更高版本,添加 Maven 依赖项 com.openai:openai-java:4.95.0,并使用 LiveConnectionWebsocketExample 类。如果使用 Ruby 3.3 或更高版本,请使用 gem install openai -v 0.110.0 安装 SDK,使用 gem install async-websocket 安装其 WebSocket 依赖项,并将示例保存为 client.rb。

import OpenAI from "openai";
import { LiveWS } from "openai/resources/live/ws";

// stdin and stdout carry raw mono PCM16 audio at 24 kHz, not WAV files.
// Supply microphone bytes continuously and play stdout in the same format.
process.stdin.pause();
const ws = new LiveWS(new OpenAI());
let started = false;
let closing = false;
let finalized = false;
let pendingByte = Buffer.alloc(0);

let closeTimeout: ReturnType<typeof setTimeout> | undefined;

ws.socket.on("open", () => {
  ws.send({
    type: "session.start",
    event_id: "event_start",
    session: {
      model: "gpt-live-1.1",
      instructions:
        "Be concise. Delegate requests needing current information to the backend, which can search the web.",
      audio: {
        format: { type: "audio/pcm", rate: 24000 },
        output: { voice: "marin" },
      },
      delegation: {
        type: "responses",
        responses: {
          model: "gpt-5.6-luna",
          tools: [{ type: "web_search" }],
          tool_choice: "auto",
        },
      },
    },
  });
});

process.stdin.on("data", (chunk) => {
  if (!started || closing || ws.socket.readyState !== 1) return;
  const bytes = Buffer.concat([pendingByte, chunk]);
  const completeLength = bytes.length - (bytes.length % 2);
  pendingByte = bytes.subarray(completeLength);
  if (completeLength) {
    ws.send({
      type: "session.input_audio.append",
      audio: bytes.subarray(0, completeLength).toString("base64"),
    });
  }
});

// Register the final-event handler before any close command can be sent.
ws.on("event", (event) => {
  if (event.type === "session.started") {
    started = true;
    console.error("Session ready", event.session.id);
    process.stdin.resume();
  } else if (event.type === "session.output_audio.delta") {
    process.stdout.write(Buffer.from(event.delta, "base64"));
  } else if (event.type === "session.closed") {
    finalized = true;
    clearTimeout(closeTimeout);
    process.stdin.pause();
    console.error("Final session usage", event.usage);
    ws.close();
  } else {
    // Includes transcript deltas and nested response.event usage.
    console.error(JSON.stringify(event));
  }
});

process.on("SIGINT", () => {
  if (closing) return;
  if (!started || ws.socket.readyState !== 1) {
    ws.socket.platformSocket.terminate();
    return;
  }
  closing = true;
  process.stdin.pause();
  ws.send({ type: "session.close" });
  closeTimeout = setTimeout(() => {
    console.error("Incomplete finalization: session.closed was not received");
    process.exitCode = 1;
    ws.socket.platformSocket.terminate();
  }, 15_000);
});
ws.on("error", (error) => {
  console.error(error.message);
  process.exitCode = 1;
});
ws.socket.on("close", () => {
  clearTimeout(closeTimeout);
  process.stdin.pause();
  if (!finalized) {
    console.error("Connection closed without final session usage");
    process.exitCode = 1;
  }
});

接好音频源和播放器后,运行 node --experimental-strip-types client.mts、python client.py、go run .、ruby client.rb 或您的 Java 应用。出现 Session ready 后,按录音时的采样率持续送入麦克风音频。通过管道一次性送入整个文件无法模拟实时麦克风输入。音频源到达文件末尾(EOF)时,对话不会结束。请向进程发送 SIGINT,请求正常关闭连接。

示例负责连接音频流。您的应用负责采集、缓冲和播放音频,并在需要时进行重采样。评估模型表现之前,请使用您的设备和网络测试这些环节。

选择音频格式

在启动时设置 session.audio.format。输入和输出使用同一种格式,会话期间无法更改。

  • {"type":"audio/pcm","rate":24000}:24 kHz 单声道有符号 16 位小端 PCM,为默认格式。
  • {"type":"audio/pcm","rate":16000}:16 kHz 单声道有符号 16 位小端 PCM。
  • {"type":"audio/pcmu","rate":8000}:8 kHz G.711 μ-law,每个采样点占一个字节。
  • {"type":"audio/pcma","rate":8000}:8 kHz G.711 A-law,每个采样点占一个字节。

对原始字节进行 Base64 编码,不要包含 WAV 或其他容器格式的文件头。每个 PCM 数据块都必须包含完整的 16 位采样值,因此字节数必须为偶数。如果末尾多出一个字节,示例会将其留到下一个输入数据块中处理。除此之外,您可以任意划分数据块,只需保持数据流连续且有序。

如果音频的采样率与配置的采样率不同,请进行重采样。更改格式设置不会转换输入字节。要将示例改为支持 G.711,请直接转发每个数据块中的编码字节,跳过 PCM 专用的双字节对齐逻辑,并将输出播放器配置为使用相同的编解码器。格式匹配的 G.711 音频流可以直接转发,无需转换为 PCM。有关如何接入电话通话,请参阅电话系统集成。

发送和接收事件

将每个事件作为一条 JSON 文本消息发送。音频以 Base64 编码的形式随消息传输。

  • 发送音频:发送 session.input_audio.append,在 audio 中提供经 Base64 编码的原始字节。追加音频后不会收到确认消息。
  • 接收音频:解码 delta 字段中的音频数据。每收到一个 session.output_audio.delta 事件,就将解码后的音频按顺序加入播放队列,按配置的格式播放。
  • 接收转写文本:将 delta 中的文本追加到相应的转写记录中。session.input_transcript.delta 对应输入音频,session.output_transcript.delta 对应输出音频。
  • 接收后端事件:使用 Responses 委派时,请处理嵌套的 event,该字段位于每条 response.event 消息中。
  • 处理错误:根据 error 事件处理被拒绝的命令和会话错误。如果事件中包含 error.client_event_id,请用它识别对应的命令。

通过应用的音频队列跟踪播放进度。GPT-Live 的主 WebSocket 连接发送输出音频时不会附带时间字段,也不会发送表示音频输出完毕的事件。您可以使用转写时间戳编排字幕,通过后端事件跟踪委派任务。

在持续传输音频的过程中,GPT-Live 会自行决定何时聆听、何时说话。使用 response.create 可以启动或继续执行委派给后端的任务。有关具体流程,请参阅委派与工具。

配置进行中的会话

Live 模型、初始对话指令、音频格式、音色和委派模式在启动时确定,之后无法更改。使用 session.update 可以更新当前委派模式支持的设置,未指定的设置保留当前值。更新成功后会返回 session.updated,其中包含实际生效的会话配置。

使用 session.instructions.append 追加对话指令,使用 session.input_audio.mute 或 session.input_audio.unmute 控制音频输入。将输入静音不会取消后端任务,也不会中断已生成的语音。有关上下文更新、转写、输入控制和用量的详情,请参阅管理会话。

关闭会话

在对话结束时发送 session.close。请先注册 session.closed 监听器,再发送关闭请求。随后持续接收消息,直到该事件到达,再释放连接。示例最多等待 15 秒,如果始终未收到结束事件,就会报告会话未能完成收尾。

请保存 session.closed 中的最终语音用量,以及此前收到的后端用量事件。每次更新的语音时长都是截至当时的累计值,请勿相加。如果在收到 session.closed 之前发生传输故障或超时,就无法确认最终用量。有关完整的会话生命周期,请参阅管理会话。