Primeros pasos con la API de texto a voz
En esta página
Actualizado el 3 de noviembre de 2026, basado en las páginas de Texto a voz y Precios de xAI. Fuentes: Texto a voz · Precios.
Texto de entrada, audio de salida
La API de texto a voz (TTS) de Grok hace una sola cosa y la hace bien: convierte texto en audio de alta calidad. Mientras que el Agente de Voz gestiona un diálogo con turnos de palabra e interrupciones, el TTS funciona estrictamente en un solo sentido: envías texto y recibes sonido. Esta simplicidad lo convierte en la herramienta ideal cuando nadie responde a la máquina: artículos narrados, mensajes de bienvenida telefónicos, locuciones para módulos de e-learning o notificaciones de audio.
HTTP o WebSocket: dos formas de llamar al servicio
El modo HTTP es el más directo. Envías una solicitud POST con tu texto y la respuesta contiene el archivo de audio completo, en MP3 de forma predeterminada:
curl -X POST "https://api.x.ai/v1/tts" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-o output.mp3 \
-d '{
"text": "Hola y bienvenido a Corsen Academy.",
"voice_id": "ara",
"language": "es"
}'
Fíjate en -o output.mp3: el cuerpo de la respuesta es audio en bruto, no un JSON que envuelve un enlace. Este modo es perfecto para la generación en segundo plano, como un proceso por lotes nocturno que produce versiones de audio de tus artículos, ya que nadie está esperando frente a una pantalla.
El modo WebSocket responde a una necesidad diferente: escuchar el sonido antes de que se haya sintetizado todo el texto. Abres una conexión y pasas los parámetros en la URL:
wss://api.x.ai/v1/tts?language=es&voice=ara&codec=mp3
A continuación, envías el texto en fragmentos con text.delta, señalas el final con text.done y el audio regresa como fragmentos en base64 en audio.delta. La transmisión elimina el límite de longitud del modo HTTP y, sobre todo, te permite sintetizar sobre la marcha, algo esencial cuando el texto aún lo está generando un modelo.
Parámetros de la solicitud HTTP
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
text | string | Sí | El texto a convertir, hasta 60.000 caracteres |
voice_id | string | No | La voz a utilizar (predeterminada: eve) |
language | string | Sí | Código BCP-47 (es, fr, de, …) o auto |
output_format | object | No | Códec, frecuencia de muestreo y tasa de bits |
speed | number | No | Velocidad de reproducción, de 0,7 a 1,5 (predeterminada: 1,0) |
Dos puntos merecen atención. language es obligatorio, lo que suele sorprender: el servicio no adivina el idioma de tu texto a menos que se lo pidas explícitamente con el valor auto. Y voice_id utiliza exactamente las mismas voces que el Agente de Voz (28 voces integradas a fecha de 3 de noviembre de 2026, incluidas eve, ara, rex, sal y leo, además de tus voces personalizadas) y no distingue entre mayúsculas y minúsculas. La misma persona de voz puede, por tanto, impulsar tanto tu agente conversacional como tu contenido grabado, algo que vale la pena aprovechar para mantener la coherencia de marca.
Elige el formato de salida
El campo output_format controla el códec y la calidad:
{
"text": "Texto a convertir.",
"voice_id": "rex",
"language": "es",
"output_format": {
"codec": "wav",
"sample_rate": 44100
}
}
Elige el códec en función de lo que vaya a ocurrir con el archivo a continuación. mp3 es adecuado para un uso general: bien comprimido y reproducible en todas partes, es la opción sensata por defecto para un sitio web o un pódcast. wav no tiene pérdidas, por lo que es más pesado, pero es lo que necesitas cuando un editor va a retocar la pista. pcm entrega audio en bruto, para tuberías de procesamiento que no necesitan un contenedor. Por último, mulaw y alaw son los códecs de telefonía G.711, para sistemas de telecomunicaciones que los requieran.
Las frecuencias de muestreo oscilan entre 8000 y 48000 Hz, con un valor predeterminado de 24000 Hz, que cubre la gran mayoría de los usos. Para MP3, la tasa de bits va de 32000 a 192000 bps, con un valor predeterminado de 128000. Subir hasta 192000 para voz hablada apenas aporta nada a la experiencia de escucha y hace que tus archivos sean un tercio más grandes: guarda ese margen para contenido que mezcle música y voz.
Consulta el catálogo de voces
La API expone dos extremos de solo lectura que complementan la generación. GET /v1/tts/voices devuelve todas las voces disponibles con sus metadatos, y GET /v1/tts/voices/{voice_id} devuelve los mismos campos (voice_id, name, language) para una sola voz; el tono y los casos de uso de cada voz se describen en la página de Texto a voz de xAI. En lugar de codificar los nombres de las voces directamente en tu interfaz, rellena tu selector de voces desde estos extremos; así, tu aplicación seguirá siendo correcta el día que cambie el catálogo.
Puntos clave
- El TTS convierte texto a audio mediante HTTP (sencillo) o WebSocket (transmisión)
- Cuesta 15 $ por millón de caracteres, con un máximo de 60.000 caracteres por solicitud HTTP
- 28 voces integradas, cinco códecs y seis frecuencias de muestreo te ofrecen mucha flexibilidad
- El modo WebSocket no tiene límite en la longitud total del texto (cada delta tiene un tope de 60.000 caracteres)
- Se requiere un código BCP-47 para especificar el idioma (o
autopara la detección automática)