Sessions, events, and lifecycle

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 feststellen, dass diese nicht über /v1/audio/speech unterstützt wird: Die Migration der Spracherstellung erfolgt über die Realtime API); gpt-realtime, gpt-4o-realtime und veraltete 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 die Voll-Duplex-Stimme ist GPT-Live 1 seit dem 10. September 2026 in der API verfügbar.

Korrigiert am 3. November 2026. Die Eingabe-Transkription verwendete gpt-live-transcribe, das nur in einer Transkriptions-Sitzung funktioniert und weder server_vad noch semantic_vad unterstützt. In einer Gesprächssitzung wie dieser, in der VAD jeden Zug validiert, legt die Dokumentation gpt-transcribe fest, das validierte Züge transkribiert und vorherige Züge als Kontext verwendet. Quellen: Realtime Transkription · GPT-Transcribe · GPT-Live-Transcribe.

Jede WebSocket-Verbindung zur Realtime API erstellt eine Sitzung. Diese Sitzung ist die grundlegende Verwaltungseinheit: Sie kapselt die Modellkonfiguration, die Gesprächshistorie, verfügbare Werkzeuge und den aktuellen Zustand der Interaktion. Das Verständnis ihres Lebenszyklus ist unerlässlich für den Aufbau robuster Sprachagenten.

Der Lebenszyklus einer Sitzung

Sobald die WebSocket-Verbindung hergestellt ist, sendet der Server ein session.created-Ereignis. Die Sitzung durchläuft mehrere Phasen:

Verbindung → session.created

Der Server bestätigt die Sitzung mit einer eindeutigen ID und einer Standardkonfiguration.

Konfiguration → session.update

Sie senden ein session.update, um Anweisungen, Stimme, Werkzeuge und Modalitäten zu definieren.

Aktives Gespräch

Austausch von Audio- und Textereignissen zwischen Client und Server.

Schließung → WebSocket-Disconnection

Die Sitzung wird zerstört, wenn die Verbindung geschlossen wird. Es wird kein Zustand auf dem Server beibehalten.

Konfigurieren einer Sitzung

Nach session.created senden Sie ein session.update-Ereignis, um das Verhalten des Modells zu konfigurieren. Die Transkription dessen, was der Benutzer sagt (audio.input.transcription), ist optional: Ohne sie erhalten Sie die Stimme, aber keinen Text. languages gibt die erwarteten Sprachen an und verbessert die Erkennung:

import asyncio
import websockets
import json

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

    async with websockets.connect(URL, additional_headers=headers) as ws:
        # Warten auf session.created
        event = json.loads(await ws.recv())
        session_id = event["session"]["id"]
        print(f"Sitzung erstellt: {session_id}")

        # Sitzung konfigurieren
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "output_modalities": ["audio"],
                "instructions": "Sie sind ein französischsprachiger Sprachassistent. "
                                "Antworten Sie prägnant und natürlich.",
                "audio": {
                    "input": {
                        "format": {"type": "audio/pcm", "rate": 24000},
                        "transcription": {"model": "gpt-transcribe", "languages": ["fr"]},
                        "turn_detection": {
                            "type": "server_vad",
                            "threshold": 0.5,
                            "prefix_padding_ms": 300,
                            "silence_duration_ms": 500
                        }
                    },
                    "output": {
                        "format": {"type": "audio/pcm", "rate": 24000},
                        "voice": "marin"
                    }
                },
                "tools": []
            }
        }))

        # Warten auf Bestätigung (andere Ereignisse können zuerst eintreffen)
        while True:
            event = json.loads(await ws.recv())
            if event["type"] == "session.updated":
                print("Sitzung aktualisiert")
                break
            if event["type"] == "error":
                raise RuntimeError(event["error"]["message"])

Wichtige Sitzungsparameter

Parameter	Beschreibung	Empfohlener Wert
output_modalities	Ausgabemodalitäten	["audio"] (oder ["text"])
audio.output.voice	Synthesestimme	marin, cedar, alloy, echo, etc.
audio.input.turn_detection	Sprachendetektion am Ende	server_vad mit Schwellenwert 0,5
audio.input.format	Eingehendes Audioformat	{"type": "audio/pcm", "rate": 24000}

Das Ereignissystem

Die Realtime API ist vollständig ereignisgesteuert. Jede ausgetauschte Nachricht ist ein JSON-Objekt mit einem type-Feld, das ihre Natur bestimmt. Ereignisse fallen in zwei Kategorien:

Client-Ereignisse (Sie → Server)

# Die Hauptereignisse, die Sie senden
client_events = {
    "session.update":              "Konfiguration ändern",
    "input_audio_buffer.append":   "Ein Audio-Chunk senden",
    "input_audio_buffer.commit":   "Audio-Puffer festlegen",
    "input_audio_buffer.clear":    "Audio-Puffer leeren",
    "conversation.item.create":    "Nachricht manuell hinzufügen",
    "conversation.item.truncate":  "Antwort kürzen",
    "conversation.item.delete":    "Nachricht löschen",
    "response.create":             "Antwort auslösen",
    "response.cancel":             "Aktuelle Antwort abbrechen",
}

Server-Ereignisse (Server → Sie)

# Die Hauptereignisse, die Sie empfangen
server_events = {
    "session.created":             "Sitzung initialisiert",
    "session.updated":             "Konfiguration angewendet",
    "input_audio_buffer.speech_started":  "Sprache erkannt",
    "input_audio_buffer.speech_stopped":  "Stille erkannt",
    "conversation.item.created":   "Neue Nachricht in der Historie",
    "response.created":            "Generierung gestartet",
    "response.output_audio.delta":        "Audio-Chunk der Antwort",
    "response.output_audio_transcript.delta": "Transkriptions-Chunk",
    "response.done":               "Antwort abgeschlossen",
    "error":                       "Fehler",
}

Fehlerbehandlung

Fehler werden über ein Ereignis vom Typ error gesendet. Sie müssen diese immer abfangen:

async def handle_events(ws):
    async for raw_message in ws:
        event = json.loads(raw_message)
        event_type = event["type"]

        if event_type == "error":
            error = event["error"]
            print(f"Fehler [{error['type']}]: {error['message']}")

            if error["type"] == "invalid_request_error":
                # Konfigurationsfehler, beheben und erneut versuchen
                pass
            elif error["type"] == "server_error":
                # Problem auf der Seite von OpenAI, neu verbinden
                pass

        elif event_type == "session.updated":
            print("Konfiguration erfolgreich angewendet")

        elif event_type == "response.done":
            usage = event["response"].get("usage", {})
            print(f"Verwendete Tokens: {usage}")

Wichtige Kernaussagen

Eine Sitzung wird automatisch bei der WebSocket-Verbindung erstellt und bei der Trennung zerstört
session.update konfiguriert die Sitzung nach session.created; warten Sie auf session.updated, bevor Sie die neue Konfiguration verwenden
Zur Transkription der Eingabe in einer Gesprächssitzung verwenden Sie gpt-transcribe; gpt-live-transcribe ist für Transkriptionssitzungen reserviert
Das Protokoll ist rein ereignisgesteuert: Jede Nachricht hat ein type, das ihre Verarbeitung bestimmt
Client-Ereignisse steuern die Interaktion; Server-Ereignisse melden Ergebnisse
Fehlerbehandlung ist kritisch: Hören Sie immer auf error-Ereignisse