Connexion WebSocket TTS

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 (TTL)

Chaque session WebSocket à une durée de vie de 600 secondes (10 minutes). Passé ce délai, le serveur ferme la connexion. 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

Votre équipe (compte API) est limitée à 50 sessions WebSocket simultanées. Au-delà, les nouvelles connexions sont refusées. Gérez un pool de connexions pour les applications à fort trafic.

Pas de timeout d’inactivite

Contrairement au mode HTTP unaire (timeout de 15 minutes), le WebSocket n’a pas de timeout d’inactivite. La session reste ouverte pendant ses 600 secondes de TTL même si vous n’envoyez rien.

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 à 15 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
• Chaque session dure 600 secondes maximum
• La limite est de 50 sessions concurrentes par équipe
• Le texte est illimité (envoyé par deltas de 15 000 caractères max)
• Utilisez le WebSocket pour le temps réel, le HTTP pour le batch