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

WebRTC

Verbinde Sprachanwendungen über WebRTC.

Wähle deine API aus, um die Schritte zum Verbindungsaufbau und die zugehörigen Sitzungsereignisse anzuzeigen.

Einen Browser mit GPT-Live verbinden

Für Audioverbindungen zu GPT-Live in Browser-, Mobil- und Serveranwendungen empfehlen wir WebRTC. Diese Anleitung zeigt den Ablauf anhand eines Browserbeispiels. Die ausgehandelten Medienspuren übertragen das Mikrofonsignal und die generierte Sprache. Über einen Datenkanal laufen JSON-Ereignisse für Transkripte, Sitzungsaktualisierungen und delegierte Aufgaben.

Dein Browser erstellt ein Angebot nach dem Session Description Protocol (SDP). Dein Anwendungsserver sendet das Angebot mit POST /v1/live/sessions und dem API-Schlüssel deines Projekts an OpenAI und erhält eine SDP-Antwort. Bewahre den Schlüssel und die Sitzungskonfiguration auf deinem vertrauenswürdigen Server auf.

Voraussetzungen

Du brauchst Folgendes:

  • Einen Projekt-API-Schlüssel mit Zugriff auf GPT-Live.
  • Eine Serverlaufzeit für das gewählte SDK-Beispiel. Für das Node.js-Beispiel brauchst du Node.js 22.6 oder neuer.
  • Einen Browser mit Mikrofonberechtigung, in dem du die Anwendung über HTTPS oder localhost aufrufst.

Das Beispiel delegiert Aufgaben an Responses und nutzt dafür gpt-5.6-terra und die gehostete Websuche. Informationen zu Backend-Anweisungen und Tools deiner Anwendung findest du im Leitfaden Delegation und Tools. Wie sich die Nutzung von Sprachfunktionen und Backend auf die Kosten auswirkt, erfährst du im Leitfaden Kosten optimieren.

So läuft der Verbindungsaufbau ab

  1. Fordere als Reaktion auf eine Nutzeraktion Zugriff auf das Mikrofon an und füge die Mikrofonspuren einer Peer-Verbindung hinzu.
  2. Erstelle den Datenkanal und registriere die Ereignislistener, bevor du das SDP-Angebot erstellst.
  3. Setze die lokale Sitzungsbeschreibung. Warte, bis WebRTC die ICE-Kandidaten gesammelt hat, und sende dann das Angebot an deinen Server.
  4. Lass deinen Server per POST ein JSON-Objekt mit session und transport: { type: "webrtc", sdp: ... } an OpenAI senden.
  5. Übernimm die zurückgegebene SDP-Antwort als Sitzungsbeschreibung der Gegenstelle. Warte, bis session.started auf dem Datenkanal eintrifft, bevor du Anwendungsbefehle sendest.

Die HTTP-Anfrage startet die Sitzung. Sende session.start nicht über den Datenkanal. Die Zeichenfolge oai-events bezeichnet im Beispiel den Datenkanal.

Wenn du mit POST /v1/live/sessions eine WebRTC-Sitzung erstellst, werden bei der Initialisierung 15 Sekunden Sprachnutzung berechnet. Sobald die Sitzung läuft, wird dieser Betrag auf die zeitabhängigen Gebühren angerechnet. Zur Laufzeit der Sitzung kommen also keine zusätzlichen 15 Sekunden hinzu. Einzelheiten zur Abrechnung findest du im Abschnitt Gebühren für die WebRTC-Initialisierung.

Anwendungsserver erstellen

Speichere das Serverbeispiel in einem neuen Verzeichnis und setze OPENAI_API_KEY in der Serverumgebung. Verwende für TypeScript Node.js 22.6 oder neuer und speichere das Beispiel als server.ts. Führe zuerst npm install openai express und danach npm pkg set type=module aus. Installiere für Python openai. Der Beispielserver lauscht auf 127.0.0.1, akzeptiert Sitzungsanfragen von http://localhost:3000 und liefert index.html aus dem Verzeichnis aus, in dem du ihn startest.

Speichere das Go-Beispiel als main.go, initialisiere mit go mod init live-demo ein Modul und installiere github.com/openai/openai-go/v3@v3.85.1 mit go get. Führe go run . mit Go 1.26 oder neuer aus. Verwende für Java die Version 17 oder neuer, füge die Maven-Abhängigkeit com.openai:openai-java:4.95.0 hinzu und führe die Klasse LiveConnectionWebrtcExample aus. Installiere für Ruby 3.3 oder neuer openai in Version 0.110.0 und webrick mit den Befehlen gem install openai -v 0.110.0 und gem install webrick. Speichere das Beispiel als server.rb und führe ruby server.rb aus.

Wähle unten eine Sprache für den Server. Jede Variante liefert index.html aus und stellt denselben Endpunkt /api/session auf Port 3000 bereit. Verwende eine SDK-Version, die Live unterstützt, und führe jeweils nur eine Variante aus.

