GPT-Realtime-2: Technischer Leitfaden — WebSocket API, Verbindung und Codebeispiele

Dieser Artikel ist ein praktischer Leitfaden für Entwickler, die GPT-Realtime-2 in ihr Projekt integrieren möchten. Wir werden die Architektur der Realtime API untersuchen, die richtige Verbindungsmethode für Ihr Szenario auswählen, die erste funktionierende Sitzung von Grund auf neu schreiben und Preambles, Tool-Aufrufe und Wiederherstellung mit echtem Code einrichten.

Wenn Sie Kontext darüber benötigen, worum es bei dieser Veröffentlichung geht und warum sie wichtig ist – lesen Sie zuerst den Nachrichtenartikel: → OpenAI hat GPT-Realtime-2 veröffentlicht: das erste Sprachmodell mit GPT-5-Denkniveau

Kurz gesagt: GPT-Realtime-2 wird über WebSocket (Server), WebRTC (Browser) oder SIP (Telefonie) verbunden. Dies ist keine REST-API – es ist eine kontinuierliche bidirektionale Verbindung. Alle Codebeispiele im Artikel stammen aus der offiziellen OpenAI-Dokumentation und wurden auf Aktualität im Mai 2026 überprüft.

Inhalt des Artikels

• Realtime API vs. Chat Completions API – Was ist der prinzipielle Unterschied der Protokolle
• Speech-to-Speech-Architektur – Wie das Modell Audio ohne Zwischenschritte verarbeitet
• Drei Verbindungsmethoden: WebSocket, WebRTC, SIP – Welche für Ihr Szenario wählen
• Verbindung über WebSocket – Schritt-für-Schritt-Anleitung mit Code in JS und Python
• Erste funktionierende Sitzung: Verbindung öffnen, Audio senden, Antwort erhalten
• Preambles, parallele Tool-Aufrufe und Wiederherstellung – Einrichtung und Codebeispiele
• Reasoning-Aufwand und Kontextfenster – Wie man das Gleichgewicht zwischen Qualität, Geschwindigkeit und Kosten einstellt
• GPT-Realtime-Translate und GPT-Realtime-Whisper – Verbindung und Anwendungsfälle
• Typische Fehler und wie man sie vermeidet
• FAQ
• Schlussfolgerungen

Realtime API vs. Chat Completions API – Was ist der prinzipielle Unterschied der Protokolle

Bevor Sie mit dem Codieren beginnen, ist es wichtig zu verstehen, womit Sie arbeiten. Realtime API und Chat Completions API sind keine zwei Versionen desselben Tools. Es handelt sich um grundlegend unterschiedliche Protokolle für unterschiedliche Aufgaben.

Chat Completions API – HTTP-Anfrage-Antwort

Die Chat Completions API funktioniert nach dem klassischen HTTP-Schema:

1. Der Client sendet eine POST-Anfrage mit Nachrichten
2. Der Server verarbeitet und gibt eine Antwort zurück
3. Die Verbindung wird geschlossen

Selbst das Streaming in Chat Completions (wenn Text schrittweise erscheint) wird über Server-Sent Events (SSE) implementiert – technisch gesehen ist dies ein unidirektionaler Stream über HTTP, keine bidirektionale Verbindung. Der Client hört zu, der Server schreibt – aber nicht umgekehrt gleichzeitig.

Realtime API – Kontinuierliches bidirektionales WebSocket

Die Realtime API arbeitet über WebSocket – ein Protokoll, das eine kontinuierliche Verbindung zwischen Client und Server herstellt. Nach dem Handshake können beide Seiten jederzeit unabhängig voneinander Daten senden:

• Der Client streamt Audio-Chunks, während der Benutzer spricht
• Das Modell antwortet mit Audio-Chunks, noch bevor die Frage vollständig ist
• Beide Streams laufen gleichzeitig über eine einzige Verbindung
• Die Verbindung bleibt während des gesamten Gesprächs bestehen (maximal 60 Minuten pro Sitzung)

