WebSocket
Erstellen Sie Echtzeit-, interaktive Sprachgespräche mit KI-Agenten
Diese Dokumentation richtet sich an Entwickler, die direkt die ElevenLabs WebSocket API integrieren. Der Einfachheit halber empfehlen wir die offiziellen SDKs von ElevenLabs.
Die ElevenAgents WebSocket API ermöglicht Echtzeit-, interaktive Sprachgespräche mit KI-Agenten. Durch eine WebSocket-Verbindung können Sie Audioeingaben senden und Audioantworten in Echtzeit empfangen. So entstehen realistische Gesprächserlebnisse.
wss://api.elevenlabs.io/v1/convai/conversation?agent_id={agent_id}Authentifizierung
Agent-ID verwenden
Bei öffentlichen Agenten können Sie die agent_id direkt in der WebSocket-URL verwenden, ohne zusätzliche Authentifizierung:
Signierte URL verwenden
Für private Agenten oder Gespräche, die eine Autorisierung erfordern, rufen Sie von Ihrem Server eine signierte URL ab. Dieser kommuniziert über Ihren API-Schlüssel sicher mit der ElevenLabs API.
Beispiel mit cURL
Anfrage:
Antwort:
WebSocket-Ereignisse
Ereignisse vom Client zum Server
Der Client kann folgende Ereignisse an den Server senden:
Kontextuelle Aktualisierungen
Senden Sie nicht unterbrechende Kontextinformationen, um den Gesprächsstatus zu aktualisieren. So können Sie zusätzlichen Kontext bereitstellen, ohne den laufenden Gesprächsfluss zu stören.
Anwendungsfälle:
- Nutzerstatus oder Präferenzen aktualisieren
- Umgebungskontext bereitstellen
- Hintergrundinformationen hinzufügen
- Interaktionen mit der Benutzeroberfläche verfolgen
Wichtige Punkte:
- Unterbricht den aktuellen Gesprächsfluss nicht
- Aktualisierungen werden als Tool-Aufrufe in den Gesprächsverlauf aufgenommen
- Hilft, den Kontext zu wahren, ohne den natürlichen Dialog zu unterbrechen
Kontextuelle Aktualisierungen werden asynchron verarbeitet und erfordern keine direkte Antwort vom Server.
Implementierungsbeispiel für Next.js
Dieses Beispiel zeigt, wie Sie einen WebSocket-basierten Client für einen Gesprächsagenten in Next.js mit der ElevenLabs WebSocket API implementieren.
Dieses Beispiel verwendet zwar das Paket voice-stream zur Verarbeitung von Mikrofoneingaben, Sie können jedoch
auch eine eigene Lösung zum Erfassen und Kodieren von Audio implementieren. Der Schwerpunkt liegt hier auf der Demonstration
der WebSocket-Verbindung und Ereignisverarbeitung mit der ElevenLabs API.
Erforderliche Abhängigkeiten installieren
Installieren Sie zuerst die erforderlichen Pakete:
Das Paket voice-stream verarbeitet Mikrofonzugriff und Audio-Streaming und kodiert das Audio automatisch im von der ElevenLabs API benötigten Base64-Format.
Dieses Beispiel verwendet Tailwind CSS für das Styling. So fügen Sie Tailwind Ihrem Next.js-Projekt hinzu:
Folgen Sie anschließend der offiziellen Tailwind-CSS-Einrichtungsanleitung für Next.js.
Alternativ können Sie die className-Attribute durch eigene CSS-Stile ersetzen.
Nächste Schritte
- Audiowiedergabe: Implementieren Sie ein eigenes Audiowiedergabesystem mit der Web Audio API oder einer Bibliothek. Berücksichtigen Sie die Audiowarteschlange, um Überlappungen zu vermeiden, da WebSocket Audioereignisse in Blöcken sendet.
- Fehlerbehandlung: Fügen Sie Wiederholungslogik und Mechanismen zur Fehlerbehebung hinzu
- UI-Feedback: Fügen Sie visuelle Anzeigen für Sprachaktivität und Verbindungsstatus hinzu
Latenzmanagement
Für reibungslose Gespräche implementieren Sie diese Strategien:
- Adaptives Buffering: Passen Sie die Audiopufferung an die Netzwerkbedingungen an.
- Jitter-Puffer: Implementieren Sie einen Jitter-Puffer, um Schwankungen bei den Paketankunftszeiten auszugleichen.
- Ping-Pong-Überwachung: Verwenden Sie Ping- und Pong-Ereignisse, um die Round-Trip-Zeit zu messen und entsprechend anzupassen.
Sicherheits-Best-Practices
- Rotieren Sie API-Schlüssel regelmäßig und speichern Sie sie in Umgebungsvariablen.
- Implementieren Sie Ratenbegrenzungen, um Missbrauch zu verhindern.
- Erklären Sie klar den Zweck, wenn Sie Nutzer um Mikrofonzugriff bitten.
- Optimierte Blockbildung: Passen Sie die Dauer der Audioblöcke an, um Latenz und Effizienz auszubalancieren.