API de Transcripción: Descripción general, autenticación y límites
Cómo usar la API REST de VoxScriber: quién tiene acceso, cómo funcionan las claves vpt_live_, autenticación Bearer, límites de peticiones y facturación por ciclos.
La API REST de VoxScriber permite enviar audios por URL y recibir la transcripción lista en tu sistema, sin pasar por el sitio web. Usa los mismos motores y cobra los mismos ciclos que las transcripciones hechas en el panel.
Quién puede usarla
La API está disponible a partir del plan Profesional (R$ 39,90/mes). Tienen acceso: Profesional, Premium, todos los planes Empresariales (mensuales y anuales) y los planes heredados equivalentes. Si tu cuenta no es elegible, las rutas de clave devuelven el error 403 PLAN_NOT_ELIGIBLE.
Claves de API
Crea la clave
Copia el secreto inmediatamente
vpt_live_... y se muestra una única vez, en el momento de la creación. Solo guardamos un hash de ella; no es posible recuperarla después.Guárdala de forma segura
¿Has perdido la clave? No hay forma de volver a mostrarla. Revoca la clave antigua y crea una nueva. Las claves comprometidas deben revocarse inmediatamente.
La creación de claves personales aún no tiene una pantalla dedicada en el panel. Si tu plan es elegible y quieres empezar a usar la API, abre un ticket y el equipo activa el acceso contigo.
Autenticación
Toda petición lleva la clave en la cabecera Authorization:
Authorization: Bearer vpt_live_SUA_CHAVE
Una petición sin la cabecera devuelve 401 MISSING_API_KEY.
Enviar un audio para transcripción
El endpoint de transcripción está en el gateway api.voxscriber.com:
curl -X POST https://api.voxscriber.com/v1/transcriptions \
-H "Authorization: Bearer vpt_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://exemplo.com/gravacoes/reuniao.mp3",
"webhook_url": "https://seusistema.com/webhooks/vozparatexto",
"formats": ["txt", "srt"]
}'
Campos aceptados en el cuerpo: audio_url, webhook_url, engine (ASSEMBLYAI, WHISPER o ELEVENLABS), language, formats (txt, json, srt, vtt, docx, pdf), metadata e idempotency_key. El resultado llega a tu webhook_url — consulta Webhooks y notificaciones.
Usa idempotency_key con un identificador propio (p. ej., el ID de la grabación en tu sistema). Si la misma petición se reenvía por error, el audio no se procesa — ni se cobra — dos veces.
Límites
| Límite | Valor |
|---|---|
| Peticiones por clave | 60 por minuto |
| Audio descargado por URL | hasta 500 MB (timeout de 60 s) |
| Audio mediante passthrough (el engine Premium lee la URL directamente) | hasta 5 GB |
| Claves activas por cuenta | 20 |
Reglas de seguridad en las URLs: solo https, sin redirecciones, y las direcciones internas/privadas están bloqueadas. La URL del audio debe ser accesible públicamente.
Los formatos de exportación disponibles siguen las condiciones de tu plan, igual que en el sitio web. Los formatos fuera del plan se devuelven listados en exports_skipped.
Cobranza
La API descuenta los mismos ciclos que una transcripción hecha en el sitio web, según el engine elegido (Estándar/Whisper: 1 ciclo/min; Premium: 4 ciclos/min; Ultra: 10 ciclos/min). Hoy no existe una cuota mensual de llamadas ni un tope de gasto por clave: controla el consumo mediante tu saldo de ciclos. Consulta Qué Son los Ciclos y Cuánto Cuesta Cada Minuto.
FAQ
Perdí mi clave de API. ¿Cómo la recupero?
No se puede recuperar; solo queda el hash en la base de datos. Revoca la clave perdida y crea una nueva.
¿La API cobra más caro que el sitio web?
No. El costo en ciclos es idéntico; lo define el engine y la duración del audio.
¿Puedo enviar el archivo directamente en lugar de una URL?
El canal principal es mediante audio_url. Si tus audios no tienen URL pública, contacta con el soporte para evaluar el mejor flujo para tu caso.
¿Existe documentación OpenAPI?
La spec pública en /.well-known/openapi.json cubre hoy solo los endpoints públicos (estadísticas y transcripciones compartidas). Para el resto, usa esta central de ayuda y el soporte.
Artículos relacionados
- Webhooks y notificaciones
- Automatizar con la API
- Qué Son los Ciclos y Cuánto Cuesta Cada Minuto
- Exportar a otras herramientas
¿No lo resolviste? Abre un ticket: nuestro equipo responde rápido.