Der entscheidende Unterschied für den Entwickler: Bei Chat Completions senden Sie eine Anfrage und warten. Bei der Realtime API pflegen Sie eine kontinuierliche Verbindung und reagieren auf Ereignisse. Dies ähnelt eher der Entwicklung eines WebSocket-Chats als eines herkömmlichen API-Clients. Wenn Sie noch nicht mit WebSocket gearbeitet haben – planen Sie Zeit für die Einarbeitung in das ereignisgesteuerte Modell ein.

Vergleichstabelle:

Speech-to-Speech-Architektur – Wie das Modell Audio ohne Zwischenschritte verarbeitet

Das Verständnis, wie das Modell Audio intern verarbeitet, ist wichtig für die korrekte Systemgestaltung und das Verständnis der Latenz.

Alter Ansatz: Kaskadierender Pipeline

Vor dem Aufkommen von End-to-End-Sprachmodellen sah die Standardarchitektur so aus:

Mikrofon → [ASR] → Text → [LLM] → Text → [TTS] → Audio
           ~300ms          ~2-6s          ~300ms

Jede Pfeilspitze ist eine separate HTTP-Anfrage oder ein separater Dienst. Jeder Schritt fügt Latenz hinzu. Das Reasoning innerhalb des LLM erhöhte den zweiten Schritt auf 5–7 Sekunden. Gesamtlatenz: 1,5–8 Sekunden je nach Komplexität.

GPT-Realtime-2: End-to-End-Audio

GPT-Realtime-2 ersetzt die gesamte Kaskade durch ein einziges Modell:

Mikrofon → [GPT-Realtime-2] → Audio
                ~500-1200ms (erste Runde)
                ~300-600ms  (folgende Runden)

Audio kommt am Eingang an, das Reasoning findet innerhalb des Modells im Audiobereich statt, Audio kommt am Ausgang heraus. Es gibt keine Konvertierung in Text zwischen den Schritten – dies eliminiert Latenz bei Übergängen und ermöglicht es dem Modell, Tonfall, Pausen und Unterbrechungen besser zu verstehen.

Audioformat

Die Realtime API akzeptiert und gibt Audio im Format PCM16 mit einer Abtastrate von 24.000 Hz (oder Opus) zurück. Dies ist wichtig zu wissen, wenn Sie eine Verbindung mit einem Mikrofon oder einem Telefonsystem herstellen – das Format muss vor der Übertragung konvertiert werden.

Ereignisgesteuertes Interaktionsmodell

Die Sitzung wird über Client-Ereignisse und Server-Ereignisse gesteuert. Der Client sendet Ereignisse – der Server reagiert mit Ereignissen. Haupttypen:

Client-Ereignisse (Sie senden):

• session.update – Aktualisierung der Sitzungskonfiguration (Anweisungen, Stimme, Tools)
• input_audio_buffer.append – Senden eines Audio-Chunks
• input_audio_buffer.commit – Signal, dass die Runde abgeschlossen ist
• response.create – Anfrage zur Generierung einer Antwort
• conversation.item.create – Hinzufügen einer Textnachricht

Server-Ereignisse (Sie erhalten):

• session.created – Sitzung ist bereit
• session.updated – Bestätigung der Aktualisierung
• response.audio.delta – Audio-Antwort-Chunk
• response.text.delta – Texttranskriptions-Chunk
• response.function_call_arguments.delta – Argumente für Tool-Aufrufe
• response.done – Antwort abgeschlossen
• error – Sitzungsfehler

Die maximale Dauer einer Realtime-Sitzung beträgt 60 Minuten. Danach wird die Verbindung geschlossen und Sie müssen eine neue Sitzung öffnen. Planen Sie eine Wiederverbindungslogik, wenn Ihr Szenario längere Interaktionen vorsieht.

Drei Verbindungsmethoden: WebSocket, WebRTC, SIP – Welche für Ihr Szenario wählen

