Dialoge in Echtzeit streamen

Der Text to Dialogue-WebSocket (/v1/text-to-dialogue/stream-input) hält eine einzelne Verbindung offen, während Sie Dialogzeilen senden und base64-kodierte Audio-Chunks empfangen. Er ist ausschließlich für Eleven v3-Dialogmodelle vorgesehen (model_id muss mit eleven_v3 beginnen).

Voraussetzungen

• Ein ElevenLabs-Konto mit API-Key (Authentifizierung).
• Der API-Key benötigt Berechtigungen für Text to Speech.
• Python oder Node.js muss auf Ihrem Rechner installiert sein.

Einrichtung

pip install python-dotenv websockets

Erstellen Sie eine .env-Datei:

ELEVENLABS_API_KEY=your_elevenlabs_api_key_here

Wählen Sie eine Stimm-ID aus der Stimmbibliothek. Die folgenden Beispiele verwenden eleven_v3_conversational, das eine registrierte Stimme pro Verbindung erlaubt.

WebSocket öffnen

Verbinden Sie sich mit wss://api.elevenlabs.io/v1/text-to-dialogue/stream-input und verwenden Sie Abfrageparameter wie model_id und output_format. Sie können den API-Key im Header xi-api-key oder in der ersten JSON-Nachricht senden (hier im Body dargestellt, um ein einheitliches Muster für alle Sprachen zu verwenden).

import asyncio
import base64
import json
import os
from dotenv import load_dotenv
import websockets
load_dotenv()
ELEVENLABS_API_KEY = os.getenv("ELEVENLABS_API_KEY")
VOICE_ID = "21m00Tcm4TlvDq8ikWAM"
MODEL_ID = "eleven_v3_conversational"
URI = (
    "wss://api.elevenlabs.io/v1/text-to-dialogue/stream-input"
    f"?model_id={MODEL_ID}&output_format=mp3_44100_128"
)

Stimmen registrieren und Text streamen

Senden Sie eine erste Nachricht, die voices (erforderlich) und xi_api_key enthält, falls Sie den Header xi-api-key nicht gesetzt haben. Senden Sie anschließend einen oder mehrere Frames mit inputs: Jedes Element enthält text, voice_id und optional new_turn.

Der Server puffert Text, bis genügend Kontext vorhanden ist (etwa 40 Zeichen und 8 Wörter), und gibt dann audio-Chunks aus. Die Antwortfelder verwenden snake_case (zum Beispiel is_final).

async def stream_dialogue():
    async with websockets.connect(URI) as websocket:
        await websocket.send(
            json.dumps(
                {
                    "voices": [VOICE_ID],
                    "xi_api_key": ELEVENLABS_API_KEY,
                }
            )
        )
        line = (
            "This is a longer line of dialogue used to exceed the minimum buffer so the model "
            "starts generating streamed audio for the registered voice. "
        )
        await websocket.send(
            json.dumps(
                {
                    "inputs": [
                        {"text": line, "voice_id": VOICE_ID, "new_turn": False},
                    ],
                }
            )
        )
        await websocket.send(json.dumps({"close_socket": True}))
        os.makedirs("output", exist_ok=True)
        out_path = "output/dialogue-ws.mp3"
        with open(out_path, "wb") as audio_file:
            while True:
                raw = await websocket.recv()
                msg = json.loads(raw)
                if msg.get("error"):
                    raise RuntimeError(msg)
                if msg.get("audio"):
                    audio_file.write(base64.b64decode(msg["audio"]))
                if msg.get("is_final"):
                    break
        print(f"Wrote {out_path}")
asyncio.run(stream_dialogue())

close_socket sendet gepufferten Text, verbleibendes Audio und anschließend einen finalen Frame mit is_final: true, bevor die Verbindung geschlossen wird. Um die Verbindung zwischen Zeilen offen zu halten, lassen Sie close_socket bis zum Ende der Sitzung weg. Verwenden Sie flush, um Audio für kürzere Puffer zu erzwingen, ohne die Verbindung zu schließen.

Skript ausführen

python text-to-dialogue-websocket.py

Sie sollten eine MP3-Datei unter output/ erhalten (mit dem Dateinamen aus dem obigen Beispiel).

Hinweise zum Verhalten

Pufferung

Anders als der TTS-WebSocket chunk_length_schedule verwendet Dialog-Streaming vor dem ersten partiellen Audio einen festen Server-Schwellenwert (Zeichen- und Wortanzahl). Wenn Sie kurze Zeilen senden und Verzögerungen hören, bündeln Sie etwas mehr Text pro inputs-Frame oder senden Sie flush: true, um die Generierung zu erzwingen, ohne den Socket zu schließen.

Gesprächswechsel und Stimmen

Setzen Sie new_turn: true, wenn ein Sprecher seinen Gesprächsbeitrag beendet, damit die Prosodie sauber zurückgesetzt wird. Das Ändern von voice_id zwischen inputs-Einträgen startet ebenfalls einen neuen Gesprächswechsel. Mit eleven_v3_conversational registrieren Sie genau eine Stimme in voices; eleven_v3 unterstützt bis zu 10 registrierte Stimmen.

Inaktivität

Wenn der Server 20 Sekunden lang keine Client-Nachricht empfängt, wird die Verbindung beendet. Senden Sie {"keep_alive": true}, um den Timer zurückzusetzen, ohne Audio zu synthetisieren.

Parallelität

Jede offene Verbindung hält eine Dialogsitzung, solange sie geöffnet bleibt. Diese wird aus einem dedizierten Pool bereitgestellt, der von der standardmäßigen Parallelitätsgrenze Ihres Tarifs getrennt ist. Audio, das über die Verbindung generiert wird, zählt nicht zur Standardparallelität. Siehe Text to Dialogue-Parallelität.

Alignment

Fügen Sie der Abfragezeichenfolge sync_alignment=true hinzu, um bei Verfügbarkeit alignment-Objekte (Timing-Arrays in snake_case) für Chunks zu erhalten. Siehe API-Referenz.

Nächste Schritte