Referencia de la API

URL base https://api.vocallab.ai. Cada solicitud necesita Authorization: Bearer vl_live_... (consulta Claves de API).

GET /api/v1/ping

Prueba de conexión y autenticación. Devuelve tu saldo de puntos.

{ "ok": true, "points": 12345, "unit": "points (1 pt ≈ 1 second of audio)" }

GET /api/v1/voices

Voces que puedes usar: el catálogo público más tus propias voces clonadas y diseñadas. Usa un id devuelto como voice para la generación. Las voces del catálogo también aceptan su slug.

{ "voices": [
  { "id": "Ashley", "slug": "warm-natural-female-explainer-voice-for-youtube-podcasts",
    "name": "Warm Natural Female Explainer Voice for YouTube & Podcasts",
    "type": "preset", "languages": ["en"], "category": "Narration" },
  { "id": "default-abc123__my-voice", "name": "My Narrator", "type": "clone", "languages": ["en"] }
] }

GET /api/v1/models

Los modelos de voz seleccionables. Pasa una key como model en POST /api/v1/tts (por defecto v-pro). Las claves de API pueden usar los tres. Consulta Modelos de voz para conocer las diferencias.

{ "default": "v-pro", "models": [
  { "key": "v-studio", "label": "VocalLab Studio", "steerable": true,  "costMultiplier": 1 },
  { "key": "v-pro",    "label": "VocalLab Pro",    "steerable": false, "costMultiplier": 1 },
  { "key": "v-lite",   "label": "VocalLab Lite",   "steerable": false, "costMultiplier": 0.5 }
] }

POST /api/v1/tts

Genera voz.

curl -X POST https://api.vocallab.ai/api/v1/tts \
  -H "Authorization: Bearer vl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from VocalLab","voice":"Ashley"}'

Devuelve el audio en línea (base64) más un id. La URL alojada aparece una vez que finaliza la subida; consúltala con GET /api/v1/tts/:id.

Cada solicitud está limitada a 2.000 caracteres y corresponde exactamente a una síntesis de voz: no hay divisiones ni ramificaciones ocultas, por lo que el coste y la latencia por llamada se mantienen predecibles. Las solicitudes se contabilizan sobre tu saldo de puntos y pasan por una cola de uso justo, de modo que la automatización intensiva nunca bloquea la aplicación. Para narrar un texto más largo, divídelo en fragmentos de ≤ 2.000 caracteres y envíalos como llamadas separadas (respetando el límite de 60 solicitudes/minuto).

{ "id": "...", "status": "pending", "audio_base64": "data:audio/mp3;base64,...",
  "audio_url": null, "format": "MP3", "model": "v-pro", "points_used": 12 }

Modelo y coste. v-lite factura la mitad de los puntos que v-pro/v-studio (points = ⌈ characters ÷ 30 ⌉ en lugar de ÷ 15). v-studio es el único modelo que sigue instrucciones de expresión/dirección; consulta Modelos de voz y Dirección de voz.

Pausas

Inserta un silencio de duración exacta con una etiqueta <break /> autocerrada dentro de text:

{ "text": "Déjame pensar <break time=\"1.5s\" /> Sí, ya lo he pensado.", "voice": "Ashley" }

• Segundos o milisegundos — 1.5s = 1500ms.
• Hasta 20 etiquetas break por solicitud, en todos los idiomas admitidos.
• Las etiquetas break cuentan para el límite de 2.000 caracteres y se eliminan de los subtítulos/SRT.

GET /api/v1/tts/:id

Estado de la generación y la URL del audio alojado cuando está lista.

{ "id": "...", "status": "ready", "audio_url": "https://...", "format": "MP3" }

GET /api/v1/me

Tu saldo de puntos y tu plan.

Errores

Los errores tienen la forma { "error": { "code": "...", "message": "..." } }.

Precios

Las generaciones se cobran de tu saldo de puntos, calculado a partir de la longitud del texto (no de la duración final del audio):

points = ⌈ characters ÷ 15 ⌉      (tarifa de la API — unos 15 caracteres por punto)

⌈ ⌉ redondea hacia arriba al siguiente punto entero. La aplicación web usa 17 caracteres por punto, por lo que la API conlleva un pequeño recargo (~13 %). Los puntos se contabilizan antes de la llamada al proveedor: una solicitud que superaría tu saldo devuelve 402 y nunca se genera. Cada respuesta incluye el points_used exacto. Como la voz promedia ~15–17 caracteres/segundo, 1 punto ≈ 1 segundo de audio, pero el cargo exacto siempre sigue la fórmula anterior. Consulta Créditos y minutos para más información.