Die Realtime API unterstützt drei Verbindungsmethoden. Die Wahl hängt nicht von der Präferenz ab, sondern davon, wo sich das Audio in Ihrem System befindet.

WebSocket – für serverseitige Anwendungen

WebSocket eignet sich für Server-zu-Server-Integrationen: Node.js-Backend, Python-Dienst, jede serverseitige Anwendung, die bereits Audio hat oder es auf dem Server verarbeitet.

Vorteile: Volle Kontrolle über die Sitzung, geeignet für komplexe Agenten-Workflows, Sie können einen regulären API-Schlüssel verwenden (kein kurzlebiger Token erforderlich).

Einschränkungen: Sie sind selbst für die Erfassung und Übertragung von Base64-kodierten Audio-Chunks verantwortlich.

WebRTC – für Browseranwendungen

WebRTC ist die empfohlene Methode für Browser- und mobile Clients, bei denen Audio direkt vom Mikrofon des Benutzers erfasst wird. WebRTC ist für minimale Latenz bei Echtzeit-Audio optimiert.

Für die Browserverbindung benötigen Sie einen kurzlebigen Token (temporärer Schlüssel) – Ihr Haupt-API-Schlüssel kann nicht auf dem Client verwendet werden. Der kurzlebige Token wird auf Ihrem Backend generiert und an den Client übergeben.

SIP – für Telefonie

SIP ist für die Integration mit Telefonsystemen. Wenn Sie einen Agenten für echte Telefonanrufe erstellen, ist dies das offizielle Protokoll. Im Jahr 2026 befindet sich der native SIP-Endpunkt von OpenAI noch in der Beta-Phase; für die Produktion verwenden die meisten Teams SIP über Twilio oder Telnyx als Brücke zu WebSocket.

Tabelle zur Auswahl der Methode:

Browser / mobile App → WebRTC (+ kurzlebiger Token von Ihrem Backend)
Node.js / Python Backend → WebSocket (direkter API-Schlüssel)
Echte Telefonanrufe → SIP (oder SIP über Twilio/Telnyx → WebSocket)
Deno / Cloudflare Workers → WebSocket über die Standard-WebSocket-API des Browsers

Verbindung über WebSocket — Schritt-für-Schritt-Anleitung mit JS- und Python-Code

Lassen Sie uns die Verbindung über WebSocket untersuchen – die gängigste Methode für serverseitige Anwendungen. Alle Beispiele stammen aus der offiziellen OpenAI-Dokumentation.

Schritt 1. Abhängigkeiten installieren

Node.js:

npm install ws

Python:

pip install websocket-client

Schritt 2. Verbindung zur Realtime API herstellen

JavaScript (Node.js):

import WebSocket from "ws";

const url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2";

const ws = new WebSocket(url, {
  headers: {
    Authorization: "Bearer " + process.env.OPENAI_API_KEY,
    // Wenn Ihre Anwendung Benutzer-IDs hat –
    // übergeben Sie eine gehashte Benutzer-ID zur Sicherheitsüberwachung
    "OpenAI-Safety-Identifier": "hashed-user-id",
  },
});

ws.on("open", function open() {
  console.log("Verbindung hergestellt");
});

ws.on("message", function incoming(message) {
  const event = JSON.parse(message.toString());
  console.log("Ereignis vom Server:", event.type);
});

ws.on("error", function error(err) {
  console.error("WebSocket-Fehler:", err);
});

ws.on("close", function close() {
  console.log("Verbindung geschlossen");
});

Python:

import os
import json
import websocket

OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY")
url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2"

headers = [
    "Authorization: Bearer " + OPENAI_API_KEY,
    "OpenAI-Safety-Identifier: hashed-user-id",
]

def on_open(ws):
    print("Verbindung hergestellt")

def on_message(ws, message):
    data = json.loads(message)
    print("Ereignis:", data["type"])

def on_error(ws, error):
    print("Fehler:", error)

