Découvrir l'API Text-to-Speech

Du texte, de l’audio, rien d’autre

L’API Text-to-Speech de Grok fait une chose et la fait bien : elle transforme du texte en audio de haute qualité. Là où le Voice Agent gère un dialogue avec ses tours de parole et ses interruptions, le TTS est strictement unidirectionnel — vous envoyez du texte, vous récupérez du son. Cette simplicité en fait l’outil des usages où personne ne répond à la machine : narration d’articles, messages d’accueil téléphoniques, doublage de modules e-learning, notifications sonores.

HTTP ou WebSocket : deux façons d’appeler le service

Le mode HTTP est le plus direct. Une requête POST part avec votre texte, la réponse contient le fichier audio complet, au format MP3 par défaut :

curl -X POST "https://api.x.ai/v1/tts" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -o sortie.mp3 \
  -d '{
    "text": "Bonjour et bienvenue sur Corsen Academy.",
    "voice_id": "ara",
    "language": "fr"
  }'

Notez le -o sortie.mp3 : le corps de la réponse est directement du binaire audio, pas du JSON encapsulant un lien. Ce mode convient parfaitement à une génération en arrière-plan — un batch nocturne qui produit les fichiers audio de vos articles, par exemple — puisque personne n’attend devant l’écran.

Le mode WebSocket répond à un autre besoin : commencer à entendre le son avant que le texte entier soit synthétisé. Vous ouvrez une connexion en passant les paramètres dans l’URL :

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

Le texte part ensuite par morceaux via text.delta, vous signalez la fin avec text.done, et l’audio revient en chunks base64 sur audio.delta. Ce fonctionnement en flux lève la contrainte de longueur du mode HTTP et permet surtout de synthétiser au fil de l’eau, ce qui est indispensable quand le texte lui-même est encore en train d’être produit par un modèle.

Les paramètres de la requête HTTP

Deux points appellent l’attention. language est obligatoire, ce qui surprend souvent : le service ne devine pas la langue de votre texte à moins que vous ne le lui demandiez explicitement avec la valeur auto. Et voice_id reprend exactement les cinq voix du Voice Agent — eve, ara, rex, sal, leo — sans se soucier de la casse. Un même personnage sonore peut donc animer votre agent conversationnel et vos contenus enregistrés, ce qui vaut la peine d’être exploité pour la cohérence de marque.

Choisir le format de sortie

Le champ output_format prend la main sur le codec et la qualité :

{
  "text": "Texte a convertir.",
  "voice_id": "rex",
  "language": "fr",
  "output_format": {
    "codec": "wav",
    "sample_rate": 44100
  }
}

Le choix du codec découle de ce que devient le fichier ensuite. Le mp3 convient à l’usage général : bien compressé, lisible partout, c’est le défaut raisonnable pour un site web ou un podcast. Le wav est sans perte, donc plus lourd, mais c’est celui qu’il faut quand un monteur va retravailler la piste. Le pcm livre de l’audio brut, destiné aux pipelines de traitement qui n’ont que faire d’un conteneur. Enfin mulaw et alaw correspondent au G.711 de la téléphonie, à réserver aux systèmes télécom qui l’exigent.

Les sample rates s’échelonnent de 8000 à 48000 Hz, avec 24000 Hz par défaut, valeur qui satisfait la grande majorité des usages. Pour le MP3, le bit rate se règle entre 32000 et 192000 bps, à 128000 par défaut. Monter à 192000 sur une voix parlée n’apporte pratiquement rien à l’oreille et alourdit vos fichiers d’un tiers : gardez cette marge pour les contenus où la musique se mêle à la voix.

Interroger le catalogue de voix

L’API expose deux endpoints en lecture seule qui complètent la génération. GET /v1/tts/voices retourne la liste de toutes les voix disponibles avec leurs métadonnées, tandis que GET /v1/tts/voices/{voice_id} détaille une voix précise, son ton et ses cas d’usage. Plutôt que de coder en dur les cinq noms dans votre interface, alimentez votre sélecteur de voix à partir de ces endpoints : votre application restera juste le jour où le catalogue évoluera.

Points clés à retenir

• Le TTS convertit du texte en audio via HTTP (simple) ou WebSocket (streaming)
• Le coût est de $4.20 par million de caractères avec un maximum de 15 000 caractères par requête HTTP
• Cinq voix, cinq codecs et six sample rates offrent une grande flexibilité
• Le mode WebSocket est illimité en longueur de texte (deltas de 15 000 caractères max)
• Le code BCP-47 est obligatoire pour spécifier la langue (ou auto pour la détection automatique)