Lister les voix disponibles

Leçon corrigée le 3 novembre 2026 d’après la référence de l’API Voice et la page Text to Speech de xAI : la réponse de GET /v1/tts/voices porte voice_id, name et language, et non les champs description et use_cases de l’ancien exemple ; xAI propose 28 voix intégrées et non cinq. Sources : Voice API · Text to Speech.

Découvrir les voix programmatiquement

Plutôt que de coder en dur la liste des voix dans votre application, l’API xAI fournit un endpoint dédié pour récupérer dynamiquement les voix disponibles. Cela vous permet de rester à jour quand de nouvelles voix sont ajoutées.

GET /v1/tts/voices

Cet endpoint retourne la liste de toutes les voix disponibles pour le TTS. Il ne nécessite aucun paramètre dans le corps de la requête.

curl -X GET "https://api.x.ai/v1/tts/voices" \
  -H "Authorization: Bearer $XAI_API_KEY"

La réponse est un objet JSON contenant un tableau voices. D’après la référence de l’API, chaque voix porte trois champs : voice_id, l’identifiant en minuscules à passer dans vos requêtes ; name, un nom d’affichage ; et language, un code de langue qui peut être nul.

Forme de la réponse

{
  "voices": [
    {"voice_id": "eve", "name": "…", "language": "…"},
    {"voice_id": "ara", "name": "…", "language": "…"}
  ]
}

Les points de suspension remplacent des valeurs que la référence ne donne pas en exemple : affichez la réponse réelle une fois avant de l’exploiter. Le ton et les usages de chaque voix, eux, ne figurent pas dans cette réponse : ils sont décrits sur la page Text to Speech de xAI.

GET /v1/tts/voices/{voice_id}

Pour obtenir les détails d’une voix spécifique, ajoutez son identifiant dans le chemin :

curl -X GET "https://api.x.ai/v1/tts/voices/rex" \
  -H "Authorization: Bearer $XAI_API_KEY"

Cet appel retourne les mêmes champs (voice_id, name, language) pour la seule voix demandée.

Choisir la bonne voix

xAI propose 28 voix intégrées (relevé du 3 novembre 2026) et décrit, pour la plupart, leurs usages de prédilection. Quelques repères tirés de cette page :

• Contenu éducatif : luna, cosmo ou lumen, classées en éducation
• Support client : carina, iris, rigel, celeste, castor, naksh ou aurora, classées en support
• Publicité et démos : altair, zenith, perseus, kepler ou lumen, classées en publicité ; eve, énergique et enjouée, reste la voix par défaut
• Narration et livres audio : orion, zagan, altair, perseus ou lux
• Bien-être : carina, helios, lux ou liora

Les cinq voix d’origine (eve, ara, rex, sal, leo) n’ont pas d’usages indiqués : xAI les décrit seulement comme énergique et enjouée (accent britannique), chaleureuse et amicale, confiant et clair, doux et équilibré, autoritaire et puissant (accent britannique).

Intégrer la sélection de voix dans votre application

Voici un exemple de composant qui charge dynamiquement les voix disponibles :

import requests

def get_available_voices(api_key):
    response = requests.get(
        "https://api.x.ai/v1/tts/voices",
        headers={"Authorization": f"Bearer {api_key}"}
    )
    response.raise_for_status()
    return response.json()["voices"]

def synthesize(api_key, text, voice_id="eve", language="fr"):
    voices = get_available_voices(api_key)
    valid_ids = [v["voice_id"] for v in voices]

    if voice_id.lower() not in valid_ids:
        raise ValueError(f"Voix '{voice_id}' inconnue. Disponibles : {valid_ids}")

    response = requests.post(
        "https://api.x.ai/v1/tts",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"text": text, "voice_id": voice_id, "language": language}
    )
    return response.content

Cette approche vous protège contre les erreurs de frappe dans les identifiants de voix et vous permet de proposer une liste à jour à vos utilisateurs.

Bonnes pratiques

• Cachez la liste des voix : l’endpoint /v1/tts/voices ne change pas souvent. Un appel au démarrage de votre application suffit
• Proposez un aperçu : permettez à vos utilisateurs d’écouter un échantillon de chaque voix avant de choisir
• Stockez la préférence : une fois que l’utilisateur a choisi sa voix, sauvegardez son choix pour les sessions suivantes
• Testez dans la langue cible : une voix agréable en anglais peut avoir un rendu différent en français. Testez toujours dans la langue de votre application

Points clés à retenir

• GET /v1/tts/voices liste toutes les voix disponibles avec leurs métadonnées
• GET /v1/tts/voices/{voice_id} donne les détails d’une voix spécifique
• 28 voix intégrées sont disponibles ; leur ton et leurs usages sont décrits sur la page Text to Speech de xAI
• La réponse de GET /v1/tts/voices donne voice_id, name et language pour chaque voix
• Chargez les voix dynamiquement plutôt que de les coder en dur