Automatizar transcripciones con la API: ejemplos prácticos
Write: "Automatización con la API de VoxScriber: envía grabaciones por URL, elige engine y formatos, usa idempotency_key y metadata, y recibe todo por webhook.
Con la API puedes transformar cualquier fuente de grabaciones — telefonía, grabadora de reuniones, sistema interno — en texto buscable, sin intervención manual. Este artículo presenta el flujo recomendado y recetas listas para usar. Antes, consulta los requisitos en API de transcripción (plan Profesional+ y clave vpt_live_).
El flujo recomendado
- Envía el audio por URL con un
webhook_url. - Recibe el callback cuando termine (éxito o fallo).
- Descarga los archivos exportados mediante los enlaces del resultado; son válidos durante 7 días.
Nada de polling: con un límite de 60 peticiones/minuto por clave, consultar el estado en bucle desperdicia la cuota. El webhook entrega el desenlace por sí solo, con hasta 6 reintentos si tu servidor está fuera de línea.
Receta 1 — transcribir cada grabación nueva
curl -X POST https://api.voxscriber.com/v1/transcriptions \
-H "Authorization: Bearer $VPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://storage.suaempresa.com/calls/2026-08-02-0931.mp3",
"webhook_url": "https://api.suaempresa.com/hooks/vpt",
"formats": ["txt", "docx"],
"metadata": { "call_id": "0931", "agente": "maria" },
"idempotency_key": "call-2026-08-02-0931"
}'
metadatase incluye en el webhook; úsalo para correlacionar el resultado con el registro de tu sistema.idempotency_keygarantiza que los reintentos accidentales (retry por tu parte, despliegue a mitad del trabajo) no procesen ni cobren el mismo audio dos veces.
Receta 2 — elegir la engine según el coste
El campo engine acepta ASSEMBLYAI (Premium, predeterminada), WHISPER (Estándar) y ELEVENLABS (Ultra). Para volumen alto en el que el coste importa más que el acabado, usa Whisper — 1 ciclo/min frente a 4 del Premium:
-d '{ "audio_url": "...", "webhook_url": "...", "engine": "WHISPER" }'
Regla práctica: Premium para reuniones y entrevistas importantes; Estándar (Whisper) para volumen alto y audio con ruido; Ultra cuando la separación de hablantes debe ser impecable (disponible en Profesional+).
Receta 3 — subtítulos automáticos
Pide formats: ["srt", "vtt"] y recibe los subtítulos listos para YouTube o reproductores web en el propio webhook. Detalles de cada formato en Exportar para otras herramientas.
Límites que afectan a las automatizaciones
| Elemento | Regla |
|---|---|
| Rate limit | 60 peticiones/min por clave |
audio_url | solo https, pública, hasta 500 MB (descarga) o 5 GB mediante passthrough con la engine Premium |
| Formatos | siguen las restricciones de tu plan; los no permitidos se devuelven en exports_skipped |
| Enlaces de descarga | caducan en 7 días (la transcripción permanece en el acervo) |
| Ciclos | mismos costes del sitio, debitados del mismo saldo |
Supervisa tu saldo de ciclos: hoy no existe un tope de gasto por clave. Una automatización con un bucle descontrolado consume saldo real. La idempotency_key es tu primera línea de defensa.
FAQ
¿Cómo recibo el texto final: en el webhook o necesito descargarlo?
El webhook trae el resultado y los enlaces de los archivos exportados en los formatos solicitados. Descarga los archivos en un plazo de 7 días; después, el contenido sigue disponible en el acervo del sitio.
¿Puedo definir el idioma del audio?
Sí, mediante el campo language. Sin él, se aplica el idioma predeterminado de la cuenta; la detección automática también está soportada por las engines.
¿Y si dos sistemas envían el mismo audio?
Usa la misma idempotency_key en ambos: solo el primero procesa y cobra.
¿La automatización funciona para miembros de organización?
Sí, y el consumo sigue las reglas del plan de la empresa. Para auditoría de llamadas a escala, consulta la API dedicada.
Artículos relacionados
- API de transcripción
- Webhooks y notificaciones
- API Enterprise de auditoría
- Qué Son los Ciclos y Cuánto Cuesta Cada Minuto
¿No se ha resuelto? Abre un ticket — nuestro equipo responde rápido.