WebSocket-Architektur der Realtime API

Aktualisiert am 2. November 2026 — Audio-Modelle. Mehrere Modelle in diesem Kurs wurden eingestellt: tts-1, tts-1-hd und gpt-4o-mini-tts werden am 6. Januar 2027 nicht mehr funktionieren (Ersatz: gpt-realtime-2.1-mini, wobei die OpenAI-TTS-Richtlinien angeben, dass dies nicht über /v1/audio/speech unterstützt wird; die Migration der Spracherstellung erfolgt zur Realtime API); gpt-realtime, gpt-4o-realtime und die Legacy-Audio-Modelle am 20. Januar 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe und /v1/audio/translations am 26. Februar 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Für Voll-Duplex-Stimmen ist GPT-Live 1 seit dem 10. September 2026 in der API verfügbar. Ergänzung vom 3. November 2026: Abschnitt zu den drei Spracharchitekturen von OpenAI (GPT-Live, Realtime API, Verarbeitungskette) und der Auswahl des Transports (WebRTC, WebSocket, SIP), basierend auf den Leitfäden Voice agents, Audio and voice und Getting started with the Realtime API; maximale Sitzungsdauer: 60 Minuten (Realtime conversations).

WebSocket-Architektur der Realtime API

Die Realtime API von OpenAI stellt einen grundlegenden Paradigmenwechsel in der Interaktion mit Sprachmodellen dar. Im Gegensatz zu traditionellen REST-APIs, die auf einem Anfrage-Antwort-Zyklus basieren, nutzt die Realtime API das WebSocket-Protokoll, um eine persistente, bidirektionale Verbindung zwischen Ihrer Anwendung und dem Modell herzustellen.

Diese Architektur ermöglicht den Echtzeit-Austausch von Audio: Sie senden Audio, das Modell verarbeitet es und antwortet mit geringem Latenzwert vokalisierend, ohne Zwischenschritte wie Transkription oder Text-zu-Sprache. Dies ist einer der Kernbausteine für konversationelle Sprachagenten und das Herzstück dieses Kurses.

Drei Spracharchitekturen im Jahr 2026

Bevor Sie eine WebSocket-Verbindung öffnen, setzen Sie die Realtime API in den Kontext der anderen Lösungen von OpenAI. Der Leitfaden Voice agents unterscheidet drei Ansätze:

Für neue Sprach-Konversationsanwendungen empfiehlt die Seite Audio and voice von OpenAI nun, mit GPT-Live zu beginnen. Die Realtime API bleibt der richtige Ausgangspunkt, wenn der Agent innerhalb einer einzigen Sitzung bleiben muss, die Unterbrechungen durch den Nutzer, schnelle erste Audioantworten, natürliches Wechseln der Sprechenden und direkte Werkzeugaufrufe unterstützt. Die Verarbeitungskette funktioniert am besten, wenn jeder Schritt sichtbar bleiben muss: Transkripte speichern, Regeln erzwingen, bevor der Agent antwortet, oder Stimme nur nach Validierung der Antwort emittieren.

Dieser Kurs konzentriert sich auf die Realtime API und die Verarbeitungskette, deren Komponenten (Transkription, Spracherstellung) in nachfolgenden Abschnitten behandelt werden.

WebRTC, WebSocket oder SIP

Ihre Transportwahl hängt davon ab, woher das Audio stammt. Laut Dokumentation: verwenden Sie WebRTC für Browser-Audio, mit einem ephemeren Client-Secret, das von Ihrem Server generiert wird; WebSocket für serverseitige Audio-Pipelines; SIP für Telefonanrufe. Eine serverseitige Steuerungsverbindung ermöglicht es einem vertrauenswürdigen Backend, eine Mediensitzung zu beobachten und zu steuern. Diese Lektion erläutert WebSocket, den einfachsten Weg, um ausgetauschte Ereignisse zu verstehen; im Browser bevorzugen Sie WebRTC. Eine Realtime-Sitzung dauert maximal 60 Minuten.

WebSocket vs. REST: Warum diese Wahl?

