Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

WebSockets

Verbinde die Audiostreams deines Servers über WebSockets.

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

  1. Stelle ohne Abfrageparameter eine Verbindung zu wss://api.openai.com/v1/live/sessions her. Authentifiziere dich mit Authorization: Bearer $OPENAI_API_KEY und sende die im Beispiel gezeigten Verbindungsheader mit.
  2. Sende session.start als erste Nachricht. Gib Modell, Gesprächsanweisungen, Audioformat, Stimme und Delegationskonfiguration im Objekt session an.
  3. 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.append mit den Base64-kodierten Rohdaten im Feld audio. Für das Anhängen von Audiodaten erhältst du keine Bestätigung.
  • Audiodaten empfangen: Dekodiere delta aus jedem session.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 delta aus session.input_transcript.delta und session.output_transcript.delta an das jeweilige Transkript an.
  • Backend-Ereignisse empfangen: Wenn du Aufgaben an das Responses-Backend delegierst, verarbeite das eingebettete event in jeder response.event-Nachricht.
  • Fehler behandeln: Reagiere auf abgelehnte Befehle und Sitzungsfehler, die über error-Ereignisse gemeldet werden. Mit error.client_event_id kannst 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.