Lister les voix disponibles

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 de voix, chacune avec son identifiant, son ton et ses cas d’usage recommandés.

Exemple de réponse

{
  "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 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étadonnées détaillées de la voix demandée. C’est utile pour afficher les informations à l’utilisateur dans une interface de sélection.

Choisir la bonne voix

Le choix de la voix dépend du contexte de votre application. Voici un guide pratique :

Pour du contenu éducatif

Privilégiez leo pour son ton autoritaire qui inspire confiance, ou rex pour un style plus accessible. Ces voix sont particulièrement adaptées 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 à l’aise. Elle est aussi excellente pour les messages d’accueil téléphonique et les réponses automatisées.

Pour des démos et présentations

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

Pour un usage polyvalent

Sal offre un équilibre entre tous les styles. Si vous hésitez, c’est un choix sûr qui ne surprendra jamais négativement.

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
• Cinq voix sont disponibles : eve, ara, rex, sal, leo
• Chaque voix a un ton distinct adapté à des cas d’usage différents
• Chargez les voix dynamiquement plutôt que de les coder en dur