Endpoint POST /v1/tts

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 contient quatre paramètres principaux :

• text (requis) : le texte à convertir, jusqu’à 15 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

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

Il n’y a pas de métadonnées dans la réponse : uniquement les octets audio. 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é à 4,20 $ par million de caractères. La facturation est basée sur le nombre de caractères du champ text, tags expressifs inclus. Avec un texte moyen de 1 000 caractères par requête, cela revient à environ 0,004 $ 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é à 15 000 caractères par requête
• L’authentification se fait via l’en-tête Authorization: Bearer
• Le coût est de 4,20 $ par million de caractères