def on_close(ws, close_status_code, close_msg):
    print("Verbindung geschlossen")

ws = websocket.WebSocketApp(
    url,
    header=headers,
    on_open=on_open,
    on_message=on_message,
    on_error=on_error,
    on_close=on_close,
)

ws.run_forever()

Schritt 3. Sitzung über session.update konfigurieren

Sofort nach Erhalt des session.created-Ereignisses – senden Sie session.update mit der Konfiguration:

// JavaScript
ws.on("open", function open() {
  // Sitzungskonfiguration senden
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      type: "realtime",
      model: "gpt-realtime-2",
      // Audioformat: PCM16 24kHz
      output_modalities: ["audio"],
      audio: {
        input: {
          format: {
            type: "audio/pcm",
            rate: 24000,
          },
          // Semantic VAD – das Modell erkennt das Ende der Phrase selbst
          turn_detection: {
            type: "semantic_vad"
          }
        },
        output: {
          format: {
            type: "audio/pcm",
          },
          // Stimme: alloy, echo, shimmer, cedar, marin
          voice: "marin",
        }
      },
      instructions: "Sie sind ein hilfreicher Assistent. Antworten Sie kurz und bündig.",
    }
  }));
});

Wichtig zur Stimme: Die Stimme kann nur geändert werden, wenn das Modell in dieser Sitzung noch keine Audioantwort gesendet hat. Nach der ersten Audioantwort – wird voice für die gesamte Sitzung unveränderlich. Planen Sie die Stimmenauswahl im Voraus.

Erste Arbeitssitzung: Verbindung öffnen, Audio senden, Antwort erhalten

Nun sammeln wir den vollständigen Zyklus: Verbindung → Konfiguration → Audioübertragung → Antwort erhalten.

Ereignisfluss in der WebSocket-Sitzung

Hier ist die Ereignissequenz für einen typischen Sprach-Turn:

Client                          Server
  |                                |
  |--- WebSocket connect --------->|
  |<-- session.created ------------|
  |                                |
  |--- session.update ------------>|
  |<-- session.updated ------------|
  |                                |
  |--- input_audio_buffer.append ->| (wiederholt für jeden Chunk)
  |--- input_audio_buffer.commit ->| (oder semantic_vad macht dies automatisch)
  |--- response.create ----------->|
  |                                |
  |<-- response.audio.delta -------| (wiederholt – jeder Audio-Chunk)
  |<-- response.text.delta --------| (Transkription der Antwort)
  |<-- response.done --------------|

Audio-Chunks übertragen

Audio wird als Base64-kodierte Chunks über input_audio_buffer.append übertragen. Bei Verwendung von semantic_vad – das Modell erkennt selbst, wann der Benutzer zu sprechen aufgehört hat und startet die Antwort. Bei manueller Steuerung – senden Sie selbst input_audio_buffer.commit:

// Audio-Chunk senden (Base64-kodiertes PCM16)
function sendAudioChunk(audioBuffer) {
  const base64Audio = Buffer.from(audioBuffer).toString("base64");

  ws.send(JSON.stringify({
    type: "input_audio_buffer.append",
    audio: base64Audio,
  }));
}

// Manueller Turn-Abschluss (wenn Sie semantic_vad nicht verwenden)
function commitAudio() {
  ws.send(JSON.stringify({
    type: "input_audio_buffer.commit",
  }));

  // Antwort anfordern
  ws.send(JSON.stringify({
    type: "response.create",
  }));
}

Audioantwort verarbeiten

ws.on("message", function incoming(message) {
  const event = JSON.parse(message.toString());

  switch (event.type) {
    case "session.created":
      console.log("Sitzung bereit:", event.session.id);
      // Hier session.update senden
      break;

    case "response.audio.delta":
      // Audio-Chunk erhalten – abspielen
      const audioChunk = Buffer.from(event.delta, "base64");
      playAudio(audioChunk); // Ihre Wiedergabefunktion
      break;

    case "response.text.delta":
      // Texttranskription der Antwort
      process.stdout.write(event.delta);
      break;

    case "response.done":
      console.log("\nAntwort abgeschlossen");
      break;

    case "error":
      console.error("Sitzungsfehler:", event.error);
      break;
  }
});

