Endpoint POST /v1/tts

Leçon corrigée le 3 novembre 2026 d’après la page Text to Speech, la référence de l’API Voice et la page Pricing de xAI : 15 $ par million de caractères et non 4,20 $, 60 000 caractères par requête et non 15 000, 28 voix intégrées et non 5 ; les réglages speed, replace, with_timestamps, text_normalization et optimize_streaming_latency sont ajoutés. Sources : Text to Speech · Voice API · Pricing.

Convertir du texte en audio avec l’API Grok

L’API Text-to-Speech de xAI vous permet de transformer n’importe quel texte en audio naturel via un simple appel HTTP. Le point d’entrée principal est POST /v1/tts, qui accepte votre texte et retourne directement un fichier audio binaire.

Structure de la requête

L’appel se fait en POST sur https://api.x.ai/v1/tts avec un corps JSON. Voici un exemple minimal en curl :

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

Le serveur répond directement avec le fichier audio binaire dans le corps de la réponse. Il n’y a pas d’enveloppe JSON autour : vous recevez les octets bruts du fichier audio.

Authentification

Comme pour tous les endpoints de l’API xAI, vous devez inclure votre clé API dans l’en-tête Authorization au format Bearer :

Authorization: Bearer xai-votre-cle-api

Corps de la requête

Le corps JSON s’articule autour de quatre paramètres principaux :

• text (requis) : le texte à convertir, jusqu’à 60 000 caractères. Il supporte les tags expressifs que vous découvrirez dans les leçons suivantes
• voice_id (optionnel) : l’identifiant de la voix. Par défaut eve. Les valeurs sont insensibles à la casse
• language (requis) : le code langue au format BCP-47 (fr, en, de…) ou auto pour la détection automatique
• output_format (optionnel) : un objet pour configurer le codec, le sample rate et le bit rate

D’autres réglages, tous facultatifs, complètent la requête : speed (vitesse de lecture, de 0,7 à 1,5, 1,0 par défaut), replace (une table de remplacements pour corriger la prononciation d’un mot sans changer le texte envoyé), with_timestamps (des horodatages caractère par caractère), text_normalization (la conversion des nombres, abréviations et symboles en toutes lettres avant la synthèse) et optimize_streaming_latency ("1" pour réduire le délai avant le premier morceau d’audio, au prix d’une légère perte de qualité aux jointures).

La réponse HTTP

En cas de succès (code 200), le serveur retourne le fichier audio avec le content-type correspondant au format demandé :

• audio/mpeg pour MP3 (défaut)
• audio/wav pour WAV
• audio/pcm pour PCM brut
• audio/basic pour le G.711 μ-law (mulaw)
• audio/alaw pour le G.711 A-law (alaw)

Il n’y a pas de métadonnées dans la réponse : uniquement les octets audio. Seule exception, with_timestamps : la réponse devient alors un objet JSON qui porte l’audio en base64, sa durée et les horodatages de chaque caractère. Vous pouvez écrire directement la réponse dans un fichier ou la streamer vers un lecteur audio.

Exemple en Python

import requests

response = requests.post(
    "https://api.x.ai/v1/tts",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "text": "Voici un exemple de synthèse vocale.",
        "voice_id": "rex",
        "language": "fr"
    }
)

with open("sortie.mp3", "wb") as f:
    f.write(response.content)

Exemple en JavaScript (Node.js)

const response = await fetch("https://api.x.ai/v1/tts", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Voici un exemple de synthèse vocale.",
    voice_id: "rex",
    language: "fr"
  })
});

const buffer = await response.arrayBuffer();
fs.writeFileSync("sortie.mp3", Buffer.from(buffer));

Tarification

Le TTS est facturé 15 $ par million de caractères (grille de xAI au 3 novembre 2026). La facturation porte sur les caractères que vous envoyez dans text, tags expressifs inclus ; une table replace ne change pas ce compte. Avec un texte moyen de 1 000 caractères par requête, cela revient à environ 0,015 $ par appel.

Points clés à retenir

• L’endpoint POST /v1/tts est le point d’entrée principal pour la synthèse vocale
• La réponse est un fichier audio binaire, pas du JSON
• Le texte est limité à 60 000 caractères par requête HTTP ; le WebSocket n’a pas de limite totale
• L’authentification se fait via l’en-tête Authorization: Bearer
• Le coût est de 15 $ par million de caractères