import express from "express";
import OpenAI from "openai";
import { readFile } from "node:fs/promises";
import { resolve } from "node:path";

const app = express();
const client = new OpenAI({ maxRetries: 0 });
const port = 3000;
const origin = `http://localhost:${port}`;
const indexPath = resolve("index.html");

app.use(express.json({ limit: "64kb" }));
app.get("/", async (_request, response) => {
  response.type("html").send(await readFile(indexPath, "utf8"));
});

// Local-only demo. Add your application's authentication and authorization
// before exposing session creation to other users.
app.post("/api/session", async (request, response) => {
  if (request.headers.origin !== origin) {
    response.status(403).json({ error: "Unexpected request origin" });
    return;
  }
  if (typeof request.body?.sdp !== "string" || !request.body.sdp.trim()) {
    response.status(400).json({ error: "An SDP offer is required" });
    return;
  }
  if (!process.env.OPENAI_API_KEY) {
    response.status(503).json({ error: "Set OPENAI_API_KEY on the server" });
    return;
  }

  try {
    const result = await client.live.create({
      session: {
        model: "gpt-live-1",
        instructions:
          "Be concise. Delegate requests needing current information to the backend, which can search the web.",
        delegation: {
          type: "responses",
          responses: {
            model: "gpt-5.6-terra",
            instructions:
              "Use web search when current facts are needed. Return concise, grounded results for a spoken conversation.",
            tools: [{ type: "web_search" }],
            tool_choice: "auto",
          },
        },
      },
      transport: {
        type: "webrtc",
        sdp: request.body.sdp,
      },
    });
    // Preserve the SDK's typed session ID and SDP answer.
    response.status(201).json(result);
  } catch (error) {
    if (!(error instanceof OpenAI.APIError)) throw error;
    console.error("Live session creation failed", error.status);
    response
      .status(error.status ?? 502)
      .json({ error: "Live session creation failed" });
  }
});

app.listen(port, "127.0.0.1", () => console.log(`Open ${origin}`));

Bevor du den Server für andere zugänglich machst, schütze /api/session mit der Authentifizierung und Autorisierung deiner Anwendung. Begrenze die Anzahl der Anfragen und verwende HTTPS. Die Prüfung der Herkunft einer Anfrage in diesem lokalen Beispiel authentifiziert die anfragende Person nicht.

Browserclient erstellen

Erstelle index.html in dem Verzeichnis, in dem du den Server startest:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>GPT-Live connection</title>
  </head>
  <body>
    <script type="module">
      // Paste the compiled contents of browser.js here.
    </script>
  </body>
</html>

Speichere den folgenden TypeScript-Code als browser.ts. Er fügt Bedienelemente zum Starten und Beenden des Gesprächs hinzu, bindet das Mikrofon und die Audiowiedergabe an und verarbeitet Sitzungsereignisse. /api/session ist eine Route auf deinem Anwendungsserver.

const start = document.createElement("button");
start.textContent = "Start conversation";
const stop = document.createElement("button");
stop.textContent = "End conversation";
stop.disabled = true;
const status = document.createElement("p");
const audio = new Audio();
audio.autoplay = true;
audio.controls = true;
document.body.append(start, stop, status, audio);

let peer: RTCPeerConnection;

let events: RTCDataChannel | undefined;

let microphone: MediaStream;

let closeTimeout: ReturnType<typeof setTimeout> | undefined;
let ready = false;
let finalized = false;

function cleanup() {
  clearTimeout(closeTimeout);
  microphone?.getTracks().forEach((track) => track.stop());
  const closingEvents = events;
  events = undefined;
  closingEvents?.close();
  peer?.close();
  audio.srcObject = null;
  ready = false;
  start.disabled = false;
  stop.disabled = true;
}