Preambles, parallele Tool-Aufrufe und Recovery – Konfiguration und Codebeispiele

Preambles – wie Phrasen während des Denkens konfiguriert werden

Preambles – kurze Phrasen, die das Modell spricht, während die Logik im Hintergrund läuft. Aktiviert in session.update über instructions:

ws.send(JSON.stringify({
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2",
    instructions: `Sie sind ein hilfreicher Assistent.

Vor jeder Antwort, die eine Suche oder Berechnung erfordert –
sprechen Sie eine kurze Phrase: 'einen Moment', 'ich prüfe gerade',
'einen Augenblick' oder etwas Ähnliches. Dies gibt dem Benutzer zu verstehen, dass Sie arbeiten.

Wenn Sie calendar_tool aufrufen – sagen Sie 'ich prüfe Ihren Kalender'.
Wenn Sie order_tool aufrufen – sagen Sie 'ich suche Ihre Bestellung'.`,
  }
}));

Preambles sind kein separater API-Parameter, sondern eine Anweisung an das Modell im System-Prompt. Das GPT-Realtime-2-Modell folgt diesen Anweisungen und generiert den Preamble kontextabhängig – je nachdem, welches Tool es aufrufen möchte.

Tool-Aufrufe – Registrierung und Verarbeitung

Tools werden in session.update registriert und funktionieren genauso wie Function Calling in Chat Completions – aber asynchron über Ereignisse:

// Tools in der Sitzung registrieren
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2",
    tools: [
      {
        type: "function",
        name: "get_order_status",
        description: "Bestellstatus anhand der Bestellnummer abrufen",
        parameters: {
          type: "object",
          properties: {
            order_id: {
              type: "string",
              description: "Bestellnummer, z. B. ORD-12345"
            }
          },
          required: ["order_id"]
        }
      },
      {
        type: "function",
        name: "check_calendar",
        description: "Verfügbare Zeitfenster im Kalender prüfen",
        parameters: {
          type: "object",
          properties: {
            date: {
              type: "string",
              description: "Datum im Format YYYY-MM-DD"
            }
          },
          required: ["date"]
        }
      }
    ],
    tool_choice: "auto", // Das Modell entscheidet selbst, wann Tools aufgerufen werden
  }
}));

// Tool-Aufruf vom Server verarbeiten
ws.on("message", function incoming(message) {
  const event = JSON.parse(message.toString());

  if (event.type === "response.function_call_arguments.done") {
    const toolName = event.name;
    const args = JSON.parse(event.arguments);

    // Tool-Aufruf auf Ihrem Backend ausführen
    const result = await executeToolCall(toolName, args);

    // Ergebnis an die Sitzung zurückgeben
    ws.send(JSON.stringify({
      type: "conversation.item.create",
      item: {
        type: "function_call_output",
        call_id: event.call_id,
        output: JSON.stringify(result),
      }
    }));

    // Das Modell bitten, das Gespräch mit dem Ergebnis fortzusetzen
    ws.send(JSON.stringify({
      type: "response.create",
    }));
  }
});

Recovery – Fehlerbehandlung in der Sitzung

GPT-Realtime-2 verarbeitet Fehler nativ und spricht sie für den Benutzer aus. Auf Code-Ebene sollten Sie jedoch auch serverseitige error-Ereignisse behandeln:

ws.on("message", function incoming(message) {
  const event = JSON.parse(message.toString());

  if (event.type === "error") {
    console.error("Sitzungsfehler:", event.error.code, event.error.message);

    // Wenn der Fehler ein Rate-Limit ist – warten und neu verbinden
    if (event.error.code === "rate_limit_exceeded") {
      setTimeout(() => reconnect(), 5000);
    }

    // Wenn die Sitzung abgelaufen ist – eine neue öffnen
    if (event.error.code === "session_expired") {
      openNewSession();
    }
  }
});

