--- title: "ThunderPhone mit OpenAI-Realtime-Clients verwenden" description: "Richten Sie einen mit OpenAI Realtime kompatiblen Server-Client auf ThunderPhone aus und verwenden Sie dabei entweder einen gespeicherten Agenten oder eine Inline-Sitzungskonfiguration." --- ThunderPhone implementiert eine gezielte Teilmenge des OpenAI-Realtime-Ereignismodells. Ein bestehender serverseitiger Client kann seinen WebSocket-, Audio-, Sitzungs- und Antwortereignisfluss beibehalten und gleichzeitig einen ThunderPhone-Sprachagenten verwenden. ## Bevor Sie eine Verbindung herstellen Sie benötigen einen geheimen API-Schlüssel einer ThunderPhone-Organisation und eine Server-Laufzeitumgebung, die WebSockets öffnen kann. Stellen Sie keine Verbindung über Browsercode her und legen Sie den Schlüssel nicht in einem Browser offen. Um einen gespeicherten Agenten zu verwenden, stellen Sie ihn zuerst bereit und kopieren Sie seine numerische Agent-ID. Verbinden Sie sich mit: ```text wss://api.thunderphone.com/v1/realtime ``` Authentifizieren Sie das WebSocket-Upgrade über Ihren Server: ```http Authorization: Bearer sk_live_YOUR_API_KEY ``` Für Clients, die keine Handshake-Header setzen können, ist eine Authentifizierung über Query-Strings verfügbar. URLs können jedoch leichter in Protokolle gelangen. ## Wählen Sie, wer die Konfiguration verwaltet | Modus | Verbinden mit | Konfigurationsquelle | | --- | --- | --- | | Gespeicherter Agent | `?agent_id=12` | Bereitgestellter Prompt, Stimme, Produkt, Sprachen, Wissen und kompatible serverseitig ausgeführte Tools | | Inline | Keine `agent_id` | Das erste akzeptierte `session.update` von Ihrem Client | ### Gespeicherter Agent Verbinden Sie sich mit der bereitgestellten Agent-ID: ```text wss://api.thunderphone.com/v1/realtime?agent_id=12 ``` Der Agent startet, während der Socket eine Verbindung herstellt. Seine Begrüßung bleibt verfügbar, doch Realtime deaktiviert seine gesprochenen Stille-Check-ins und lässt `transfer_call` und `send_keypad_input` weg. Andere kompatible Tools werden auf ThunderPhone ausgeführt. Senden Sie für diesen Modus keine Inline-Anweisungen oder clientseitig ausgeführten Tools. Legen Sie die Audioübertragung vor dem Start des Agenten mit den Abfrageparametern `input_audio_format`, `output_audio_format`, `input_rate` und `output_rate` fest. Nach der Verbindung können Sie die gespeicherte Konfiguration oder Audioformate nicht mehr ändern. ### Inline-Sitzung Warten Sie ohne `agent_id` auf `session.created` und senden Sie dann `session.update`: ```json { "type": "session.update", "session": { "type": "realtime", "instructions": "Answer questions clearly and keep responses brief.", "audio": { "input": { "format": { "type": "audio/pcm", "rate": 24000 } }, "output": { "format": { "type": "audio/pcm", "rate": 24000 }, "voice": "olivia" } }, "config": { "product": "bolt" } } } ``` Die erste akzeptierte Aktualisierung richtet den Anruf ein. `session.updated` bedeutet, dass die Sitzung aktiv ist. Anweisungen, Stimme, Produkt, Tools und Audioformate können danach nicht mehr geändert werden. Inline-Sitzungen haben keine automatische Begrüßung oder gesprochenen Stille-Check-ins. Damit der Agent zuerst spricht, fügen Sie eine System- oder Benutzernachricht hinzu und senden Sie `response.create`. Eine vollständig inaktive Sitzung endet weiterhin am Grenzwert der Plattform für stille Anrufe, standardmäßig nach 600 Sekunden. ## Das offizielle OpenAI SDK verwenden Übergeben Sie eine WebSocket-Basis-URL, die auf `/v1` endet; das SDK hängt `/realtime` an. Der Wert `model` ist ein Kompatibilitätsname und wählt nicht das ThunderPhone- Produkt aus. Wählen Sie das Produkt in der Sitzungskonfiguration oder im gespeicherten Agenten. Diese Verbindungsprüfung erstellt eine Inline-Bolt-Sitzung, gibt Ereignisse bis zum ersten `session.updated` aus und schließt dann die Verbindung. Verwenden Sie den [minimalen Python- Client](/api-reference/realtime#minimal-python-client), um Audio zu streamen. ```python import asyncio import os from openai import AsyncOpenAI async def main(): client = AsyncOpenAI( api_key=os.environ["THUNDERPHONE_API_KEY"], websocket_base_url="wss://api.thunderphone.com/v1", ) async with client.realtime.connect( model="thunderphone-realtime" ) as connection: await connection.session.update(session={ "type": "realtime", "instructions": "Listen to the caller and help them complete the call.", "config": {"product": "bolt"}, }) async for event in connection: print(event.type) if event.type == "session.updated": break if __name__ == "__main__": asyncio.run(main()) ``` Behalten Sie Ihre bestehende Verarbeitung für das Anhängen von Eingabeaudio, Antwortaudio-Deltas, Unterbrechungen, Funktionsaufrufe, Fehler und das saubere Schließen des Sockets bei. Inline-benutzerdefinierte Funktionen werden in Ihrem Client ausgeführt; geben Sie ihre Ergebnisse über das Realtime- Protokoll zurück. Tools gespeicherter Agenten werden auf ThunderPhone ausgeführt. ## Sitzungslebenszyklus und Fehler Ein WebSocket repräsentiert einen Anruf. Eine ungültige Agenten-ID oder abgelehnte Inline- Konfiguration erzeugt ein `error`-Ereignis. Warten Sie auf `session.updated`, bevor Sie die Sitzung als aktiv behandeln. Deklarieren Sie die tatsächlichen Ein- und Ausgabeformate sowie Abtastraten: Eine nicht übereinstimmende PCM-Rate gibt Audio zu schnell oder zu langsam wieder, anstatt einen Validierungsfehler zu erzeugen. Nachdem die Sitzung gestartet ist, schließen Sie den Socket sauber, wenn Ihre Anwendung fertig ist. Inline-Sitzungen können clientseitig ausgeführte Funktionen verwenden. Sitzungen mit gespeicherten Agenten verwenden kompatible, von ThunderPhone ausgeführte Tools und bieten keine Weiterleitung oder Tastatureingabe. ## Die Integration testen Beginnen Sie mit dem [minimalen Python-WAV-Client](/api-reference/realtime#minimal-python-client) und einer Mono-PCM16-WAV-Datei mit der darin deklarierten Rate. Prüfen Sie Folgendes: 1. Der Server akzeptiert die Konfiguration und sendet `session.updated`. 2. Die Eingabe erzeugt Transkript- und Antwortaudio-Ereignisse mit der erwarteten Geschwindigkeit. 3. Unterbrechung und Abbruch der Antwort stoppen verbleibendes Ausgabeaudio. 4. Ergebnisse von Inline-Funktionen oder Tools gespeicherter Agenten werden an das Modell zurückgegeben. 5. Ungültige Eingaben erzeugen ein `error`-Ereignis, das Ihr Client verarbeitet. 6. Ihr Client schließt den Socket und der Anruf erscheint im [Anruf- verlauf](/de/guides/review-calls). Die [Realtime-WebSocket-Referenz](/api-reference/realtime) listet die akzeptierten Ereignisse, Audioformate, Sitzungsfelder und vollständigen Beispiele auf. ## Kosten Realtime-Anrufe verwenden den normalen Minutentarif des ausgewählten Produkts. Die Aktivierung von Live- Transkript-Deltas fügt für die gesamte Sitzung einen Aufpreis pro Minute hinzu; den Tarif finden Sie unter [Live- Transkripte](/api-reference/realtime#live-transcripts) und die Produkttarife unter [Preise](/de/guides/pricing). `POST /v1/realtime/sessions` ist ein separater verwalteter LiveKit-Pfad. Er erstellt einen Raum und ein bereichsbeschränktes Teilnehmer-Token; für eine direkte WebSocket-Verbindung ist er nicht erforderlich. Informationen zu Framework-Integrationen finden Sie unter [ThunderPhone mit Pipecat verwenden](/de/guides/use-with-pipecat) und [ThunderPhone mit LiveKit Agents verwenden](/de/guides/use-with-livekit).