start.addEventListener("click", async () => {
  start.disabled = true;
  finalized = false;
  status.textContent = "Connecting…";
  try {
    const connection = new RTCPeerConnection();
    peer = connection;
    connection.addEventListener("track", (event) => {
      audio.srcObject = new MediaStream([event.track]);
      audio.play().catch(() => {
        status.textContent =
          "Select play on the audio controls to hear the assistant.";
      });
    });
    microphone = await navigator.mediaDevices.getUserMedia({ audio: true });
    for (const track of microphone.getAudioTracks()) {
      connection.addTrack(track, microphone);
    }

    // Create the event channel before creating the SDP offer.
    events = connection.createDataChannel("oai-events");
    events.addEventListener("message", ({ data }) => {
      const event = JSON.parse(data);
      if (event.type === "session.started") {
        ready = true;
        stop.disabled = false;
        status.textContent = "Connected: " + event.session.id;
      } else if (event.type === "session.closed") {
        finalized = true;
        console.log("Final session usage", event.usage);
        status.textContent = "Conversation ended.";
        cleanup();
      } else {
        // Save transcript and nested Responses events as needed by your app.
        console.log(event);
      }
    });
    events.addEventListener("close", (event) => {
      if (event.target !== events) return;
      if (!finalized) {
        status.textContent = "Disconnected without final session usage.";
        cleanup();
      }
    });

    const offer = await connection.createOffer();
    await connection.setLocalDescription(offer);
    if (connection.iceGatheringState !== "complete") {
      await new Promise((resolve, reject) => {
        const timeout = setTimeout(() => {
          connection.removeEventListener("icegatheringstatechange", onState);
          reject(new Error("Timed out while gathering ICE candidates"));
        }, 10_000);
        function onState() {
          if (connection.iceGatheringState !== "complete") return;
          clearTimeout(timeout);
          connection.removeEventListener("icegatheringstatechange", onState);
          resolve(undefined);
        }
        connection.addEventListener("icegatheringstatechange", onState);
        onState();
      });
    }

    const sdp = connection.localDescription?.sdp;
    if (!sdp) throw new Error("Missing local SDP offer");
    const response = await fetch("/api/session", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ sdp }),
    });
    if (!response.ok) throw new Error(await response.text());

    const result = await response.json();
    console.log("Created session", result.session.id);
    await connection.setRemoteDescription({
      type: "answer",
      sdp: result.transport.sdp,
    });
    // The HTTP request started this session. Do not send session.start here.
  } catch (error) {
    status.textContent =
      error instanceof Error ? error.message : String(error);
    cleanup();
  }
});

stop.addEventListener("click", () => {
  if (!ready || !events || events.readyState !== "open") return;
  stop.disabled = true;
  status.textContent = "Finishing the conversation…";
  // The session.closed handler is already registered. Keep media and events
  // alive while pending work drains; only clean up after the final event.
  events.send(JSON.stringify({ type: "session.close" }));
  closeTimeout = setTimeout(() => {
    status.textContent = "Incomplete finalization: no session.closed event.";
    cleanup();
  }, 15_000);
});

Kompiliere browser.ts mit den folgenden Befehlen. Ersetze anschließend den Platzhalter im Modulskript durch den Inhalt der erzeugten Datei browser.js.

npm install --save-dev esbuild
npx esbuild browser.ts --format=esm --outfile=browser.js

Starte die gewählte Servervariante (node --experimental-strip-types server.ts oder python server.py), öffne http://localhost:3000 und wähle „Start conversation“. Sobald der Status „Connected“ erscheint, stelle eine Frage, für deren Beantwortung aktuelle Informationen nötig sind. So testest du die gehostete Websuche. Falls dein Browser die automatische Wiedergabe blockiert, starte sie über die Audiosteuerung.

Sitzungsantwort auslesen

Bei einer erfolgreichen Anfrage erhältst du den HTTP-Statuscode 201 und ein JSON-Objekt mit der Sitzungs-ID und der SDP-Antwort:

{
  "session": { "id": "live_123" },
  "transport": { "type": "webrtc", "sdp": "<SDP answer>" }
}

Lies result.session.id aus und übergib result.transport.sdp an setRemoteDescription. Interpretiere die Bestandteile der Sitzungs-ID nicht und behalte die gesamte ID einschließlich ihres Präfixes unverändert bei.

Wie du die Latenz beim Verbindungsaufbau verringerst, erfährst du im Leitfaden WebRTC mit WARP.

Medien übertragen und Ereignisse verarbeiten

Sende das Mikrofonsignal und empfange die generierte Sprache über die Medienspuren. WebRTC handelt das Audioformat über SDP aus. Lass deshalb audio.format in der Sitzungskonfiguration weg. Sende session.input_audio.append nicht über den Datenkanal. Dort erhältst du auch keine Ereignisse vom Typ session.output_audio.delta.

Verwende den Datenkanal für inkrementelle Transkriptänderungen, Sitzungsbefehle und verschachtelte response.event-Nachrichten. Wie du Transkripte und Ereignisse im Lebenszyklus einer Sitzung verarbeitest, erfährst du im Leitfaden Sitzungen verwalten. Falls dein Server eine eigene Verbindung für Ereignisse benötigt, lies den Leitfaden Serverseitige Steuerung.

Sende zum Beenden des Gesprächs session.close und empfange weiterhin Ereignisse, bis session.closed eintrifft. Schließe erst dann die Peer-Verbindung und beende die Mikrofonspuren. Das Beispiel registriert den Listener für das Abschlussereignis, bevor es den Befehl sendet. Falls die Verbindung vorher abbricht oder das Zeitlimit überschritten wird, sind die endgültigen Nutzungsdaten unbestätigt. Wie du diese Daten verarbeitest, erfährst du im Abschnitt Nutzungsdaten erfassen und Sitzungen geordnet beenden.