Passer à la navigation
Guides pratiquesWebSockets

WebSockets Text to Speech et Text to Dialogue

Ce guide explique comment choisir le WebSocket adapté au streaming vocal et présente les différences entre les deux protocoles.

ElevenLabs propose deux familles de produits WebSocket pour le streaming de parole synthétisée. Chaque famille comprend une variante à flux unique et une variante multi-contexte qui multiplexe plusieurs flux indépendants sur une même connexion. Elles répondent à des besoins différents, acceptent des formats de messages différents et ciblent différents modèles.

Quel WebSocket utiliser ?

Utilisez le WebSocket Text to Speech (TTS) lorsque vous diffusez du texte brut pour une voix par connexion (la voix est définie dans l’URL) et que vous souhaitez utiliser des modèles autres que v3, tels que Flash ou Multilingual v2, le SSML facultatif, les planifications de fragments ou la variante multi-contexte pour gérer les interruptions de type agent.

Utilisez le WebSocket Text to Dialogue (TTD) lorsque vous avez besoin du comportement de dialogue d’Eleven v3 : une restitution expressive, un **voice_id par fragment **, des limites de tours (new_turn) et la même mise en mémoire tampon orientée dialogue que celle utilisée côté serveur pour v3.

Utilisez le WebSocket TTD multi-contexte lorsque vous avez besoin de ce même comportement de dialogue d’Eleven v3 et de plusieurs flux simultanés ou entrelacés sur une seule connexion, par exemple pour un agent conversationnel qui doit interrompre et relancer le dialogue sans ouvrir un nouveau socket à chaque fois.

Pour le dialogue en traitement par lots ou en streaming HTTP (requête complète en un seul appel), utilisez plutôt Créer un dialogue ou Diffuser un dialogue qu’un WebSocket.

Comparaison

WebSocket Text to SpeechWebSocket Text to Dialogue
Guide de l’APIEntrée de flux TTSWebSocket TTD
URLwss://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream-inputwss://api.elevenlabs.io/v1/text-to-dialogue/stream-input
Sélection de la voixUn voice_id dans le chemin ; tout le texte diffusé utilise cette voixLe premier message enregistre une ou plusieurs voices par ID ; chaque entrée inputs[] indique un voice_id
ModèlesFlash, Multilingual v2 et les autres modèles TTS pris en charge. Pas de eleven_v3 ni de eleven_v4 sur cet endpoint.model_id doit commencer par eleven_v3 ou eleven_v4 (par exemple, eleven_v4 ou eleven_v4_turbo)
Premier message clientInitialisez avec un espace et, éventuellement, voice_settings / generation_config (voir le guide TTS en temps réel)Doit inclure voices (ainsi que les identifiants s’ils n’ont pas déjà été envoyés dans les en-têtes ou la requête)
Texte ultérieurEnvoyez une chaîne text (généralement suivie d’un espace) ; flush, try_trigger_generation, etc., sont facultatifsEnvoyez des inputs : objets { text, voice_id, new_turn? } ; flush, close_socket, keep_alive sont facultatifs
Mise en mémoire tampon / planificationPlanification de la longueur des fragments et contrôles WebSocket TTS associésLe serveur attend d’avoir suffisamment de texte (environ 40 caractères et 8 mots) avant d’émettre l’audio, sauf si vous utilisez flush
Plusieurs locuteurs sur un socketUtilisez le WebSocket multi-contexte pour plusieurs contextes TTS parallèles, et non pour une sémantique de dialogue multi-locuteurJusqu’à 10 voix enregistrées pour eleven_v4 ; eleven_v4_turbo n’autorise qu’une seule voix enregistrée. Pour des flux de dialogue parallèles, utilisez le WebSocket TTD multi-contexte
Inactivitéinactivity_timeout configurable (paramètre de requête WebSocket TTS)20 s fixes entre les messages client, sauf si vous envoyez keep_alive
Requêtes simultanéesSeul le temps de génération actif est comptabilisé dans la limite de requêtes simultanées de votre forfait ; un socket ouvert inactif n’est pas comptabiliséChaque connexion ouverte réserve une session de dialogue dans un pool distinct pendant toute sa durée de vie ; la génération sur cette connexion ne consomme pas les requêtes simultanées standard
Alignementsync_alignment facultatif (nommage des champs TTS dans le Guide de l’API)sync_alignment facultatif ; le JSON utilise des champs en snake_case dans les réponses (par exemple, is_final, char_start_times_ms)

Quand le WebSocket TTS est le meilleur choix

  • Vous intégrez déjà Flash ou Multilingual v2 pour leur faible latence ou leur couverture linguistique.
  • Vous souhaitez une voix de narrateur par connexion et un protocole simple avec un texte par trame.
  • Vous avez besoin d’une orchestration multi-contexte pour les interruptions et les énoncés parallèles (guide multi-contexte).

