POST/api/v6/tts/synthesize

Sintetizar texto a voz

Convierte un texto en audio y devuelve su referencia. Síncrono.

Alcance

API key con el servicio tts habilitado

Límite de uso

60 solicitudes por minuto

Idempotencia

Admite Idempotency-Key

Hasta 4000 caracteres de texto por solicitud.
La vigencia del audio va de 1 hora a 1 año; por defecto son 30 días.

Convierte un texto en un archivo de audio y devuelve su referencia. La síntesis es síncrona: la respuesta llega cuando el audio ya está listo.

La voz se elige con voice, usando un code del catálogo (ver GET /api/v6/tts/voices). El texto admite hasta 4000 caracteres por solicitud.

El mismo texto con la misma voz se reutiliza automáticamente: si ya generaste ese audio, la respuesta llega con cached: true y sin volver a procesarlo.

Cuerpo de la petición

application/json

text

stringobligatorio

Texto a sintetizar. Entre 1 y 4000 caracteres.

voice

stringobligatorio

Código de voz del catálogo (ver GET /api/v6/tts/voices).

speakingRate

numberopcional

Velocidad de habla, de 0.25 a 4.0. Por defecto 1.0.

Por defecto: 1

format

stringopcional

Formato del audio. Por ahora solo wav.

wav

ttlSeconds

integeropcional

Vigencia del audio en segundos (mínimo 1 hora, máximo 1 año). Se fija al crear el audio; si reutilizas uno ya generado, conserva su vigencia original.

Por defecto: 2592000

{
  "text": "Hola, te llamamos de Acme para confirmar tu cita.",
  "voice": "es-us-female-2",
  "speakingRate": 1
}

Respuestas

201

Audio listo, recién generado o reutilizado.

{
  "success": true,
  "data": {
    "id": "01J9Z4M7K2QABCDEF5GHTV3WXY",
    "status": "completed",
    "cached": false,
    "charCount": 49,
    "durationMs": 3120,
    "voice": "es-us-female-2",
    "cost": "12.500000",
    "currency": "COP",
    "audioUrl": "https://storage.hablame.co/tts/9f2c...e1.wav?Expires=...&Signature=..."
  },
  "meta": {
    "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6",
    "timestamp": "2026-06-23T15:04:05+00:00",
    "responseTimeMs": 412.5
  }
}

400

Entrada inválida: texto vacío o demasiado largo, voz inexistente, o parámetro fuera de rango.

401

Credenciales inválidas o faltantes.

402

Saldo insuficiente para generar el audio.

403

La API key no tiene habilitado el servicio tts, o un tope de gasto impide la generación.

429

Se excedió el límite de solicitudes.

Errores posibles

Códigos que este endpoint puede devolver en error.code. El detalle completo está en el catálogo.

401AUTH_REQUIREDNo se envió un token Bearer y cada llamada lo requiere.401AUTH_INVALID_KEYLa API key no se reconoce: formato equivocado, revocada o vencida.401AUTH_SERVICE_NOT_ALLOWEDLa key no tiene permitido el servicio detrás de este endpoint.400BAD_REQUESTNo pudimos interpretar tu petición.403ACCOUNT_READ_ONLYModo solo lectura: solo pasan GET, HEAD y OPTIONS.429RATE_TPS_EXCEEDEDExcediste el cupo de tu organización para este endpoint.

Ver el catálogo completo

Alcance y límites

Cuerpo de la petición

Respuestas

Errores posibles