Wähle deine API aus, um zu sehen, wie du die Verbindung herstellst und welche Sitzungsereignisse es gibt.
Einen Server mit GPT-Live verbinden
Für Audioverbindungen mit GPT-Live empfehlen wir WebRTC. Das gilt auch für Server-zu-Server-Integrationen.
GPT-Live unterstützt auch WebSockets. Die primäre WebSocket-Verbindung überträgt Audiodaten und JSON-Ereignisse in beide Richtungen. Bewahre den API-Schlüssel deines Projekts auf deinem vertrauenswürdigen Server auf.
In dieser Anleitung erfährst du, wie du Audiodaten an GPT-Live streamst. Wie du eine bestehende Sitzung überwachst oder steuerst, erfährst du in der Anleitung zur serverseitigen Steuerung. Wie du ein Backend für Reasoning und Tools an die Responses API anbindest, erfährst du in der Anleitung zum WebSocket-Modus der Responses API.
Verbindung authentifizieren und Sitzung starten
- Stelle ohne Abfrageparameter eine Verbindung zu
wss://api.openai.com/v1/live/sessionsher. Authentifiziere dich mitAuthorization: Bearer $OPENAI_API_KEYund sende die im Beispiel gezeigten Verbindungsheader mit. - Sende
session.startals erste Nachricht. Gib Modell, Gesprächsanweisungen, Audioformat, Stimme und Delegationskonfiguration im Objektsessionan. - Warte auf
session.started, bevor du Audiodaten oder Anwendungsbefehle sendest. Das Ereignis enthält die tatsächlich verwendete Sitzungskonfiguration und die Sitzungs-ID.
Das folgende Beispiel verwendet die Stimme Marin, PCM16-Audio mit 24 kHz und ein Responses-Backend mit Websuche. Halte die Gesprächsanweisungen kurz. Wie du Backend-Anweisungen, Tools und deren Berechtigungen konfigurierst, erfährst du in der Anleitung Delegation und Tools.
Audio mit einem SDK streamen
Für Node.js ab Version 22.6 installierst du openai und ws mit npm install openai ws und speicherst das TypeScript-Beispiel als client.mts. Für Python unter macOS oder Linux installierst du openai[realtime] und speicherst das Python-Beispiel als client.py. Setze OPENAI_API_KEY in der Serverumgebung. Die Beispiele erfordern eine SDK-Version mit Live-Unterstützung. Das Beispiel liest rohe PCM16-Audiodaten in Mono mit 24 kHz von der Standardeingabe und schreibt die empfangenen Audiodaten im selben Format auf die Standardausgabe. Verbinde diese Streams mit der Audioaufnahme und -wiedergabe deiner Anwendung. Protokollmeldungen und Transkriptereignisse werden auf die Standardfehlerausgabe geschrieben, damit sie den Audiostream nicht beschädigen.
Für Go verwendest du Go 1.26 oder neuer, speicherst das Beispiel als main.go, initialisierst ein Modul mit go mod init live-demo und installierst github.com/openai/openai-go/v3@v3.85.1 mit go get. Für Java verwendest du Java 17 oder neuer, fügst die Maven-Abhängigkeit com.openai:openai-java:4.95.0 hinzu und verwendest die Klasse LiveConnectionWebsocketExample. Für Ruby ab Version 3.3 installierst du das SDK mit gem install openai -v 0.110.0 und seine WebSocket-Abhängigkeit mit gem install async-websocket. Speichere das Beispiel als 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",
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;
}
});Schließe deine Audioquelle und deinen Audioplayer an. Starte dann node --experimental-strip-types client.mts, python client.py, go run ., ruby client.rb oder deine Java-Anwendung. Sobald Session ready erscheint, sende einen kontinuierlichen Mikrofonstream im Takt der Abtastrate der Aufnahme. Wenn du eine ganze Datei auf einmal über eine Pipe einspeist, simulierst du damit kein Live-Mikrofon. Ein EOF an der Audioquelle beendet das Gespräch nicht. Sende SIGINT an den Prozess, um das geordnete Schließen der Verbindung anzufordern.
Das Beispiel verbindet die Audiostreams. Deine Anwendung übernimmt die Aufnahme, die Pufferung, die Wiedergabe und bei Bedarf die Umwandlung der Abtastrate. Teste diese Funktionen mit deinen Geräten und deinem Netzwerk, bevor du das Verhalten des Modells beurteilst.
Audioformat auswählen
Lege session.audio.format beim Start fest. Dasselbe Format gilt für Ein- und Ausgabe und lässt sich während der Sitzung nicht ändern.
{"type":"audio/pcm","rate":24000}: vorzeichenbehaftetes 16-Bit-PCM in Little-Endian-Bytefolge, mono, mit 24 kHz (Standard).{"type":"audio/pcm","rate":16000}: vorzeichenbehaftetes 16-Bit-PCM in Little-Endian-Bytefolge, mono, mit 16 kHz.{"type":"audio/pcmu","rate":8000}: G.711 μ-law mit 8 kHz und einem Byte pro Abtastwert.{"type":"audio/pcma","rate":8000}: G.711 A-law mit 8 kHz und einem Byte pro Abtastwert.
Kodiere die Rohdaten ohne WAV- oder sonstigen Container-Header in Base64. Jeder PCM-Block muss vollständige 16-Bit-Abtastwerte enthalten. Seine Länge in Bytes muss daher gerade sein. Bleibt am Ende eines Eingabeblocks ein Byte übrig, übernimmt das Beispiel es in den nächsten Block. Ansonsten kannst du die Blockgrenzen frei wählen, solange du die Daten lückenlos und in der richtigen Reihenfolge überträgst.
Weicht die Abtastrate der Audiodaten von der konfigurierten Rate ab, rechne die Daten auf die konfigurierte Rate um. Eine Änderung der Formateinstellung allein wandelt die Eingabebytes nicht um. Um das Beispiel für G.711 anzupassen, leite die Codec-Bytes jedes Blocks direkt weiter. Lass dabei die PCM-spezifische Ausrichtung an Zwei-Byte-Grenzen weg und stelle den Audioplayer auf denselben Codec ein. Einen passenden G.711-Stream kannst du ohne Umwandlung in PCM durchleiten. Wie du ein Telefongespräch anbindest, erfährst du in der Anleitung zu Telefonie-Integrationen.
Ereignisse senden und empfangen
Sende jedes Ereignis als JSON-Textnachricht. Audiodaten werden in diesen Nachrichten als Base64 übertragen.
- Audiodaten senden: Sende
session.input_audio.appendmit den Base64-kodierten Rohdaten im Feldaudio. Für das Anhängen von Audiodaten erhältst du keine Bestätigung. - Audiodaten empfangen: Dekodiere
deltaaus jedemsession.output_audio.delta-Ereignis. Lege die Audiodaten in der empfangenen Reihenfolge in die Wiedergabewarteschlange und verwende für die Wiedergabe das konfigurierte Format. - Transkripte empfangen: Hänge den Text im Feld
deltaaussession.input_transcript.deltaundsession.output_transcript.deltaan das jeweilige Transkript an. - Backend-Ereignisse empfangen: Wenn du Aufgaben an das Responses-Backend delegierst, verarbeite das eingebettete
eventin jederresponse.event-Nachricht. - Fehler behandeln: Reagiere auf abgelehnte Befehle und Sitzungsfehler, die über
error-Ereignisse gemeldet werden. Miterror.client_event_idkannst du den zugehörigen Befehl ermitteln, sofern das Feld vorhanden ist.
Verfolge die Wiedergabe anhand der Audio-Warteschlange deiner Anwendung. Über die primäre WebSocket-Verbindung sendet GPT-Live die Audioausgabe ohne Zeitangaben und ohne Ereignis, das ihr Ende signalisiert. Richte Untertitel an den Zeitstempeln im Transkript aus und verfolge delegierte Aufgaben anhand der Backend-Ereignisse.
Während der Audiostream läuft, entscheidet GPT-Live, wann es zuhört und wann es spricht. Mit response.create kannst du delegierte Aufgaben im Backend starten oder fortsetzen. Den Ablauf beschreibt die Anleitung Delegation und Tools.
Eine laufende Sitzung konfigurieren
Das Live-Modell, die anfänglichen Gesprächsanweisungen, das Audioformat, die Stimme und der Delegationsmodus stehen beim Start fest. Mit session.update kannst du die Einstellungen ändern, die der aktuelle Delegationsmodus unterstützt. Für Einstellungen, die du weglässt, gelten die bisherigen Werte. Bei erfolgreicher Aktualisierung erhältst du session.updated mit der tatsächlich verwendeten Sitzungskonfiguration.
Mit session.instructions.append kannst du Gesprächsanweisungen ergänzen. Mit session.input_audio.mute und session.input_audio.unmute kannst du den Audioeingang stummschalten und wieder aktivieren. Das Stummschalten bricht weder laufende Backend-Aufgaben ab noch stoppt es die generierte Sprachausgabe. Wie du den Kontext aktualisierst, mit Transkripten arbeitest, die Eingabe steuerst und die Nutzung erfasst, erfährst du in der Anleitung Sitzungen verwalten.
Sitzung schließen
Sende session.close, wenn das Gespräch endet. Registriere vorher den Listener für session.closed. Empfange weiter Nachrichten, bis dieses Ereignis eintrifft, und gib die Verbindung erst danach frei. Das Beispiel wartet bis zu 15 Sekunden. Bleibt das abschließende Ereignis aus, meldet es, dass die Sitzung nicht vollständig abgeschlossen wurde.
Speichere die endgültigen Nutzungsdaten für die Sprachverarbeitung aus session.closed und die bereits empfangenen Ereignisse zur Backend-Nutzung. Jede Aktualisierung der Sprachdauer enthält die bisherige Gesamtdauer. Addiere diese Werte nicht. Tritt vor session.closed ein Übertragungsfehler oder eine Zeitüberschreitung auf, bleibt die endgültige Nutzung unbestätigt. Den gesamten Lebenszyklus beschreibt die Anleitung Sitzungen verwalten.
WebSockets sind eine weithin unterstützte API für die Datenübertragung in Echtzeit. Sie eignen sich gut, um Server-zu-Server-Anwendungen mit der Realtime API von OpenAI zu verbinden. Für Browser und mobile Clients empfehlen wir eine Verbindung über WebRTC.
Bei einer Server-zu-Server-Integration mit Realtime stellt dein Backend über WebSocket eine direkte Verbindung zur Realtime API her. Du kannst die Verbindung mit einem Standard-API-Schlüssel authentifizieren, da das Token nur auf deinem abgesicherten Backend-Server verfügbar ist.
Verbindung über WebSocket herstellen
Die folgenden Beispiele zeigen, wie du über WebSocket eine Verbindung zur Realtime API herstellst. Verwende die unten angegebene WebSocket-URL und sende einen Authentifizierungsheader mit deinem OpenAI-API-Schlüssel. Wenn deine Anwendung Sicherheitskennungen vergibt, übergib die dauerhafte, datenschutzwahrende Kennung der Person, die deine Anwendung nutzt, im Header OpenAI-Safety-Identifier.
Auch im Browser kannst du WebSocket mit einem kurzlebigen API-Token verwenden, wie in der Anleitung zur Verbindung über WebRTC beschrieben. Für Verbindungen von einem Client wie einem Browser oder einer mobilen App ist WebRTC jedoch in den meisten Fällen die robustere Lösung.
ws-Modul (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.")Installiere die erforderlichen Gems mit
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
endVerwende Java 17 oder neuer mit 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;
}
}
}Verwende Go 1.26 oder neuer und installiere das SDK mit
go get github.com/openai/openai-go/v3@v3.85.1. Das SDK
übernimmt die Datenübertragung über den Socket. Deine Anwendung verarbeitet
Ereignisse, nimmt Audio auf, gibt es wieder und stellt nach einem erneuten
Verbindungsaufbau den Sitzungszustand wieder her.
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()Installiere das SDK mit
dotnet add package OpenAI –version 2.14.0. Die Realtime API
verwendet experimentelle SDK-Typen. Das Beispiel enthält die dafür
erforderliche Compiler-Direktive für Warnungen.
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);
});Ereignisse senden und empfangen
Eine Sitzung der Realtime API verwaltest du mithilfe von Ereignissen, die dein Client sendet, und Ereignissen, die der Server sendet. Mit den Serverereignissen informiert dich die Realtime API über den Verlauf der Sitzung.
Über eine WebSocket-Verbindung sendest und empfängst du Ereignisse als JSON-serialisierte Zeichenketten. Das folgende Node.js-Beispiel zeigt, wie das funktioniert. Für andere WebSocket-Bibliotheken gilt dasselbe Prinzip.
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()));
});Die WebSocket-Schnittstelle bietet dir wohl den direktesten Zugriff auf ein Realtime-Modell. Dabei übernimmst du selbst das Senden und Verarbeiten der Base64-kodierten Audioblöcke über die Socket-Verbindung.
Wie du Audiodaten über WebSockets sendest und empfängst, erfährst du in der Anleitung zu Realtime-Gesprächen.