选择您使用的 API,查看连接步骤和会话事件。
将服务器连接到 GPT-Live
我们建议使用 WebRTC 建立 GPT-Live 音频连接,包括服务器之间的连接。
GPT-Live 也支持 WebSocket。主 WebSocket 连接可双向传输音频和 JSON 事件。请将项目 API 密钥保存在您信任的服务器上。
本指南介绍如何将音频流发送到 GPT-Live。要监控或控制已有会话,请参阅服务器端控制。要将负责推理和工具调用的后端连接到 Responses API,请参阅 Responses WebSocket 模式。
进行身份验证并启动会话
- 连接到
wss://api.openai.com/v1/live/sessions,不要添加查询参数。使用Authorization: Bearer $OPENAI_API_KEY进行身份验证,并附上示例中所示的连接请求头。 - 将
session.start作为第一条消息发送。在session对象中指定模型、对话指令、音频格式、音色和委派配置。 - 等待收到
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 之前发生传输故障或超时,就无法确认最终用量。有关完整的会话生命周期,请参阅管理会话。
WebSockets 是一种广泛受支持的实时数据传输 API,适合在服务器之间通信的应用中连接 OpenAI Realtime API。对于浏览器和移动客户端,我们建议通过 WebRTC 建立连接。
在服务器之间集成 Realtime 时,您的后端系统会通过 WebSocket 直接连接到 Realtime API。您可以使用标准 API 密钥对该连接进行身份验证,因为只有您的安全后端服务器可以访问此令牌。
通过 WebSocket 建立连接
下面的示例展示了如何通过 WebSocket 连接到 Realtime API。除了使用下方的 WebSocket URL,您还需要在身份验证请求头中传入您的 OpenAI API 密钥。如果您的应用会分配安全标识符,请在 OpenAI-Safety-Identifier 请求头中传入最终用户的标识符。该标识符应保持稳定,并保护用户隐私。
如 WebRTC 连接指南所示,您可以在浏览器中使用临时 API 令牌建立 WebSocket 连接。不过,从浏览器或移动应用等客户端发起连接时,WebRTC 在大多数情况下更可靠。
ws 模块(Node.js)
import WebSocket from "ws";
const url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1";
const ws = new WebSocket(url, {
headers: {
Authorization: "Bearer " + process.env.OPENAI_API_KEY,
"OpenAI-Safety-Identifier": "hashed-user-id",
},
});
let connected = false;
ws.on("message", function incoming(message) {
const event = JSON.parse(message.toString());
if (event.type === "error") throw new Error(event.error.message);
if (event.type === "session.created") {
connected = true;
console.log(`Connected to the Realtime API: ${event.session.id}`);
ws.close(1000);
}
});
ws.on("close", () => {
if (!connected)
throw new Error("Connection closed before the session was created");
});# example requires websocket-client library:
# pip install websocket-client
import os
import json
import websocket
OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]
url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"
headers = [
"Authorization: Bearer " + OPENAI_API_KEY,
"OpenAI-Safety-Identifier: hashed-user-id",
]
session_created = False
def on_message(ws, message):
global session_created
data = json.loads(message)
if data["type"] == "session.created":
session_created = True
print("Connected to the Realtime API:", data["session"]["id"])
ws.close()
elif data["type"] == "error":
ws.close()
ws = websocket.WebSocketApp(
url,
header=headers,
on_message=on_message,
)
ws.run_forever()
if not session_created:
raise RuntimeError("Connection closed before the Realtime session was created.")要安装所需的 gem 包,请运行
gem install openai async-websocket。
require "openai"
client = OpenAI::Client.new(
default_headers: { "OpenAI-Safety-Identifier" => "hashed-user-id" }
)
client.realtime.connect(model: "gpt-realtime-2.1") do |connection|
created = connection.find do |event|
raise event.error.message if event.is_a?(OpenAI::Realtime::RealtimeErrorEvent)
next unless event.is_a?(OpenAI::Realtime::SessionCreatedEvent)
puts("Connected to the Realtime API: #{event.session[:id]}")
true
end
raise "Connection closed before the session was created" unless created
end请使用 Java 17 或更高版本,并添加依赖项 com.openai:openai-java:4.75.1。
import com.openai.client.okhttp.OkHttpClient;
import com.openai.core.ClientOptions;
import com.openai.helpers.RealtimeConnection;
import com.openai.helpers.RealtimeWebSocketOptions;
import com.openai.models.realtime.*;
var http = OkHttpClient.builder().build();
var options =
ClientOptions.builder()
.fromEnv()
.httpClient(http)
.putHeader("OpenAI-Safety-Identifier", "hashed-user-id")
.build();
try (http;
var connection =
RealtimeConnection.connect(
options,
RealtimeWebSocketOptions.builder().model("gpt-realtime-2.1").build())) {
while (true) {
var event = connection.receive();
if (event.error().isPresent())
throw new IllegalStateException(event.error().orElseThrow().toString());
if (event.sessionCreated().isPresent()) {
System.out.println("Connected to server.");
System.out.println(event);
break;
}
}
}请使用 Go 1.26 或更高版本,并运行
go get github.com/openai/openai-go/v3@v3.85.1 安装 SDK。SDK 负责管理套接字传输。您的应用负责处理事件、采集和播放音频,并在重新连接后恢复会话状态。
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := openai.NewClient()
conn, err := client.Realtime.Connect(ctx, realtime.RealtimeConnectionOptions{}, option.WithQuery("model", "gpt-realtime-2.1"), option.WithHeader("OpenAI-Safety-Identifier", "hashed-user-id"))
if err != nil {
return err
}
defer conn.Close()运行
dotnet add package OpenAI –version 2.14.0 安装 SDK。Realtime API 使用实验性的 SDK 类型,示例中包含处理相关警告所需的指令。
using OpenAI.Realtime;
#pragma warning disable OPENAI002
string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
RealtimeClient client = new(key);
RealtimeSessionClientOptions options = new();
options.Headers["OpenAI-Safety-Identifier"] = "hashed-user-id";
using CancellationTokenSource timeout = new(TimeSpan.FromSeconds(30));
using RealtimeSessionClient session = await client.StartConversationSessionAsync("gpt-realtime-2.1", options, cancellationToken: timeout.Token);
await foreach (RealtimeServerUpdate update in session.ReceiveUpdatesAsync(timeout.Token))
{
if (update is RealtimeServerUpdateError error)
throw new InvalidOperationException(error.Error.Message);
if (update is RealtimeServerUpdateSessionCreated)
{
Console.WriteLine("Connected to server.");
Console.WriteLine(System.ClientModel.Primitives.ModelReaderWriter.Write(update));
return;
}
}
throw new InvalidOperationException("Connection closed before session creation.");/*
Note that in client-side environments like web browsers, we recommend
using WebRTC instead. It is possible, however, to use the standard
WebSocket interface in browser-like environments like Deno and
Cloudflare Workers.
*/
const ws = new WebSocket(
"wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1",
[
"realtime",
// Use a short-lived token fetched from your application server.
"openai-insecure-api-key." + OPENAI_REALTIME_EPHEMERAL_KEY,
]
);
ws.addEventListener("open", function open() {
console.log("Connected to server.");
});
ws.addEventListener("message", function incoming(event) {
console.log(event.data);
});发送和接收事件
管理 Realtime API 会话需要配合使用两类事件:由您的应用发出的客户端事件,以及由 Realtime API 生成、用于通知会话生命周期变化的服务器端事件。
通过 WebSocket 收发事件时,事件会序列化为 JSON,并以文本字符串的形式传输。下面以 Node.js 为例,其他 WebSocket 库也遵循相同的原理。
import WebSocket from "ws";
const url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1";
const ws = new WebSocket(url, {
headers: {
Authorization: "Bearer " + process.env.OPENAI_API_KEY,
"OpenAI-Safety-Identifier": "hashed-user-id",
},
});
ws.on("open", function open() {
console.log("Connected to server.");
// Send client events over the WebSocket once connected
ws.send(
JSON.stringify({
type: "session.update",
session: {
type: "realtime",
instructions: "Be extra nice today!",
},
})
);
});
// Listen for and parse server events
ws.on("message", function incoming(message) {
console.log(JSON.parse(message.toString()));
});在与 Realtime 模型交互的可用接口中,WebSocket 可能是最底层的接口。您需要自行通过套接字连接发送和处理经过 Base64 编码的音频块。
有关如何通过 WebSocket 发送和接收音频,请参阅实时对话指南。