Consultez Générer de l’audio en temps réel pour découvrir en détail le WebSocket TTS.

Quand le WebSocket TTD est le meilleur choix

  • Vous ciblez le dialogue Eleven v4 (balises expressives, rythme conversationnel, répliques multi-locuteurs).
  • Vous diffusez un dialogue scénarisé ou généré par un LLM dans lequel la voix parlante peut changer à chaque ligne sans ouvrir de nouvelle connexion.
  • Vous souhaitez une entrée incrémentielle au format WebSocket, avec une génération de dialogue réservée à v4 côté serveur.

Pour un guide pratique, utilisez Text to Dialogue en temps réel. Retrouvez les détails du protocole dans le Guide de l’API.

WebSockets multi-contexte

Les deux produits proposent une variante multi-contexte qui multiplexe plusieurs flux indépendants sur une seule connexion WebSocket. Chaque contexte est identifié par un context_id choisi par le client, met son propre texte en mémoire tampon et émet des fragments audio étiquetés avec ce context_id. Les contextes TTS partagent le voice_id de l’URL de connexion, tandis que les contextes TTD enregistrent leurs propres voix et paramètres. Utilisez ce format lorsque vous avez besoin d’une génération simultanée ou entrelacée avec gestion des interruptions, par exemple pour un agent vocal qui doit annuler un énoncé en cours et en démarrer un nouveau sans fermer la connexion.

WebSocket TTS multi-contexteWebSocket TTD multi-contexte
Guide de l’APIEntrée de flux multiple TTSEntrée de flux multiple TTD
URLwss://api.elevenlabs.io/v1/text-to-speech/{voice_id}/multi-stream-inputwss://api.elevenlabs.io/v1/text-to-dialogue/multi-stream-input
ModèlesFlash, Multilingual v2 et les autres modèles TTS pris en charge. Pas de eleven_v3 ni de eleven_v4.model_id doit commencer par eleven_v3 (par exemple, eleven_v3 ou eleven_v3_conversational). eleven_v4 n’est pas pris en charge sur cet endpoint.
ContextesPlusieurs contextes TTS parallèles sur une seule connexionJusqu’à 5 contextes simultanés par connexion
Voix par contexteUn voice_id défini dans l’URL pour chaque contexteEnregistrées dans le premier message pour un context_id : 1 pour eleven_v3_conversational, jusqu’à 10 pour eleven_v3
Routage par messageChaque message inclut context_idChaque message inclut context_id (à l’exception d’un message contenant uniquement close_socket)
Messages de contrôleflush, close_context, close_socket, keep_alive par contexteflush, close_context, close_socket, keep_alive par contexte
Inactivitéinactivity_timeout configurable par contexte20 s fixes par contexte, sauf si vous envoyez keep_alive pour ce contexte
AuthentificationAu niveau de la connexion (en-tête, requête ou premier message)Au niveau de la connexion (en-tête, requête ou premier message), pas par contexte

Quand le WebSocket TTD multi-contexte est le meilleur choix

  • Vous avez besoin du comportement de dialogue d’Eleven v3 (restitution expressive, voice_id par fragment, limites de tours) et de flux simultanés ou entrelacés sur une seule connexion.
  • Vous concevez un agent conversationnel qui doit interrompre et relancer le dialogue sans ouvrir un nouveau socket à chaque fois.
  • Vous souhaitez répartir plusieurs sessions de dialogue v3 indépendantes, par exemple des scènes ou des locuteurs parallèles, sur une seule connexion authentifiée.

Pour le WebSocket TTD à flux unique, consultez Text to Dialogue en temps réel. Pour le WebSocket TTS multi-contexte, consultez le guide WebSocket multi-contexte. Retrouvez les détails du protocole de l’endpoint TTD multi-contexte dans le Guide de l’API.

Guides associés

Text to Dialogue en temps réel

Connectez-vous, enregistrez des voix, diffusez des inputs et enregistrez l’audio depuis le WebSocket TTD.

WebSocket TTS en temps réel

Connexion et messagerie pas à pas pour le WebSocket TTS standard.

WebSocket multi-contexte

Plusieurs contextes TTS sur une seule connexion pour les flux de travail d’agents.

WebSocket TTD multi-contexte (API)

Paramètres de requête, schémas de messages et exemples pour des flux de dialogue v3 parallèles.

Démarrage rapide de Text to Dialogue

Exemples de requêtes HTTP pour les dialogues à plusieurs voix.

Fonctionnalité Text to Dialogue

Présentation du produit orientée génération de dialogue.