In einer traditionellen REST-Architektur erfordert jede Interaktion eine vollständige HTTP-Anfrage: Öffnen einer TCP-Verbindung, TLS-Verhandlung, Senden von Kopfzeilen, Warten auf die Antwort und Schließen der Verbindung. Für Echtzeit-Audio ist dieser Overhead unzumutbar.

Das WebSocket-Protokoll hält einen Kanal kontinuierlich offen. Sobald etabliert, können Client und Server Nachrichten zu jedem Zeitpunkt senden, ohne auf den anderen zu warten, bis dieser fertig ist.

Herstellen einer WebSocket-Verbindung

So stellen Sie eine Verbindung zur Realtime API in Python her:

import asyncio
import websockets
import json

OPENAI_API_KEY = "sk-..."
URL = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"

async def connect_realtime():
    headers = {
        "Authorization": f"Bearer {OPENAI_API_KEY}"
    }

    async with websockets.connect(URL, additional_headers=headers) as ws:
        print("Verbunden mit Realtime API")

        # Empfangen des Begrüßungsevents
        response = await ws.recv()
        event = json.loads(response)
        print(f"Typ: {event['type']}")
        # → "session.created"

        # Verbindung offen halten
        await asyncio.Future()

asyncio.run(connect_realtime())

Die Verbindungs-URL enthält das Modell als Abfrageparameter. Da die API den allgemeinen Verfügbarkeit erreicht hat, ist nur der Authentifizierungskopfzeile erforderlich – der Kopfzeile OpenAI-Beta: realtime=v1 aus der Betaphase ist nicht mehr vorhanden.

Schnittstelle notiert am 5. August 2026 — Die Realtime API entwickelt sich weiter (Modelle, Event-Namen, Sitzungsformat): Im Zweifel prüfen Sie die offizielle Dokumentation.

Architektur einer Realtime-Anwendung

Eine Anwendung, die die Realtime API verwendet, folgt einer schichtenbasierten Architektur:

Die Rolle des Proxy-Servers

Während der Entwicklung können Sie Ihre Anwendung direkt mit der Realtime API verbinden. In der Produktion ist ein Proxy-Server unerlässlich, um:

• Ihren API-Schlüssel zu schützen – niemals auf der Client-Seite offenzulegen
• Ihre Nutzer zu authentifizieren – Token zu verifizieren, bevor die Sitzung geöffnet wird
• Kosten zu kontrollieren – Sitzungsdauer und Token-Nutzung begrenzen
• Interaktionen zu protokollieren – zur Fehlerbehebung und Compliance

# Vereinfachtes Beispiel eines WebSocket-Proxy mit FastAPI
from fastapi import FastAPI, WebSocket
import websockets

app = FastAPI()

@app.websocket("/ws/realtime")
async def proxy_realtime(client_ws: WebSocket):
    await client_ws.accept()

    headers = {"Authorization": f"Bearer {OPENAI_API_KEY}"}

    async with websockets.connect(URL, additional_headers=headers) as openai_ws:
        async def forward_to_openai():
            async for message in client_ws.iter_text():
                await openai_ws.send(message)

        async def forward_to_client():
            async for message in openai_ws:
                await client_ws.send_text(message)

        await asyncio.gather(forward_to_openai(), forward_to_client())

Kernaussagen

• Drei Spracharchitekturen bei OpenAI: GPT-Live (empfohlen für neue Konversationsanwendungen), Realtime API (Sprache, Nachdenken und Werkzeuge in einer Sitzung) und die Kette Transkription → Agent → Spracherstellung
• WebRTC für Browser-Audio, WebSocket für Server-Pipelines, SIP für Telekommunikation; Sitzungen dauern maximal 60 Minuten
• Die Realtime API nutzt WebSocket für bidirektionale Kommunikation mit geringer Latenz
• Die Verbindung ist persistent: eine einzige Öffnung für die gesamte konversationelle Sitzung
• Schichtenarchitektur trennt Audio, Transport, Geschäftslogik und Server-Proxy
• In der Produktion ist ein Proxy-Server für Sicherheit und Kostenkontrolle unerlässlich
• Das Protokoll ist ereignisgesteuert: jede Nachricht ist ein JSON-Objekt mit einem type-Feld