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

El punto de conexión POST /v1/tts

Lección 1 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Convierte texto en audio con la API de Grok
  2. Estructura de la solicitud
  3. La respuesta HTTP
  4. Precios
  5. Puntos clave

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.

60.000
Caracteres máximos por solicitud
28
Voces integradas
20
Idiomas compatibles
15 $
Por millón de caracteres

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 es eve. Los valores no distinguen entre mayúsculas y minúsculas.
  • language (obligatorio): el código de idioma en formato BCP-47 (en, fr, de, …) o auto para 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/mpeg para MP3 (predeterminado)
  • audio/wav para WAV
  • audio/pcm para PCM crudo
  • audio/basic para G.711 ley μ (mulaw)
  • audio/alaw para 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/tts es 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