Reasoning effort und Kontextfenster — wie man die Balance zwischen Qualität, Geschwindigkeit und Kosten einstellt

Reasoning effort: Fünf Stufen

GPT-Realtime-2 unterstützt fünf Stufen von reasoning effort, die über session.update eingestellt werden können:

ws.send(JSON.stringify({
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2",
    // Verfügbare Werte: "minimal", "low", "medium", "high", "xhigh"
    // Standard: "low"
    reasoning_effort: "medium",
  }
}));

Praktische Auswahl der Stufe:

Praktischer Tipp: Die Marketing-Benchmarks von OpenAI (+15,2 % Big Bench Audio, +13,8 % Audio MultiChallenge) wurden auf dem Niveau high / xhigh gemessen. Mit dem Standardwert low sind die Ergebnisse anders. Beginnen Sie mit low, messen Sie die Qualität in realen Szenarien und erhöhen Sie den effort nur dort, wo es ein objektives Problem mit der Antwortqualität gibt.

Kontextfenster 128K — was das praktisch bedeutet

128K Token Kontext bedeutet ungefähr:

• ~60–90 Minuten Sprachdialog (abhängig von der Sprechdichte)
• Eine vollständige Sitzung mit 10–15 Tool-Aufrufen und deren Ergebnissen
• Ein detaillierter System-Prompt + die gesamte Kundenhistorie + das aktuelle Gespräch

Wichtig: Audio-Token sind deutlich teurer als Text-Token. Bei 128K Kontext darf die Gesamtsumme der Token (einschließlich Audio-Chunks) dieses Limit nicht überschreiten. Für sehr lange Sitzungen ist eine Kompaktierungslogik erforderlich — das Zusammenfassen des Kontexts:

// Wenn die Sitzung das Limit erreicht —
// kann der Kontext über die Responses API zusammengefügt und eine neue Sitzung gestartet werden
// mit einer kompakten Zusammenfassung des vorherigen Gesprächs

// Überprüfung der Token-Nutzung im Ereignis response.done:
if (event.type === "response.done") {
  const usage = event.response.usage;
  console.log("Verwendete Token:", usage.total_tokens);

  if (usage.total_tokens > 100000) {
    // Limit wird erreicht — Kompaktierung planen
    scheduleContextCompaction();
  }
}

GPT-Realtime-Translate und GPT-Realtime-Whisper — Anbindung und Anwendungsfälle

GPT-Realtime-Translate — Live-Übersetzung

Die Anbindung erfolgt über dieselbe Realtime API, jedoch mit einem anderen Sitzungstyp. Die offizielle Dokumentation empfiehlt WebRTC für Browser-Medien und WebSocket für serverseitige Medien-Pipelines.

Der Hauptunterschied in der Konfiguration: Für Translate muss response.create nicht aufgerufen werden — die Übersetzung beginnt automatisch, sobald Audio vorhanden ist.

// Konfiguration der Sitzung für Live-Übersetzung
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    type: "translation", // Sitzungstyp — translation
    model: "gpt-realtime-translate",
    translation: {
      source_language: "uk", // Sprache der eingehenden Sprache
      target_language: "en", // Sprache der ausgehenden Sprache
    }
    // Rufen Sie response.create nicht auf — die Übersetzung erfolgt automatisch
  }
}));

Unterstützte Ausgangssprachen (13): Englisch, Spanisch, Französisch, Deutsch, Portugiesisch, Japanisch, Koreanisch, Chinesisch (vereinfacht), Arabisch, Hindi, Italienisch, Niederländisch, Polnisch.

Eingangssprachen — 70+, darunter Ukrainisch, Russisch, Türkisch, Hindi, Tamil, Telugu und andere.

