OpenAI Realtime API

Was ist die OpenAI Realtime API?

Die OpenAI Realtime API ermöglicht Low-Latency-Kommunikation zwischen Ihrer Anwendung und Modellen, die nativ Speech-to-Speech-Interaktionen unterstützen. Sie unterstützt multimodale Eingaben – Audio, Bilder und Text – sowie multimodale Ausgaben – Audio und Text –, was sie ideal für interaktive Voice-Erlebnisse macht.

Über Voice Agents hinaus kann die Realtime API für Echtzeit-Audio-Transkription genutzt werden, indem Audio über eine WebSocket-Verbindung gestreamt wird. Die Dokumentation hebt empfohlene Einstiegspunkte hervor (z. B. Agents SDK for TypeScript) für browserbasierte Voice-Agent-Workflows.

Wichtige Features

• Low-Latency Speech-to-Speech-Interaktionen: Entwickelt für Echtzeit-Gesprächs-Audio-Erlebnisse statt reinem Request/Response.
• Multimodale Eingaben (Audio, Bilder, Text): Ermöglicht einer einzigen Session unterschiedliche Eingabetypen je nach Anwendungsablauf.
• Multimodale Ausgaben (Audio und Text): Unterstützt die Rückgabe von Audio, Text oder beidem als Teil der Interaktion.
• Mehrere Verbindungsarten: Wählen Sie zwischen WebRTC (Browser/Client-seitig), WebSocket (Middle-Tier-Server-seitig mit konstant niedriger Latenz) und SIP (VoIP-Telefonie).
• Guides für Sessions und Gespräche: Enthält Anleitungen zu Prompting, Gesprächs-Lebenszyklus-Events und Server-Verwaltung des Session-Verhaltens.
• Echtzeit-Transkription über WebSocket: Bietet einen Weg, um Audio-Streams in Echtzeit zu transkribieren.

So nutzen Sie die OpenAI Realtime API

1. Wählen Sie eine Verbindungsart je nach Laufzeitumgebung Ihrer App: WebRTC für Browser/Client, WebSocket für Server/Middle-Tier oder SIP für VoIP-Telefonie.
2. Starten Sie mit einer Session. Für Browser-Voice-Agents empfehlen die Docs das Agents SDK for TypeScript, das WebRTC im Browser und WebSocket auf dem Server nutzt.
3. Erstellen und initialisieren Sie eine Session in Ihrem Code, dann verbinden Sie mit einem Client-API-Key (Beispiel verwendet RealtimeAgent und RealtimeSession mit session.connect).
4. Interagieren Sie mit dem Modell über Events. Nach der Verbindung nutzen Sie die Guides für Prompting/Steering, Gesprächs-Lebenszyklus-Management und (bei Bedarf) Server-Kontrolle via Webhooks.

Die Dokumentation erwähnt auch GA-Migrationsdetails (siehe FAQ), die die Authentifizierung von Realtime-Requests betreffen.

Anwendungsfälle

• Browserbasierter Voice Agent mit Speech-to-Speech: Nutzen Sie WebRTC (oft via Agents SDK for TypeScript), um Mikrofon und Audio-Ausgabe für interaktive Gespräche zu verbinden.
• Server-unterstützter Echtzeit-Assistent: Verwenden Sie eine WebSocket-Verbindung aus dem Middle Tier für konsistente Low-Latency-Netzwerke und zentrale Session-Verwaltung.
• VoIP/Telefonie-Integration: Verbinden Sie via SIP, wenn Ihre Zielumgebung eine Telefonie- statt Browser-Umgebung ist.
• Echtzeit-Audio-Transkription: Streamen Sie Audio zu einem Realtime-Transkriptionsflow über WebSocket, um Transkriptionsergebnisse während des Sendens zu erhalten.
• Multimodale Interaktion: Akzeptieren Sie Audio neben Bildern und Text in einer einzigen Echtzeit-Session, dann geben Sie Audio, Text oder beides zurück.

FAQ

Brauche ich den Beta-Header bei der GA Realtime API?

Für GA-Requests besagt die Dokumentation, der OpenAI-Beta: realtime=v1-Header solle entfernt werden. Zur Beibehaltung des Beta-Verhaltens sollten Sie den Header weiterhin einbeziehen.

Wie generiere ich Credentials für Client-seitige (Browser) Realtime-Sessions?

Im GA-Interface beschreiben die Docs einen einzigen REST-Endpoint – POST /v1/realtime/client_secrets –, um Keys für die Initialisierung von WebRTC- oder WebSocket-Verbindungen von Clients zu generieren. Das Beispiel zeigt die Erstellung einer Session-Konfiguration und deren POST an diesen Endpoint.

Worin unterscheiden sich WebRTC und WebSocket hinsichtlich der Laufzeitumgebung?

Die Dokumentation positioniert WebRTC als ideal für Browser/Client-seitige Interaktionen, während WebSocket für Middle-Tier-Server-Apps mit konsistenten Low-Latency-Netzwerkverbindungen ideal ist.

Welche URL-Änderung gilt für die WebRTC-SDP-Abfrage?

Beim Initialisieren einer WebRTC-Session im Browser lautet die URL für die Abruf von Remote-Session-Infos via SDP nun /v1/realtime/calls.

Kann ich die Realtime API für Transkription ohne volles Voice-Agent-Verhalten nutzen?

Ja. Die Dokumentation hebt explizit Echtzeit-Audio-Transkription hervor, indem Audio-Streams in Echtzeit über eine WebSocket-Verbindung transkribiert werden.

Alternativen

• Agents SDK für TypeScript nutzen, ohne alles direkt auf Realtime-Primitiven aufzubauen: So konzentrierst du dich auf die Orchestrierung von Voice Agents, während Realtime im Hintergrund für Browser (WebRTC)- und Server (WebSocket)-Verbindungen genutzt wird.
• Request/Response-Transkriptions-Pipeline statt Streaming aufbauen: Wenn deine App kein Echtzeit-Audio-Handling benötigt, vermeidet ein Non-Realtime-Transkriptions-Workflow den ereignisgesteuerten Session-Ansatz für Realtime.
• Andere Realtime-Kommunikationsansätze für Voice: Bei telephony-spezifischen Flows ist SIP-basierte Integration eine Option innerhalb der Realtime-Verbindungsarten; ansonsten wähle zwischen WebRTC (Browser) und WebSocket (Server) je nach Deployment.
• Multimodales Chat mit Non-Realtime-Endpunkten: Wenn Latenzanforderungen weniger streng als „Low-Latency-Kommunikation“ sind, passt ein Non-Realtime-Multimodal-Chat-Ansatz, obwohl er nicht dem Streaming/Event-Session-Workflow der Realtime-Docs folgt.