Ir al contenido principal
Español— Elegir un idioma
Menú

Listar las voces disponibles

Lección 3 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Descubrir voces mediante programación
  2. GET /v1/tts/voices
  3. GET /v1/tts/voices/{voice_id}
  4. Elegir la voz adecuada
  5. Integrar la selección de voz en tu aplicación
  6. Buenas prácticas
  7. Puntos clave

Actualizado el 3 de noviembre de 2026, según la referencia de la API de voz de xAI y la página Text to Speech: la respuesta de GET /v1/tts/voices incluye voice_id, name y language, y xAI ofrece 28 voces integradas. Fuentes: Voice API · Text to Speech.

Descubrir voces mediante programación

En lugar de codificar manualmente la lista de voces en tu aplicación, la API de xAI proporciona un endpoint dedicado para obtener las voces disponibles de forma dinámica. De este modo, te mantendrás actualizado cuando se añadan nuevas voces.

GET /v1/tts/voices

Este endpoint devuelve la lista de todas las voces disponibles para TTS. No requiere ningún parámetro en el cuerpo de la solicitud.

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

La respuesta es un objeto JSON que contiene un array voices. Según la referencia de la API, cada voz tiene tres campos: voice_id, el identificador en minúsculas que debes pasar en tus solicitudes; name, un nombre para mostrar; y language, un código de idioma que puede ser nulo.

Estructura de la respuesta

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

Las elipsis representan valores que la referencia no ofrece como ejemplos: imprime la respuesta real una vez antes de depender de ella. El tono y los casos de uso de cada voz no aparecen en esta respuesta; se describen en la página Text to Speech de xAI.

GET /v1/tts/voices/{voice_id}

Para obtener los detalles de una voz concreta, añade su ID a la ruta:

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

Esta llamada devuelve los mismos campos (voice_id, name, language) únicamente para la voz solicitada.

Elegir la voz adecuada

xAI ofrece 28 voces integradas (a fecha de 3 de noviembre de 2026) y, para la mayoría de ellas, describe para qué son más adecuadas. Algunos consejos extraídos de esa página:

  • Contenido educativo: luna, cosmo o lumen, enumeradas para educación
  • Atención al cliente: carina, iris, rigel, celeste, castor, naksh o aurora, enumeradas para soporte
  • Publicidad y demostraciones: altair, zenith, perseus, kepler o lumen, enumeradas para publicidad; eve, enérgica y optimista, sigue siendo la voz predeterminada
  • Narración y audiolibros: orion, zagan, altair, perseus o lux
  • Bienestar: carina, helios, lux o liora

Las cinco voces originales (eve, ara, rex, sal, leo) no tienen casos de uso listados: xAI solo las describe como enérgica y optimista (acento británico), cálida y amigable, segura y clara, suave y equilibrada, y autoritaria y potente (acento británico).

Integrar la selección de voz en tu aplicación

Aquí tienes un ejemplo que carga las voces disponibles de forma dinámica:

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="en"):
    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"Voz desconocida '{voice_id}'. 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

Este enfoque te protege de errores tipográficos en los ID de voz y te permite ofrecer a tus usuarios una lista actualizada.

Buenas prácticas

  • Almacena en caché la lista de voces: el endpoint /v1/tts/voices no cambia a menudo, por lo que basta con una llamada al iniciar tu aplicación
  • Ofrece una vista previa: permite a tus usuarios escuchar una muestra de cada voz antes de elegirla
  • Guarda la preferencia: una vez que un usuario haya elegido una voz, almacena la elección para futuras sesiones
  • Prueba en el idioma de destino: una voz que suena genial en inglés puede sonar diferente en otro idioma. Prueba siempre en el idioma de tu aplicación

Puntos clave

  • GET /v1/tts/voices lista todas las voces disponibles con sus metadatos
  • GET /v1/tts/voices/{voice_id} ofrece los detalles de una voz específica
  • Hay 28 voces integradas disponibles; su tono y casos de uso se describen en la página Text to Speech de xAI
  • La respuesta de GET /v1/tts/voices proporciona voice_id, name y language para cada voz
  • Carga las voces de forma dinámica en lugar de codificarlas manualmente