El punto de conexión POST /v1/tts
En esta página
Actualizado el 3 de noviembre de 2026, basado en la página Text to Speech de xAI, la referencia de la API de voz y la página de Precios. Fuentes: Text to Speech · Voice API · Pricing.
Convierte texto en audio con la API de Grok
La API de texto a voz (Text-to-Speech) de xAI transforma cualquier texto en audio de sonido natural mediante una única llamada HTTP. El punto de entrada principal es POST /v1/tts, que recibe tu texto y devuelve directamente un archivo de audio binario.
Estructura de la solicitud
Envías una petición POST a https://api.x.ai/v1/tts con un cuerpo JSON. Aquí tienes un ejemplo mínimo con curl:
curl -X POST "https://api.x.ai/v1/tts" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello, and welcome to Corsen Academy.",
"voice_id": "eve",
"language": "en"
}' \
--output audio.mp3
El servidor responde con el archivo de audio binario directamente en el cuerpo de la respuesta. No hay ningún contenedor JSON alrededor: obtienes los bytes crudos del archivo de audio.
Autenticación
Al igual que con cualquier punto de conexión de la API de xAI, debes incluir tu clave de API en la cabecera Authorization en formato Bearer:
Authorization: Bearer xai-your-api-key
Cuerpo de la solicitud
El cuerpo JSON gira en torno a cuatro parámetros principales:
text(obligatorio): el texto que se va a convertir, hasta 60.000 caracteres. Admite las etiquetas expresivas que aprenderás en las próximas lecciones.voice_id(opcional): el identificador de la voz. El valor predeterminado eseve. Los valores no distinguen entre mayúsculas y minúsculas.language(obligatorio): el código de idioma en formato BCP-47 (en,fr,de, …) oautopara la detección automática.output_format(opcional): un objeto que configura el códec, la frecuencia de muestreo y la tasa de bits.
Otros ajustes, todos opcionales, completan la solicitud: speed (velocidad de reproducción, de 0,7 a 1,5; 1,0 por defecto), replace (una tabla de sustituciones que corrige cómo se pronuncia una palabra sin cambiar el texto que envías), with_timestamps (marcas de tiempo por carácter), text_normalization (deletreo de números, abreviaturas y símbolos antes de la síntesis) y optimize_streaming_latency ("1" para reducir la espera antes del primer fragmento de audio, a costa de una ligera pérdida de calidad en las uniones).
La respuesta HTTP
En caso de éxito (estado 200), el servidor devuelve el archivo de audio con el tipo de contenido que coincide con el formato solicitado:
audio/mpegpara MP3 (predeterminado)audio/wavpara WAVaudio/pcmpara PCM crudoaudio/basicpara G.711 ley μ (mulaw)audio/alawpara G.711 ley A (alaw)
La respuesta no contiene metadatos, solo bytes de audio. La única excepción es with_timestamps: en ese caso, la respuesta se convierte en un objeto JSON que contiene el audio en base64, su duración y la marca de tiempo de cada carácter. Puedes escribir la respuesta directamente en un archivo o transmitirla a un reproductor de audio.
Ejemplo en Python
import requests
response = requests.post(
"https://api.x.ai/v1/tts",
headers={"Authorization": f"Bearer {api_key}"},
json={
"text": "Here's an example of speech synthesis.",
"voice_id": "rex",
"language": "en"
}
)
with open("output.mp3", "wb") as f:
f.write(response.content)
Ejemplo en JavaScript (Node.js)
const response = await fetch("https://api.x.ai/v1/tts", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.XAI_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
text: "Here's an example of speech synthesis.",
voice_id: "rex",
language: "en"
})
});
const buffer = await response.arrayBuffer();
fs.writeFileSync("output.mp3", Buffer.from(buffer));
Precios
El servicio TTS cuesta 15 $ por millón de caracteres (precios de xAI a 3 de noviembre de 2026). Se te factura por los caracteres que envías en text, incluidas las etiquetas expresivas; una tabla replace no modifica ese recuento. Con una media de 1.000 caracteres por solicitud, el coste asciende a unos 0,015 $ por llamada.
Puntos clave
- El punto de conexión
POST /v1/ttses la entrada principal para la síntesis de voz - La respuesta es un archivo de audio binario, no JSON
- El texto está limitado a 60.000 caracteres por solicitud HTTP; WebSocket no tiene límite total
- La autenticación se realiza con la cabecera
Authorization: Bearer - El coste es de 15 $ por millón de caracteres