Lister les voix disponibles

Decouvrir les voix programmatiquement

Plutot que de coder en dur la liste des voix dans votre application, l’API xAI fournit un endpoint dedie pour recuperer dynamiquement les voix disponibles. Cela vous permet de rester a jour quand de nouvelles voix sont ajoutees.

GET /v1/tts/voices

Cet endpoint retourne la liste de toutes les voix disponibles pour le TTS. Il ne necessite aucun parametre dans le corps de la requete.

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

La reponse est un objet JSON contenant un tableau de voix, chacune avec son identifiant, son ton et ses cas d’usage recommandes.

Exemple de reponse

{
  "voices": [
    {
      "voice_id": "eve",
      "description": "Energetic and playful",
      "use_cases": ["demos", "announcements"]
    },
    {
      "voice_id": "ara",
      "description": "Warm and friendly",
      "use_cases": ["customer support", "narration"]
    },
    {
      "voice_id": "rex",
      "description": "Confident and clear",
      "use_cases": ["business presentations", "tutorials"]
    },
    {
      "voice_id": "sal",
      "description": "Soft and balanced",
      "use_cases": ["general purpose"]
    },
    {
      "voice_id": "leo",
      "description": "Authoritative",
      "use_cases": ["instructions", "educational content"]
    }
  ]
}

GET /v1/tts/voices/{voice_id}

Pour obtenir les details d’une voix specifique, 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 metadonnees detaillees de la voix demandee. C’est utile pour afficher les informations a l’utilisateur dans une interface de selection.

Choisir la bonne voix

Le choix de la voix depend du contexte de votre application. Voici un guide pratique :

Pour du contenu educatif

Privilegiez leo pour son ton autoritaire qui inspire confiance, ou rex pour un style plus accessible. Ces voix sont particulierement adaptees aux tutoriels, aux cours en ligne et aux explications techniques.

Pour du support client

Ara est le choix naturel : son ton chaleureux met l’interlocuteur a l’aise. Elle est aussi excellente pour les messages d’accueil telephonique et les reponses automatisees.

Pour des demos et presentations

Eve apporte de l’energie et du dynamisme. C’est la voix par defaut pour une bonne raison : elle fonctionne bien dans la plupart des contextes grand public.

Pour un usage polyvalent

Sal offre un equilibre entre tous les styles. Si vous hesitez, c’est un choix sur qui ne surprendra jamais negativement.

Integrer la selection 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 protege contre les erreurs de frappe dans les identifiants de voix et vous permet de proposer une liste a jour a vos utilisateurs.

Bonnes pratiques

• Cachez la liste des voix : l’endpoint /v1/tts/voices ne change pas souvent. Un appel au demarrage de votre application suffit
• Proposez un apercu : permettez a vos utilisateurs d’ecouter un echantillon de chaque voix avant de choisir
• Stockez la preference : une fois que l’utilisateur a choisi sa voix, sauvegardez son choix pour les sessions suivantes
• Testez dans la langue cible : une voix agreable en anglais peut avoir un rendu different en francais. Testez toujours dans la langue de votre application

Points cles a retenir

• GET /v1/tts/voices liste toutes les voix disponibles avec leurs metadonnees
• GET /v1/tts/voices/{voice_id} donne les details d’une voix specifique
• Cinq voix sont disponibles : eve, ara, rex, sal, leo
• Chaque voix a un ton distinct adapte a des cas d’usage differents
• Chargez les voix dynamiquement plutot que de les coder en dur