GPT-Realtime-Whisper — Streaming-Transkription

Für die Transkription wird ein separater Sitzungstyp transcription verwendet:

// Konfiguration der Sitzung für Streaming-Transkription
ws.send(JSON.JSON.stringify({
  type: "session.update",
  session: {
    type: "transcription", // Sitzungstyp — transcription
    model: "gpt-realtime-whisper",
    transcription: {
      language: "uk", // Sprache der Transkription (optional, auto-detect wenn nicht angegeben)
      // Steuerung der Latenz:
      // niedriger Wert = schnellere partielle Transkripte
      // hoher Wert = bessere Qualität
      delay: "low", // "low" | "medium" | "high"
    }
  }
}));

// Erhalt von Transkripten
ws.on("message", function incoming(message) {
  const event = JSON.parse(message.toString());

  if (event.type === "conversation.item.input_audio_transcription.delta") {
    // Partielle Transkription — erscheint in Echtzeit
    process.stdout.write(event.delta);
  }

  if (event.type === "conversation.item.input_audio_transcription.completed") {
    // Finale Transkription eines Turns
    console.log("\nFinale:", event.transcript);
  }
});

Whisper ≠ GPT-Realtime-Whisper: Das klassische whisper-1 über die Speech-to-Text API ist eine Batch-Transkription einer fertigen Audiodatei nach der Aufnahme. GPT-Realtime-Whisper ist Streaming, Wort für Wort, während die Person noch spricht. Unterschiedliche Endpunkte, unterschiedliches Modell, unterschiedliches Szenario. Ersetzen Sie sie nicht gegenseitig.

Typische Fehler und wie man sie vermeidet

❌ Versuch, sich über OpenRouter oder einen anderen Aggregator zu verbinden

OpenRouter und ähnliche Aggregatoren basieren auf HTTP-Infrastruktur. Die Realtime API benötigt WebSocket. Architektonische Inkompatibilität — nicht durch Einstellungen lösbar. Die einzige Lösung: ein direkter OpenAI-Schlüssel.

❌ Verwendung des API-Schlüssels auf dem Client (Browser) bei WebSocket

Übergeben Sie bei der Verbindung über WebSocket vom Browser aus nicht den Haupt-API-Schlüssel — er wäre im Code sichtbar. Verwenden Sie für Browser-Clients WebRTC mit einem ephemeral token, das auf Ihrem Backend generiert wird:

// Auf Ihrem Backend — Generierung eines ephemeral token
const response = await fetch("https://api.openai.com/v1/realtime/client_secrets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    session: {
      type: "realtime",
      model: "gpt-realtime-2",
      audio: { output: { voice: "marin" } },
    },
  }),
});
const data = await response.json();
const ephemeralKey = data.value; // Übergabe an den Client

❌ Kein Reconnect bei session_expired behandeln

Die maximale Sitzungsdauer beträgt 60 Minuten. Ohne Reconnect-Logik friert Ihr Agent nach einer Stunde ein. Implementieren Sie eine automatische Wiederverbindung mit Übergabe eines gekürzten Kontexts des vorherigen Gesprächs.

❌ xhigh effort für alle Anfragen einstellen

xhigh = maximale Qualität, aber auch maximale Latenz (~2-3s) und maximale Anzahl von Ausgabe-Token. Für einen FAQ-Agenten mit Tausenden von Anrufen pro Monat kann der Kostenunterschied zwischen low und xhigh um ein Vielfaches betragen. Beginnen Sie mit low, messen Sie, erhöhen Sie punktuell.

❌ Audioformat ignorieren

Die Realtime API erwartet PCM16 mit einer Frequenz von 24.000 Hz. Wenn Ihr Mikrofon oder Telefonsystem ein anderes Format liefert — konvertieren Sie es vor der Übertragung. Ein falsches Format führt entweder zu Stille oder zu verzerrter Sprache ohne expliziten API-Fehler.

❌ Stimme nach der ersten Audio-Antwort ändern

