Connexion WebSocket TTS

Leçon corrigée le 3 novembre 2026 d’après la page Text to Speech de xAI : deltas de 60 000 caractères et non 15 000 ; la connexion n’a pas de délai d’expiration et la page ne dit pas que le serveur la ferme au bout de 600 secondes (elle parle d’un « permis de session » de 600 secondes) ; pas de voix par défaut indiquée pour le WebSocket. Source : Text to Speech.

Synthèse vocale en temps réel avec WebSocket

L’API TTS de Grok propose un mode WebSocket pour la synthèse vocale en streaming. Contrairement au mode HTTP unaire qui attend la fin du traitement pour retourner l’audio complet, le WebSocket envoie les morceaux audio au fur et à mesure de leur génération. C’est idéal pour les applications interactives où la latence perçue doit être minimale.

Endpoint WebSocket

La connexion se fait sur wss://api.x.ai/v1/tts. Les paramètres de configuration sont passés en query string lors de la connexion initiale.

Paramètres de connexion

URL de connexion complète

wss://api.x.ai/v1/tts?language=fr&voice=rex&codec=mp3&sample_rate=24000

Établir la connexion

En JavaScript (navigateur ou Node.js)

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=fr&voice=rex&codec=mp3",
  {
    headers: {
      "Authorization": `Bearer ${API_KEY}`
    }
  }
);

ws.onopen = () => {
  console.log("Connexion TTS etablie");
};

ws.onerror = (error) => {
  console.error("Erreur WebSocket:", error);
};

Note importante : dans un navigateur, l’API WebSocket native ne supporte pas les en-têtes personnalisés. Vous devrez passer par votre backend pour la connexion (voir la leçon sur la production).

En Python avec websockets

import asyncio
import websockets
import json

async def connect_tts():
    uri = "wss://api.x.ai/v1/tts?language=fr&voice=rex&codec=mp3"
    headers = {"Authorization": f"Bearer {api_key}"}

    async with websockets.connect(uri, additional_headers=headers) as ws:
        print("Connexion TTS etablie")
        # Envoyer du texte et recevoir de l'audio...

Gestion de la session

Durée de vie

La page Text to Speech de xAI indique deux choses à rapprocher : la connexion WebSocket n’a pas de délai d’expiration de requête (elle reste ouverte), et le « permis de session » a une durée de vie de 600 secondes, sans que la page détaille ce qui se passe à son terme. Par prudence, votre application doit :

1. Détecter la fermeture de connexion
2. Se reconnecter automatiquement si nécessaire
3. Reprendre l’envoi de texte là où il s’était arrêté

Sessions concurrentes

D’après la page Text to Speech, votre équipe est limitée à 50 sessions WebSocket simultanées (la page Rate limits, elle, compte les sessions TTS par palier, à partir de 100). Au-delà, les nouvelles connexions sont refusées. Gérez un pool de connexions pour les applications à fort trafic.

Plusieurs textes sur une même connexion

Contrairement au mode HTTP unaire, dont les requêtes expirent au bout de 15 minutes, la connexion reste ouverte après chaque audio.done : vous pouvez enchaîner les textes sans vous reconnecter, et annuler celui en cours avec text.clear (leçon 10).

Différences entre HTTP unaire et WebSocket

Quand utiliser le WebSocket

Le WebSocket s’impose dès que le temps réel entre en jeu. Si un utilisateur attend une réponse vocale immédiate — chatbot, assistant vocal — chaque seconde de silence avant le premier son se paie en expérience perçue, et le WebSocket permet de commencer la lecture dès les premiers fragments d’audio, avant même la fin de la génération. Il est aussi l’architecture naturelle quand le texte lui-même arrive progressivement : la sortie streamée d’un LLM se branche directement sur le TTS, delta après delta, sans attendre le texte complet. Et il lève la contrainte de longueur : pas de limite globale sur le texte total, seuls les deltas individuels sont plafonnés à 60 000 caractères — de quoi vocaliser un document entier en flux continu.

Le mode HTTP unaire garde sa place partout où le temps réel n’apporte rien : la génération de fichiers audio en batch, les traitements qui ont besoin du fichier complet avant d’agir (post-traitement, stockage, envoi), et plus simplement toutes les architectures qui préfèrent un aller-retour sans état à une connexion persistante à gérer.

Points clés à retenir

• Le WebSocket TTS est accessible sur wss://api.x.ai/v1/tts
• Les paramètres sont passés en query string à la connexion
• La connexion n’expire pas d’elle-même, mais la doc mentionne un permis de session de 600 secondes : prévoyez la reconnexion
• La limite est de 50 sessions concurrentes par équipe
• Le texte est illimité (envoyé par deltas de 60 000 caractères max)
• Utilisez le WebSocket pour le temps réel, le HTTP pour le batch