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’entree principal est POST /v1/tts, qui accepte votre texte et retourne directement un fichier audio binaire.

Structure de la requete

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 repond directement avec le fichier audio binaire dans le corps de la reponse. 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 cle API dans l’en-tete Authorization au format Bearer :

Authorization: Bearer xai-votre-cle-api

Corps de la requete

Le corps JSON contient quatre parametres principaux :

• text (requis) : le texte a convertir, jusqu’a 15 000 caracteres. Il supporte les tags expressifs que vous decouvrirez dans les lecons suivantes
• voice_id (optionnel) : l’identifiant de la voix. Par defaut eve. Les valeurs sont insensibles a la casse
• language (requis) : le code langue au format BCP-47 (fr, en, de…) ou auto pour la detection automatique
• output_format (optionnel) : un objet pour configurer le codec, le sample rate et le bit rate

La reponse HTTP

En cas de succes (code 200), le serveur retourne le fichier audio avec le content-type correspondant au format demande :

• audio/mpeg pour MP3 (defaut)
• audio/wav pour WAV
• audio/pcm pour PCM brut

Il n’y a pas de metadonnees dans la reponse : uniquement les octets audio. Vous pouvez ecrire directement la reponse 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 synthese 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 synthese vocale.",
    voice_id: "rex",
    language: "fr"
  })
});

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

Tarification

Le TTS est facture a 4,20 $ par million de caracteres. La facturation est basee sur le nombre de caracteres du champ text, tags expressifs inclus. Avec un texte moyen de 1 000 caracteres par requete, cela revient a environ 0,004 $ par appel.

Points cles a retenir

• L’endpoint POST /v1/tts est le point d’entree principal pour la synthese vocale
• La reponse est un fichier audio binaire, pas du JSON
• Le texte est limite a 15 000 caracteres par requete
• L’authentification se fait via l’en-tete Authorization: Bearer
• Le cout est de 4,20 $ par million de caracteres