Die Stimme wird nach der ersten Audio-Antwort des Modells festgelegt. Der Versuch, voice über session.update danach zu ändern, wird ohne Fehler ignoriert. Wenn Sie die Stimme ändern müssen — öffnen Sie eine neue Sitzung.

FAQ

Benötige ich einen separaten API-Schlüssel für die Realtime API?
Nein. Wenn Sie bereits einen Schlüssel für GPT-4o oder GPT-5 haben — er funktioniert auch für die Realtime API. Derselbe Schlüssel, dasselbe Konto auf platform.openai.com.

Wie kann ich GPT-Realtime-2 ohne Code testen?
Über das OpenAI Playground — dort gibt es eine Benutzeroberfläche für Realtime-Modelle mit Mikrofon direkt im Browser. Der schnellste Weg, das Modell zu hören, bevor Sie Code schreiben.

Kann ich GPT-Realtime-2 über OpenRouter verwenden?
Nein. OpenRouter basiert auf HTTP-Infrastruktur, die Realtime API benötigt WebSocket. Architektonische Inkompatibilität.

Was ist die maximale Sitzungsdauer?
60 Minuten. Danach schließt der Server die Verbindung. Implementieren Sie eine Reconnect-Logik für längere Interaktionen.

Wird die ukrainische Sprache unterstützt?
Ja — sowohl für GPT-Realtime-2 (versteht und antwortet), als auch als Eingangssprache für GPT-Realtime-Translate (70+ Eingangssprachen beinhalten Ukrainisch), als auch für GPT-Realtime-Whisper (Transkription).

Was ist semantic_vad und wann sollte es verwendet werden?
Voice Activity Detection — ein Mechanismus, der das Ende der Sprecherphrase bestimmt. semantic_vad nutzt das Verständnis des Kontexts, um Sätze nicht mitten im Satz abzubrechen. Empfohlen für die meisten Szenarien — besser als klassisches silence-based VAD, das Sätze bei natürlichen Pausen abschneidet.

Wie werden Token für Audio berechnet?
1 Sekunde Audio ≈ 40 Token. Bei einem Preis von 32 $/1M Eingabe-Token kostet 1 Minute Audio-Eingabe etwa 0,077 $. Eine detaillierte Kostenberechnung — in der offiziellen Dokumentation.

Schlussfolgerungen

GPT-Realtime-2 ist eine andere Art der Integration im Vergleich zur Chat Completions API. Event-gesteuertes Modell, ständige WebSocket-Verbindung, Base64-kodierte Audio-Chunks — wenn Sie noch nicht mit diesem Stack gearbeitet haben, planen Sie Zeit für die Einarbeitung ein.

Aber architektonisch läuft alles auf einige Schlüsselpunkte hinaus:

• Wählen Sie die richtige Methode: WebSocket (Server), WebRTC (Browser), SIP (Telefonie)
• Verbindung öffnen → session.created erhalten → session.update senden
• Audio in Chunks über input_audio_buffer.append streamen
• Auf response.audio.delta reagieren und Audio abspielen
• Tool-Aufrufe verarbeiten und Ergebnisse über conversation.item.create zurückgeben

Beginnen Sie mit dem Playground für erste Tests, nehmen Sie dann das WebSocket-Beispiel aus diesem Artikel und passen Sie es an Ihren Stack an. Reasoning effort — beginnen Sie mit low.

Kontext zum Release selbst, reale Anwendungsfälle und Vergleiche von Modellen — im Nachrichtenartikel:

→ OpenAI hat GPT-Realtime-2 veröffentlicht: das erste Sprachmodell mit GPT-5-Denkniveau

Wenn Sie sich für das breitere OpenAI-Ökosystem für Entwickler interessieren:

→ Codex von OpenAI: Der vollständige Leitfaden 2026

Quellen: OpenAI Realtime API Overview, WebSocket Guide, WebRTC Guide, SIP Guide, Managing Conversations, Managing Costs