API de WizCut
Subí, procesá y renderizá ediciones de podcasts multicam de forma programática con la API de WizCut.
La API de WizCut te permite automatizar la edición de podcasts multicam. Subís los ángulos de cámara, WizCut detecta los hablantes, averigua quién está en cuál cámara y genera los cortes, opcionalmente los revisás en un editor online, y recibís el video renderizado por webhook.
La especificación completa de OpenAPI 3.1 está en https://wizcut.com/openapi.json, pensada para generadores de código y plataformas de agentes. ¿Preferís que ChatGPT, Claude o tu propio agente edite por vos? Mirá Usar WizCut con ChatGPT, Claude y otros agentes de IA.
Autenticación
Creá una API key en wizcut.com/settings. Incluila en cada request:
Authorization: Bearer wc_live_your_key_here
Las keys se pueden revocar en cualquier momento desde la página de configuración.
Crear un job
POST /api/jobs
{
"sources": [
{ "label": "Camera 1", "kind": "video", "ext": "mp4", "fileSize": 2147483648 },
{ "label": "Camera 2", "kind": "video", "ext": "mp4", "fileSize": 1932735283 },
{ "label": "Mic mix", "kind": "audio", "ext": "wav" }
],
"callbackUrl": "https://your-server.com/webhook",
"review": true,
"autoMap": "confident",
"silence": { "mode": "tighten" }
}
Campos:
| Campo | Tipo | Descripción |
|---|---|---|
sources | array | Ángulos de cámara o archivos de audio, hasta 12 por job. Un job necesita al menos dos fuentes de video para poder procesarse. Cada uno tiene label, kind opcional ("video" o "audio", por defecto "video"), ext opcional (mp4, mov, webm, mkv, wav, mp3, m4a o aac; por defecto "mp4" para video, "wav" para audio) y fileSize opcional: el tamaño exacto del archivo en bytes, hasta 100 GB (107374182400 bytes) por archivo. |
title | string | Opcional. Un nombre para el job, como el título del episodio, de hasta 200 caracteres. Si no lo pasás, el título se arma con los nombres de las fuentes y la fecha. |
callbackUrl | string | Opcional. URL que recibe las notificaciones webhook, ver Webhooks. |
review | boolean | Por defecto true. Con true, el job se pausa en “ready” para que un humano revise los cortes antes del render. Con false, el render arranca automáticamente apenas se envía el mapeo de hablantes, ya sea una persona, tu código o el propio WizCut. |
autoMap | string | Por defecto "confident". Si WizCut puede decidir por su cuenta quién está en cuál cámara: "off", "confident" o "always", ver Mapeo automático de cámaras. |
silence | object | Opcional. Eliminación automática de pausas, ver Eliminación de silencios. Si se omite, está desactivado. |
share | boolean | Por defecto true. Le da al video terminado una página para compartir no listada, que puede abrir cualquiera que tenga el link, ver Links para compartir y descargar. |
No se puede pasar el mapeo de hablantes (tracks) acá: los IDs de fuente recién existen cuando el job está creado, así que todavía no hay a qué cámara apuntar un hablante. Una lista tracks que nombre hablantes se rechaza con 400 y "code": "TRACKS_ON_CREATE". Usá autoMap, o mapeá los hablantes por la API cuando termine la detección de hablantes.
Pasá fileSize para todo archivo del que sepas el tamaño. Los archivos de más de 100 MB usan entonces una subida multipart: podés subir las partes en paralelo, reintentar una sola parte, y es la única forma de subir archivos de más de 5 GB. Sin fileSize, todos los archivos se suben con un único PUT prefirmado, y el almacenamiento lo limita a 5 GB.
fileSize tiene que ser exacto, porque va firmado dentro de las URLs de subida: un PUT cuyo body tenga otro tamaño se rechaza. Un archivo que supera el límite se rechaza con 400 y "code": "FILE_TOO_LARGE" antes de crear el job; la respuesta incluye maxBytes, el límite en bytes. Si fileSize no es un número entero de bytes, recibís "code": "INVALID_FILE_SIZE". Un archivo que no puede ser una grabación se rechaza con 422 y "code": "NOT_A_MEDIA_FILE", también antes de crear el job: un archivo de metadatos de macOS (un label o un fileName opcional que empieza con ._; el archivo real se llama igual pero sin ._) o un fileSize de menos de 32 KB. La respuesta nombra el archivo en fileName, dice por qué en reason (macos_metadata o too_small) e incluye su sourceIndex.
Respuesta:
{
"jobId": "uuid",
"uploads": {
"source-uuid-1": {
"method": "multipart",
"uploadId": "...",
"key": "sources/uuid/source-uuid-1.mp4",
"partSize": 52428800,
"partCount": 41,
"urls": ["https://presigned-part-1-url...", "https://presigned-part-2-url...", "..."]
},
"source-uuid-3": {
"method": "put",
"url": "https://presigned-upload-url..."
}
},
"audioUploads": { "...": "..." }
}
uploads está indexado por los IDs de fuente que asigna WizCut, en el mismo orden que tu array sources. Podés ignorar audioUploads: lo usan las apps de WizCut, que suben una pista de audio extraída antes que el video.
Reintentar sin riesgo con Idempotency-Key
Si un request da timeout o se corta la conexión, no hay forma de saber si el job se creó. Si reintentás a ciegas, podés terminar con dos jobs. Para que los reintentos sean seguros, mandá un header Idempotency-Key con un valor que elijas para este job, por ejemplo un UUID:
curl -s -X POST https://wizcut.com/api/jobs \
-H "Authorization: Bearer wc_live_your_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b0d7c1e-8a3f-4f8e-9c51-2f0e6d9b7a14" \
-d '{ "sources": [...] }'
Es opcional, y los requests sin él funcionan igual que antes. Lo recomendamos para agentes y para cualquier cosa que reintente por su cuenta.
- Misma key, mismo body: recibís el job que creó el primer request, con el mismo
jobIdy, en las subidas multipart, el mismouploadId,key,partSizeypartCount, y con todas las URLs de subida firmadas de nuevo. La respuesta traeIdempotent-Replayed: true. No se crea un segundo job. - Misma key, otro body:
422con"code": "IDEMPOTENCY_KEY_MISMATCH". Usá una key nueva para un request distinto. Los bodies se comparan como JSON ya parseado, así que no importan ni el orden de las claves ni los espacios. - El primer request todavía está corriendo:
409con"code": "IDEMPOTENCY_IN_PROGRESS". Esperá un segundo y reintentá. - El job se eliminó después:
409con"code": "IDEMPOTENCY_KEY_REUSED". Usá una key nueva.
Las keys tienen entre 1 y 255 caracteres ASCII imprimibles (cualquier otra cosa recibe 400 con "code": "INVALID_IDEMPOTENCY_KEY"), pertenecen a tu cuenta y se recuerdan durante 24 horas. Un request que se rechaza antes de crear el job, ya sea por un error de validación o porque se te acabaron los minutos, no gasta su key, así que podés corregirlo y reintentar con la misma.
Subir archivos
Las URLs prefirmadas no necesitan header de autenticación: ya traen la autenticación incorporada.
Subí exactamente los bytes que declaraste. Los clientes HTTP calculan Content-Length a partir del body que mandan, así que no hace falta que lo configures vos.
"method": "put": hacé PUT del archivo completo a url dentro de la próxima hora:
curl -X PUT -T mic-mix.wav "https://presigned-upload-url..."
"method": "multipart": partí el archivo en fragmentos de partSize bytes (el último puede ser más corto) y hacé PUT del fragmento n a la URL de la parte n. Cada URL de parte solo acepta el tamaño exacto de esa parte, y hay exactamente partCount partes: si pedís un número de parte más alto, recibís un 400:
-
urlstrae las URLs de las primeras partes (urls[0]es la parte 1). Pedí más a medida que avanzás, hasta 16 por request:POST /api/jobs/{jobId}/sources/{sourceId}/parts{ "uploadId": "...", "partNumbers": [5, 6, 7, 8] }La respuesta mapea números de parte a URLs:
{ "urls": { "5": "https://...", "6": "https://..." } }. Las URLs de cada parte son válidas por dos horas, así que pedilas poco antes de usarlas. -
Una vez subidas todas las partes, cerrá la subida:
POST /api/uploads/complete{ "key": "sources/uuid/source-uuid-1.mp4", "uploadId": "..." }
Para abandonar una subida, mandá el mismo body a POST /api/uploads/abort.
WizCut verifica el tamaño real de cada archivo una vez subido: al completar una subida multipart y de nuevo al iniciar el procesamiento. Un archivo que supera el límite se elimina y el request recibe un 400 con "code": "FILE_TOO_LARGE"; un archivo bastante más chico o más grande que su fileSize declarado recibe "code": "FILE_SIZE_MISMATCH". Volvé a subirlo a la misma fuente.
Importar archivos desde un link
Si las grabaciones ya están online (en Google Drive, Dropbox u OneDrive, en el link de exportación de una plataforma de grabación, o adjuntas a un chat con un asistente de IA), podés pasarle el link a WizCut en vez de subir los bytes. WizCut descarga el archivo en segundo plano.
Creá el job con "sources": [] (o con los archivos que sí subas) y después sumá un archivo por llamada:
POST /api/jobs/{jobId}/sources/from-url
{
"url": "https://drive.google.com/file/d/1AbC.../view?usp=sharing",
"label": "Camera 1",
"kind": "video"
}
| Campo | Tipo | Descripción |
|---|---|---|
url | string | Un link https:// a un único archivo de video o audio, de hasta 4096 caracteres. |
label | string | Un nombre para el archivo, como "Camera 1" o "Host mic", de hasta 80 caracteres. |
kind | string | Opcional: "video" o "audio". Si lo omitís, WizCut lo decide según el archivo. Un archivo sin video es siempre una fuente de audio. |
Respuesta (202 Accepted):
{ "sourceId": "uuid", "status": "importing" }
La llamada devuelve enseguida. Mandá un header Idempotency-Key, igual que al crear un job, para que un reintento no importe el archivo dos veces: la misma key y el mismo body devuelven el mismo sourceId, con Idempotent-Replayed: true.
Qué links sirven:
- Links de descarga directa al archivo en sí, incluidos los links firmados de servicios de almacenamiento y el link de exportación de una plataforma de grabación que apunta al archivo.
- Links para compartir de Google Drive, Dropbox, OneDrive y SharePoint. Compartilos con “cualquier persona con el link”; WizCut los convierte en descargas por su cuenta, incluido el paso de “no se puede analizar este archivo en busca de virus” que Drive pone en los archivos grandes.
- No sirven: páginas web, carpetas, ni páginas de YouTube, Vimeo, Riverside o Zoom. WizCut no lee páginas para encontrar un video adentro. Usá el link de descarga de la plataforma, o subí el archivo.
Los formatos son los mismos que en las subidas (MP4, MOV, M4A, WebM, MKV, WAV, MP3 y AAC), y WizCut mira el contenido del archivo, no su nombre. También rige el límite de 100 GB por archivo.
Cómo seguir la importación. La fuente cuenta como “subiéndose” hasta que termina la importación, así que mientras tanto iniciar el procesamiento responde 409 con "code": "SOURCES_PENDING". El resumen de estado lista cada archivo bajo uploads:
{
"uploads": {
"allUploaded": false,
"files": [
{
"sourceId": "uuid",
"label": "Camera 1",
"kind": "video",
"state": "importing",
"progressPercent": 42,
"import": {
"status": "importing",
"host": "drive.google.com",
"bytes": 1803886592,
"totalBytes": 4294967296,
"error": null
}
}
]
}
}
state pasa de importing a imported, o a import_failed con import.error que explica por qué. WizCut guarda solo el host del link, nunca el link en sí.
Cuando falla una importación, el job sigue su curso. Eliminá el archivo y sumá en su lugar un link que funcione o una subida:
DELETE /api/jobs/{jobId}/sources/{sourceId}
Si el job tiene una callbackUrl, WizCut además manda un webhook source_import_failed. Los motivos (import.error.code):
| Code | Significado |
|---|---|
URL_NOT_ALLOWED | No es un link https:// público: es una dirección privada o local, un puerto no estándar, o tiene usuario y contraseña. |
URL_NOT_REACHABLE | No se pudo conectar con el servidor, o respondió con un error como 404. |
NOT_A_FILE | El link abre una página web o una carpeta, no un único archivo. |
LOGIN_REQUIRED | El link pide iniciar sesión. Compartilo con “cualquier persona con el link”. |
FILE_TOO_LARGE | Supera el límite de 100 GB por archivo. |
UNSUPPORTED_MEDIA_FORMAT | No es un formato de video o audio compatible, o está dañado. |
IMPORT_TIMEOUT | La descarga se trabó o tardó demasiado. |
IMPORT_FAILED | Algo falló de nuestro lado. Probá de nuevo. |
Rechazados al instante (no arranca ninguna importación): 400 con URL_NOT_ALLOWED o NOT_A_FILE para los links que WizCut sabe que están mal sin necesidad de abrirlos (http://, YouTube); 409 con INVALID_STATUS una vez que arrancó el procesamiento, o JOB_FULL con 12 archivos; 429 con TOO_MANY_IMPORTS cuando ya hay 6 importaciones corriendo en el job, o IMPORT_RATE_LIMITED después de 20 importaciones en una hora, los dos con un header Retry-After; 503 con IMPORT_UNAVAILABLE si la importación no está disponible en este momento.
¿Usás n8n, Make o Zapier? Es el camino más fácil: sin manejo de archivos y sin subidas multipart. Creá el job con un nodo HTTP Request (
"sources": []), sumá cada archivo con otro nodo HTTP Request que apunte a su link de Drive o Dropbox, y pasá unIdempotency-Keyfijo por archivo (por ejemplo, el ID del archivo en tu drive) para que un nodo reintentado no importe dos veces. Después esperá: consultáGET /api/jobs/{jobId}?view=summarycada minuto hasta queuploads.allUploadedseatrue, o reaccioná al webhooksource_import_failed, e iniciá el procesamiento.
Iniciar el procesamiento
POST /api/jobs/{jobId}/process
Llamá a esto una vez que subiste todos los archivos. Arranca el pipeline: sincronización de audio, detección de hablantes, render de proxy, mapeo de cámaras y generación de cortes. El request devuelve inmediatamente y el procesamiento ocurre de forma asincrónica.
Body opcional:
{ "diarizeSourceIds": ["source-uuid-3"] }
diarizeSourceIds elige qué fuentes escucha WizCut para la detección de hablantes. Son tu audio de las voces: el sonido del episodio también parte de ellas (mirá la mezcla de audio más abajo). Si lo omitís, WizCut usa tus fuentes de audio, o la primera fuente si no hay ninguna. Elegí las fuentes con el audio más limpio de todos los que hablan: una cámara con el micrófono silenciado o lejos puede dejarte con un job sin cortes.
También podés mandar silence acá, con el mismo formato que al crear el job, por ejemplo cuando la opción de pausas se elige después de crearlo. Si lo omitís, el job conserva lo que tenía al crearse. Con title funciona igual.
Respuesta:
{ "jobId": "uuid", "status": "syncing" }
Listar jobs
GET /api/jobs
Devuelve { "jobs": [...] } con tus 50 jobs más recientes, del más nuevo al más viejo. Cada uno trae id, title, status, thumbnails, created_at y updated_at.
thumbnails trae una imagen fija chiquita en JPEG (320 px de ancho) por cámara, en el orden de las cámaras, como { source_id, url }. Es [] hasta que estén listas las vistas previas de las cámaras, unos minutos después de que arranca el procesamiento. Las URL están firmadas por 6 horas y cambian en cada pedido, así que si guardás las imágenes en caché, hacelo por source_id. Si no se pudo crear la imagen de una cámara, su URL devuelve 404: mostrá un marcador en su lugar.
Ver el estado del job
GET /api/jobs/{jobId}
Respuesta:
{
"job": {
"id": "uuid",
"status": "complete",
"sources": [...],
"tracks": [...],
"turns": [...],
"cuts": [...],
"removed_ranges": [...],
"camera_map": {...},
"output_url": "https://presigned-download-url...",
"error_message": null
},
"sourceUrls": { "source-uuid-1": "https://..." },
"audioUrl": "https://...",
"downloadUrl": "https://wizcut.com/api/jobs/uuid/output",
"shareUrl": "https://wizcut.com/s/PyuMHl16Tpuhwg1Ob4qbEA1BQblecdp8-ayE20sNcSdQ"
}
El job en sí queda anidado bajo job. Las URLs firmadas de la respuesta (output_url, sourceUrls, audioUrl) se firman de nuevo en cada request, así que volvé a pedir el job en vez de guardarlas. downloadUrl y shareUrl son los links que sí podés guardar, ver Links para compartir y descargar.
camera_map es la propuesta de WizCut sobre quién está en cuál cámara, ver El mapa de cámaras. Es null hasta que se calcula.
Valores de estado:
| Estado | Significado |
|---|---|
created | Job creado, esperando las subidas |
uploading | Esperando que terminen de subirse los archivos (por ejemplo, después de reabrir un job fallido) |
syncing | Alineando audio entre las fuentes |
diarizing | Detectando hablantes |
mapping | Hablantes detectados. WizCut todavía está averiguando quién está en cuál cámara, o una persona (o tu agente) tiene que confirmarlo |
ready | Cortes generados, listo para revisión o render |
rendering | Render final en progreso |
complete | Render terminado, output_url disponible |
approved | Un humano aprobó el resultado |
failed | Algo salió mal, revisá error_message |
Resumen de estado
El job completo incluye cada turno de hablante y cada corte, y llega a pesar bastante. Si solo necesitás saber en qué punto está un job y qué hacer después, por ejemplo cuando consultás desde un agente o una automatización, pedí el resumen:
GET /api/jobs/{jobId}?view=summary
{
"id": "uuid",
"status": "mapping",
"progress": null,
"nextAction": {
"type": "map_speakers",
"url": "https://wizcut.com/jobs/uuid/edit?reviewToken=...",
"message": "Confirm who is on which camera at the review link, or submit the mapping with POST /api/jobs/uuid/tracks."
},
"outputUrl": null,
"downloadUrl": "https://wizcut.com/api/jobs/uuid/output",
"shareUrl": "https://wizcut.com/s/PyuMHl16Tpuhwg1Ob4qbEA1BQblecdp8-ayE20sNcSdQ",
"share": true,
"error": null,
"failedAtStatus": null,
"updatedAt": "2026-10-10T09:42:17.000Z",
"uploads": null,
"syncWarnings": [],
"syncRecheck": { "running": false, "failed": false, "available": false }
}
progress es el avance del render de 0 a 1 mientras el job está en rendering, y null en cualquier otro caso. error y failedAtStatus coinciden con los del webhook “failed”. Mientras el job recibe archivos (created, uploading), uploads lista cada archivo y en qué punto está: uploading, uploaded, o, para los archivos importados desde un link, importing, imported o import_failed con el motivo. Después queda en null. nextAction.message es una pista en inglés simple que podés pasarle tal cual a una persona o a un agente; basá tu lógica en nextAction.type:
type | Estado | Qué hacer | url |
|---|---|---|---|
upload_files | created, uploading; o failed cuando la subida se cortó | Subí los archivos y después iniciá el procesamiento. Si el job falló porque la subida se cortó (no llegó nada en 24 horas), quien subía los archivos puede seguir en la app de WizCut con los mismos archivos; lo que llegó se guarda una semana. | null |
wait | syncing, diarizing, rendering | Nada, WizCut está trabajando. Volvé a consultar más tarde o esperá el próximo webhook. | null |
map_speakers | mapping | Confirmá quién está en cuál cámara, en el editor o por la API. | Link de revisión, igual que la reviewUrl del webhook “mapping” |
review_or_render | ready | Revisá los cortes o arrancá el render. | Link de revisión |
download | complete, approved | Descargá el video. | URL de render recién firmada (también está en outputUrl) |
retry | failed | Llamá a POST /api/jobs/{jobId}/retry. | null |
contact_support | failed | Reintentar no va a servir, por ejemplo porque el archivo no tiene un formato compatible. Empezá un job nuevo o escribinos. | Link mailto: |
Cuando las fuentes elegidas para la detección de hablantes resultan estar en silencio, type es retry, pero un reintento común fallaría igual: el mensaje indica reintentar con una lista diarizeSourceIds que nombre una fuente con habla clara.
Archivos que WizCut no pudo alinear. WizCut alinea tus archivos por su sonido. Cuando el sonido de un archivo no coincide con el de ningún otro —muchas veces una exportación recortada o editada en vez de la grabación original—, WizCut lo ubica igual lo mejor que puede, pero la imagen y el sonido pueden quedar desfasados en ese archivo. El job no falla por eso: syncWarnings (en el resumen y en el GET /api/jobs/{jobId} completo) lista cada uno de esos archivos con su sourceId, label, kind y un reason: unverified (ubicado, pero nada lo confirmó), not_placed (empieza al principio), no_audio (no tiene sonido para alinear) o unreadable (no se pudo leer su sonido, así que no se revisó para nada). Un archivo que sí coincidió igual puede estar drifting: el aparato que lo grabó lleva un reloj apenas distinto, así que se va desfasando a lo largo del episodio, en driftMs (milisegundos, del principio al final). WizCut lo alinea en el medio, así que el principio y el final quedan desfasados más o menos la mitad cada uno; todavía no se corrige. Es [] cuando todos los archivos coinciden, y los mensajes de map_speakers, review_or_render y download también nombran los archivos. Si no está vacío, pedile a una persona que revise la sincronización antes de publicar.
Revisar la sincronización de nuevo. Para un archivo unreadable, POST /api/jobs/{jobId}/sync-recheck vuelve a leer el sonido de todos los archivos y los alinea de nuevo. Solo cambia la ubicación; el estado, los hablantes, la asignación y los cortes quedan igual. Responde 202 al instante, y syncRecheck (en el resumen y en el job completo) dice cómo va: running mientras trabaja (unos minutos con archivos grandes), failed cuando la última revisión no terminó, y available cuando una revisión puede ayudar ahora (hay un archivo unreadable, el job está en mapping, ready o complete, y no hay ninguna en curso). Consultá hasta que running sea false, después leé syncWarnings de nuevo y renderizá recién ahí, así el video usa la nueva ubicación. Rechazos: SYNC_RECHECK_NOT_NEEDED y SYNC_RECHECK_RUNNING (los dos 409). WizCut ya hace una revisión así por su cuenta justo después de sincronizar cuando un archivo es unreadable, así que en general solo ves que running pasa a false; llamalo vos cuando esa no ayudó (failed).
Renderizar con archivos sin alinear. Un archivo not_placed, no_audio o unreadable queda al principio del episodio, así que en el video no está en sincronía de labios. POST /api/jobs/{jobId}/render lo rechaza con 409: SYNC_RECHECK_RUNNING mientras una revisión todavía está alineando archivos (esperá unos minutos y probá de nuevo), FILES_NOT_SYNCED cuando ya nada los va a ubicar, con files que los lista. Mandá {"allowUnsyncedFiles": true} para renderizar igual, cuando una persona lo decidió; el video lleva entonces el aviso de render FILES_NOT_SYNCED. Los jobs creados con review: false esperan a que termine una revisión en curso antes de renderizar solos, y renderizan con el aviso si quedan archivos sin alinear.
Renders que no salieron como pediste. Pocas veces, un render termina pero no puede hacer todo lo que pediste. Casi siempre es uno de estos dos: PROGRAM_AUDIO_FAILED, cuando WizCut no pudo mezclar el audio del episodio desde tus archivos originales, así que el video usa la mezcla básica de la detección de hablantes, sin tu mezcla de audio ni el volumen que elegiste; y AV_DRIFT, cuando una parte del video salió bastante más larga o más corta de lo previsto, así que la imagen y el sonido pueden desfasarse. El job igual queda “complete”, y renderWarnings (en el resumen y en el GET /api/jobs/{jobId} completo) lista qué salió mal, cada uno con un code y un message que le podés mostrar a una persona. El mensaje de download también lo dice, y el webhook “complete” trae la misma lista en warnings. Es [] cuando el render salió como pediste. Renderizar de nuevo casi siempre lo arregla. Un tercero, FILES_NOT_SYNCED, significa que se renderizó con allowUnsyncedFiles mientras había archivos sin alinear; renderizá de nuevo cuando estén alineados.
Un job se puede reintentar 5 veces por hora. Si volvió a fallar después de esa cantidad de reintentos, POST /api/jobs/{jobId}/retry responde 429 con "code": "RETRY_LIMIT", y retryAfterSeconds (también en el header Retry-After) indica cuándo podés probar de nuevo. Otros rechazos también traen un code: INVALID_STATUS (409, el job no está en failed), NOT_RETRYABLE (422, falló en una etapa que un reintento no puede reiniciar) e INVALID_DIARIZE_SOURCES (400, diarizeSourceIds está vacío o nombra fuentes que el job no tiene).
Más adelante se pueden sumar tipos nuevos, así que tratá uno que no conozcas como wait. Los valores de view desconocidos devuelven el job completo.
Eliminar un job
DELETE /api/jobs/{jobId}
Elimina el job y todos sus archivos: uploads, proxies, el audio de detección de hablantes y el render. Funciona en cualquier estado; si una etapa todavía está corriendo, lo que genere se limpia cuando termina. Los minutos ya usados no se devuelven. Devuelve { "ok": true }, o 404 si el job no existe o no es tuyo.
Links para compartir y descargar
Un video terminado viene con tres links. Elegí el que mejor se ajuste a lo que querés hacer:
| Campo | Vigencia | Quién puede abrirlo | Usalo para |
|---|---|---|---|
outputUrl | Unas horas (una URL de archivo firmada) | Cualquiera que la tenga | Pasarle el archivo a otro servicio en el momento |
downloadUrl | Mientras exista el job | Vos: tu API key, o un navegador con sesión iniciada en WizCut | Links que guardás en tus propias herramientas |
shareUrl | Mientras exista el job y compartir esté activado | Cualquiera que tenga el link | Mandarle el video a otras personas, o tener un link estable para un tercero |
Los tres están en GET /api/jobs/{jobId} (completo y con ?view=summary) y en los webhooks “complete” y “approved”.
downloadUrl es https://wizcut.com/api/jobs/{jobId}/output. Cada request redirige (302) a una URL de archivo recién firmada, así que el link en sí nunca se vence. Mandá tu API key con el request; en un navegador funciona si tenés la sesión iniciada, y si no, primero te pide que inicies sesión. Agregá ?download=1 para guardar el archivo en vez de reproducirlo. Antes de que termine el render responde 409 con "code": "NOT_RENDERED".
curl -L -H "Authorization: Bearer $WIZCUT_API_KEY" \
-o episode.mp4 "https://wizcut.com/api/jobs/$JOB_ID/output"
shareUrl es una página no listada (https://wizcut.com/s/…) con un reproductor, el título y un botón de descarga. Nadie la encuentra sin el link y los buscadores no la indexan. Agregá /video.mp4 al link para obtener el archivo crudo. Antes de que termine el render, la página avisa que el episodio todavía no está listo, así que podés repartir el link con anticipación.
Compartir viene activado por defecto en los jobs nuevos. Desactivalo al crear el job con "share": false, o cambialo después:
PATCH /api/jobs/{jobId}
{ "share": false }
| Campo | Tipo | Descripción |
|---|---|---|
share | boolean | Activa o desactiva la página para compartir. Si la desactivás y la volvés a activar, vuelve el mismo link. |
resetShareLink | boolean | Con true, el link se reemplaza por uno nuevo. El link viejo deja de funcionar para siempre. Usalo cuando un link terminó donde no tenía que estar. |
Respuesta:
{ "jobId": "uuid", "share": true, "shareUrl": "https://wizcut.com/s/..." }
shareUrl es null mientras compartir está desactivado. También podés activar y desactivar compartir, copiar el link o generar uno nuevo desde el editor de WizCut, debajo del video terminado.
La página para compartir reproduce el video para cualquiera que tenga el link, así que tratalo como si fuera el video mismo. Si en el episodio aparecen otras personas, asegurate de que estén de acuerdo con que se comparta.
Transcripción y subtítulos
Los episodios con transcripción tienen "hasTranscript": true en GET /api/jobs/{jobId} (completo y con ?view=summary). Estamos sumando las transcripciones de a poco, así que la mayoría de los episodios todavía no tiene una.
GET /api/jobs/{jobId}/transcript?format=srt
| Parámetro | Valores | Descripción |
|---|---|---|
format | txt (por defecto), srt, vtt | Texto plano con un párrafo por hablante, con su nombre y el tiempo; o subtítulos en SRT o WebVTT. |
timeline | edit (por defecto), render | edit sigue la edición tal como está ahora. render coincide con el último video terminado, para subtítulos junto a un archivo que ya descargaste. |
download | 1 | Manda Content-Disposition: attachment, con el título del job como nombre. |
La respuesta es el archivo en sí, no JSON. Los tiempos siguen la edición: lo que se cortó del episodio no aparece, y todo lo que viene después se adelanta, así los subtítulos coinciden con el video. El header X-WizCut-Timeline dice qué edición siguen; dice edit si pediste render pero el video se hizo antes de que WizCut registrara lo que corta un render.
curl -H "Authorization: Bearer $WIZCUT_API_KEY" \
-o episodio.srt "https://wizcut.com/api/jobs/$JOB_ID/transcript?format=srt&timeline=render"
Errores: 404 con "code": "NO_TRANSCRIPT" si el episodio no tiene, 409 con "code": "INVALID_STATUS" antes de que esté cortado, y 409 con "code": "NOT_RENDERED" para timeline=render sin un video terminado.
Webhooks
Cuando proporcionás una callbackUrl, WizCut manda un POST con JSON cada vez que un job llega a uno de los estados de abajo. WizCut intenta cada entrega hasta tres veces y espera hasta 10 segundos a que tu endpoint responda.
Cada entrega va firmada, así que podés comprobar que de verdad viene de WizCut (mirá Verificar webhooks). Sondeá también como respaldo, por si se pierde alguna entrega.
Webhook “mapping” (una persona tiene que confirmar quién está en cuál cámara):
{
"jobId": "uuid",
"status": "mapping",
"reviewUrl": "https://wizcut.com/jobs/uuid/edit?reviewToken=...",
"speakers": ["SPEAKER_00", "SPEAKER_01"],
"cameraMap": {
"version": 1,
"speakers": ["SPEAKER_00", "SPEAKER_01"],
"unassignedSpeakers": ["SPEAKER_01"],
"droppedSpeakers": [],
"cameras": [
{ "sourceId": "source-uuid-1", "kind": "closeup", "confidence": "high", "speakers": ["SPEAKER_00"], "...": "..." },
{ "sourceId": "source-uuid-2", "kind": "closeup", "confidence": "low", "speakers": ["SPEAKER_01"], "...": "..." }
]
}
}
Mandá a alguien a la reviewUrl para mapear los hablantes a las fuentes de cámara y revisar los cortes, o mapealos por la API. Los links de revisión son válidos por 72 horas. speakers lista los hablantes detectados, empezando por el que más habla.
cameraMap es la propuesta de WizCut, con la misma forma que camera_map en el job, ver El mapa de cámaras. Se omite cuando todavía no hay propuesta.
Cuándo llega este webhook depende de autoMap:
"confident"o"always": el job espera en “mapping” sin mandar webhook mientras WizCut averigua las cámaras, lo que tarda unos minutos una vez que los proxies están listos. Después, o mapea las cámaras por su cuenta y el próximo webhook que recibís es “ready”, o manda “mapping” con la propuesta adjunta. Si WizCut no puede calcular una propuesta (por ejemplo, porque falló un proxy), “mapping” se manda sincameraMap, como máximo unos 30 minutos después de la detección de hablantes."off": “mapping” se manda enseguida después de la detección de hablantes, normalmente sincameraMap. La propuesta aparece enGET /api/jobs/{jobId}unos minutos más tarde.
Webhook “ready” (mapeo de hablantes enviado, ya sea por una persona, tu código o WizCut, y cortes generados):
{
"jobId": "uuid",
"status": "ready",
"reviewUrl": "https://wizcut.com/jobs/uuid/edit?reviewToken=..."
}
Webhook “complete” (render terminado):
{
"jobId": "uuid",
"status": "complete",
"outputUrl": "https://presigned-download-url...",
"downloadUrl": "https://wizcut.com/api/jobs/uuid/output",
"shareUrl": "https://wizcut.com/s/..."
}
Webhook “approved” (humano aprobó desde la UI de revisión):
{
"jobId": "uuid",
"status": "approved",
"outputUrl": "https://presigned-download-url...",
"downloadUrl": "https://wizcut.com/api/jobs/uuid/output",
"shareUrl": "https://wizcut.com/s/..."
}
Webhook “failed” (el job falló, en cualquier etapa):
{
"jobId": "uuid",
"status": "failed",
"error": "description of what went wrong",
"failedAtStatus": "syncing"
}
error trae el mismo mensaje que GET /api/jobs/{jobId} devuelve como error_message, y failedAtStatus indica en qué etapa falló, por ejemplo syncing, diarizing o rendering. En la mayoría de las fallas de sincronización, detección de hablantes y render, WizCut hace primero un reintento por su cuenta: si te llega este webhook, es que el reintento tampoco funcionó.
La excepción es un archivo que WizCut no puede leer. Antes de procesar, se verifica cada archivo subido, y todo lo que no sea un MP4, MOV, M4A, WebM, MKV, WAV, MP3 o AAC hace fallar el job al instante y sin reintento, diga lo que diga su extensión, porque el mismo archivo fallaría igual. Lo mismo pasa con un archivo dañado o cortado. El error nombra el archivo por su label, por ejemplo "Camera 2" isn't a supported video or audio format, or the file is damaged. (el mensaje llega en inglés). Subí un archivo compatible en un job nuevo.
Webhook “source_import_failed” (un archivo agregado desde un link no se pudo importar):
{
"jobId": "uuid",
"status": "source_import_failed",
"sourceId": "source-uuid-1",
"code": "LOGIN_REQUIRED",
"error": "That link needs a sign-in. Make the file viewable by anyone with the link, or use a direct download link."
}
Este webhook se refiere a un solo archivo, no al job: el job queda donde estaba. Eliminá la fuente con DELETE /api/jobs/{jobId}/sources/{sourceId} y sumá un link que funcione o una subida. code es uno de los códigos de falla de importación. Las importaciones exitosas no mandan webhook; mirá el resumen de estado.
El outputUrl de los webhooks “complete” y “approved” es válido por siete días después de terminar el render. GET /api/jobs/{jobId} siempre devuelve un output_url recién firmado. Para guardar un link, usá downloadUrl o shareUrl (shareUrl es null cuando compartir está desactivado), ver Links para compartir y descargar.
Verificar webhooks
WizCut firma cada webhook según la especificación Standard Webhooks, así que las librerías oficiales de standardwebhooks pueden verificarlos por vos. Cada entrega trae tres headers:
| Header | Valor |
|---|---|
webhook-id | Único por evento, como msg_2b6f0c…. Un reintento del mismo evento trae el mismo id, así que usalo para saltear duplicados. |
webhook-timestamp | Cuándo se mandó este intento, en segundos Unix. |
webhook-signature | Una o más firmas separadas por espacios, cada una con la forma v1,<base64>. |
Tu secreto de firma está en la página de configuración, bajo “Secreto de firma de webhooks”. Se ve como whsec_…, y un solo secreto cubre todos tus jobs.
Cada firma es el HMAC-SHA256 en base64 de {webhook-id}.{webhook-timestamp}.{body}, con los bytes de tu secreto como clave: la parte que sigue a whsec_, decodificada de base64. Para verificar una entrega:
- Calculá la firma sobre el body crudo del request, tal como llegó, no sobre un JSON que ya parseaste y volviste a serializar.
- Aceptá la entrega si alguna firma
v1del header coincide. Compará en tiempo constante. - Rechazá los timestamps que se alejen más de 5 minutos de tu reloj, para que nadie pueda reenviar más tarde una entrega capturada.
- Llevá registro de los
webhook-idque ya procesaste y salteá los repetidos.
Con el paquete standardwebhooks (Node):
import express from "express";
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.WIZCUT_WEBHOOK_SECRET); // "whsec_..."
const app = express();
// express.raw: la firma cubre el body exactamente como se envió
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
let event;
try {
// Verifica la firma y la ventana de 5 minutos del timestamp; tira un error si falla alguna
event = wh.verify(req.body.toString("utf8"), req.headers);
} catch {
return res.status(400).send("Invalid signature");
}
// event.jobId, event.status, ...
res.sendStatus(200);
});
Con crypto a secas (Node):
import crypto from "node:crypto";
function verifyWizCutWebhook(rawBody, headers, secret) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"];
if (!id || !timestamp || !signatures) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 5 * 60) return false;
const key = Buffer.from(secret.slice("whsec_".length), "base64");
const expected = crypto
.createHmac("sha256", key)
.update(`${id}.${timestamp}.${rawBody}`)
.digest();
return signatures.split(" ").some((entry) => {
const [version, signature] = entry.split(",");
if (version !== "v1" || !signature) return false;
const received = Buffer.from(signature, "base64");
return (
received.length === expected.length &&
crypto.timingSafeEqual(received, expected)
);
});
}
Python:
import base64
import hashlib
import hmac
import time
def verify_wizcut_webhook(raw_body: bytes, headers, secret: str) -> bool:
msg_id = headers.get("webhook-id")
timestamp = headers.get("webhook-timestamp")
signatures = headers.get("webhook-signature")
if not (msg_id and timestamp and signatures):
return False
if abs(time.time() - int(timestamp)) > 5 * 60:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = f"{msg_id}.{timestamp}.".encode() + raw_body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
for entry in signatures.split(" "):
version, _, signature = entry.partition(",")
if version == "v1" and hmac.compare_digest(signature, expected):
return True
return False
Renovar tu secreto. “Renovar secreto” en la página de configuración crea uno nuevo. El anterior sigue funcionando 24 horas: durante ese tiempo cada entrega trae dos firmas, la nueva primero, así que tu servidor verifica con el secreto que tenga. Cambiá al secreto nuevo dentro de esas 24 horas. Si volvés a renovar antes de que se cumplan, el más viejo deja de funcionar al instante: solo firman el actual y el inmediatamente anterior.
Si alguna vez WizCut no puede firmar una entrega, la manda igual, sin los headers de firma, en vez de descartarla. Aceptar o no una entrega sin firma queda en tus manos; si la rechazás, pedí el job con GET /api/jobs/{jobId} para ver qué cambió.
Mapeo de hablantes y revisión (human-in-the-loop)
Después de la detección de hablantes, el job pasa al estado “mapping”. Los hablantes detectados tienen que mapearse a las fuentes de cámara: la detección identifica cuándo habla alguien, pero no en qué cámara está.
WizCut intenta resolver eso por vos. La gente se mueve cuando habla: gesticula, asiente, se inclina. Por eso WizCut compara cuándo habla cada hablante con el movimiento de cada cámara y propone quién está en cuál. Cuánto decide por su cuenta depende de vos, con autoMap.
Cuando hace falta una persona, WizCut manda el webhook “mapping”. Incluye una reviewUrl, un link firmado al editor de WizCut. Mandá a alguien ahí. En el editor, la persona:
- Revisa qué hablante está en cuál cámara (las cámaras de las que WizCut está seguro ya vienen seleccionadas)
- Previsualiza y edita los cortes generados automáticamente
- Hace clic en “Render” cuando está listo (si
review: true, que es el valor por defecto) - Opcionalmente hace clic en “Approve” después de revisar el resultado renderizado
Con review: false, el render arranca automáticamente en cuanto se envía el mapeo de hablantes. La persona no tiene la opción de revisar los cortes antes del render.
Mapeo automático de cámaras
Configurá autoMap cuando crees el job:
| Modo | Qué hace WizCut | Elegilo cuando |
|---|---|---|
"off" | Nunca mapea las cámaras por su cuenta. Manda “mapping” enseguida después de la detección de hablantes; la propuesta aparece en el job unos minutos más tarde para que la use una persona o tu agente. | De todas formas una persona siempre revisa el mapeo. |
"confident" | Es el valor por defecto. Mapea las cámaras él mismo cuando está seguro de haber encontrado un primer plano de cada hablante, y pasa a “ready”. Si no, manda “mapping” con la propuesta adjunta. Un plano general o un two-shot se usa en la edición, pero nunca cuenta como la cámara propia de un hablante. | La mayoría de las integraciones. Solo sabés de WizCut cuando necesita ayuda. |
"always" | No espera a una persona. Usa las respuestas de las que está seguro, después las probables, y ubica a quien quede en las cámaras restantes según el tiempo de habla. Solo manda “mapping” si no puede calcular ninguna propuesta (por ejemplo, porque falló un proxy). | Pipelines totalmente desatendidos que prefieren una edición a ojo antes que un job frenado. |
“Seguro de cada hablante” significa: todos los que hablan al menos un minuto están en una cámara que WizCut respondió con confianza high. A las cámaras de las que no está seguro no les asigna hablantes, así que la edición no corta a ellas; si querés usarlas, corregilo en el editor.
Tené en cuenta que “confident” va a pedirle ayuda a una persona bastante seguido. Se frena con material donde el movimiento no sigue a un solo hablante: estudios de TV con señales conmutadas, eventos, cámaras en mano u operadas. Además necesita unos 20 minutos de conversación para estar seguro, así que los clips cortos suelen terminar en “mapping”. En nuestras pruebas hasta ahora, WizCut no puso a ningún hablante en la cámara equivocada cuando dijo estar seguro, pero la muestra todavía es chica.
Combinados con review: false, "confident" y "always" hacen que un job pueda renderizarse sin que nadie lo mire. Ese es el objetivo en pipelines desatendidos; si querés que una persona vea cada edición, mantené review: true.
El mapa de cámaras
La propuesta está en el job como camera_map (y en el webhook “mapping” como cameraMap). Es null hasta que se calcula, unos minutos después de que los proxies están listos. Este es el de un show de dos personas con un primer plano de cada una y un two-shot:
{
"version": 1,
"computedAt": "2026-10-01T09:42:17.000Z",
"speakers": ["SPEAKER_00", "SPEAKER_01"],
"unassignedSpeakers": [],
"droppedSpeakers": ["SPEAKER_02"],
"cameras": [
{
"sourceId": "source-uuid-1",
"kind": "closeup",
"confidence": "high",
"speakers": ["SPEAKER_00"],
"z": { "SPEAKER_00": 11.5, "SPEAKER_01": 0.9 },
"lagErrorS": { "SPEAKER_00": 0.1, "SPEAKER_01": 41.6 }
},
{
"sourceId": "source-uuid-2",
"kind": "closeup",
"confidence": "high",
"speakers": ["SPEAKER_01"],
"z": { "SPEAKER_01": 12.4, "SPEAKER_00": 1.3 },
"lagErrorS": { "SPEAKER_01": 0.2, "SPEAKER_00": 63.0 }
},
{
"sourceId": "source-uuid-3",
"kind": "twoshot",
"confidence": "high",
"speakers": ["SPEAKER_01", "SPEAKER_00"],
"positions": { "left": "SPEAKER_01", "right": "SPEAKER_00" },
"z": { "SPEAKER_00": 6.8, "SPEAKER_01": 5.2 },
"lagErrorS": { "SPEAKER_00": 0.3, "SPEAKER_01": 0.4 }
}
]
}
Por cámara:
| Campo | Descripción |
|---|---|
sourceId | Una de las fuentes de video del job. |
kind | Qué muestra la cámara: closeup (una persona), twoshot (dos personas una al lado de la otra), wide (tres personas), multi (varias personas, una después de otra, por lo general una cámara operada o conmutada) o unknown. |
confidence | high (WizCut está seguro), low (una respuesta probable, no segura) o none (sin respuesta). |
speakers | A quién muestra la cámara. Vacío cuando confidence es none. En two-shots y planos generales, de izquierda a derecha. |
positions | Solo para two-shots y planos generales: quién está a la left, al middle y a la right del encuadre. |
reason | Vale no_motion cuando no se pudo analizar la cámara en absoluto. |
z, lagErrorS | Números de diagnóstico por hablante: qué tan de cerca el movimiento de la cámara sigue el habla de esa persona, y a cuántos segundos quedó el mejor calce. Sirven para depurar, pero no te apoyes en ellos. |
Nivel superior:
| Campo | Descripción |
|---|---|
speakers | Los hablantes que WizCut evaluó: todos los que tienen al menos un minuto de habla. |
unassignedSpeakers | Hablantes evaluados que no están en ninguna cámara high. Si no está vacío, “confident” deja la decisión a una persona. |
droppedSpeakers | Hablantes con muy poca habla para evaluar, normalmente una etiqueta suelta o una interjección corta. WizCut no los ubica en ninguna cámara. |
Para aceptar la propuesta tal cual, convertí cada cámara en la que confiás en un track (su sourceId y sus speakers) y enviala.
Mapear hablantes por la API
Si ya sabés quién está sentado frente a cada cámara, o tu agente revisó la propuesta, mandá vos mismo el mapeo mientras el job está en estado “mapping”:
POST /api/jobs/{jobId}/tracks
{
"tracks": [
{ "sourceId": "source-uuid-1", "speakers": ["SPEAKER_00"] },
{ "sourceId": "source-uuid-2", "speakers": ["SPEAKER_01"] }
]
}
Usá los nombres de hablante del webhook “mapping” (o los turns de GET /api/jobs/{jobId}) y los IDs de tus fuentes de video. Una cámara puede mostrar a más de un hablante. WizCut genera entonces los cortes, pasa el job a “ready”, manda el webhook “ready” y, con review: false, arranca el render. La respuesta trae los nuevos cuts.
Cada sourceId tiene que ser una de las fuentes de video del job; cualquier otro recibe un 400 con "code": "UNKNOWN_SOURCE". Podés enviar el mapeo mientras WizCut todavía está averiguando las cámaras: gana el que llegue primero. Si el mapeo ya se envió, por ejemplo de forma automática, recibís un 409 con "code": "INVALID_STATUS".
Avanzado: corregir un mapeo cuando ya existen cortes. Una vez que el job está “ready” o “complete”, el mismo endpoint todavía puede cambiar el mapeo, pero ya no genera los cortes por vos: mandá los cuts corregidos junto con tracks (y opcionalmente removedRanges), o recibís un 400 con "code": "CUTS_REQUIRED". WizCut guarda las dos cosas juntas, así que un recut posterior usa el mapeo corregido. Si un tramo de un corte cae fuera del archivo de su cámara (porque arranca más tarde o termina antes), pasa a una cámara que tenga imagen en ese momento. Los cuts de la respuesta son los que se guardaron. No manda webhook ni arranca un render: disparalo si necesitás una salida nueva. El editor de WizCut hace todo esto por vos cuando alguien corrige un mapeo ahí.
Eliminación de silencios
WizCut puede acortar o eliminar automáticamente las pausas largas antes de generar los cortes. Esto pasa primero, así que el cambio de cámara se decide sobre la conversación ya ajustada: nunca vas a terminar con un corte a una cámara que pierde de inmediato la mayor parte de su tiempo en pantalla por una pausa eliminada.
Activalo con el campo silence al crear un job:
{ "silence": { "mode": "tighten" } }
Modos:
| Modo | Comportamiento |
|---|---|
off | Mantiene todas las pausas tal como se grabaron (valor por defecto cuando se omite silence). |
tighten | Acorta las pausas largas a un compás natural (~0.7s). Recomendado: mantiene la conversación sonando humana. |
remove | Corta las pausas largas casi por completo, dejando apenas el padding necesario para no cortar palabras. |
Ajustes finos opcionales (los valores por defecto funcionan bien para la mayoría de las grabaciones):
| Campo | Por defecto | Rango | Descripción |
|---|---|---|---|
minPauseSec | 1.5 | 0.3–10 | Solo se tocan las pausas más largas que este valor. |
keepPauseSec | 0.7 | 0–3 | El compás que queda en lugar de una pausa ajustada (solo en el modo tighten). |
paddingSec | 0.25 | 0–1 | Margen de seguridad que se mantiene alrededor del habla en cada rango eliminado. |
La detección es conservadora: una pausa solo se elimina cuando la detección de hablantes y un análisis de energía del audio coinciden en que es silencio, así que las risas y otros momentos que no son habla se conservan.
El objeto del job (GET /api/jobs/{jobId}) incluye removed_ranges, los tramos eliminados en tiempo de la fuente como { startMs, endMs }, junto con cuts. El render final se salta estos rangos; el editor de revisión los muestra como secciones rayadas que se pueden restaurar.
Cambialo después del procesamiento con el endpoint de recut:
POST /api/jobs/{jobId}/recut
{ "silence": { "mode": "remove", "minPauseSec": 1.0 } }
Recut regenera los cortes y los rangos eliminados a partir de los hablantes ya detectados, sin reprocesar, así que devuelve la respuesta de inmediato con los nuevos cuts, removedRanges y savedMs (cuánto más corto queda el resultado). Pasá { "mode": "off" } para desactivar la eliminación de silencios de nuevo; omití silence por completo para mantener la configuración guardada del job. Con el ritmo de corte pasa lo mismo: agregá "presetId" ("relaxed", "balanced" o "dynamic") para cambiarlo, o dejalo afuera para mantener el ritmo actual del job.
Nota sobre facturación: el uso se mide en minutos de entrada (el material que subís), así que la eliminación de silencios no cambia lo que cuesta un job, solo hace que el resultado quede más ajustado.
Avanzado: control programático de cortes
Para pipelines completamente automatizados que saltean la UI por completo, dejá que WizCut mapee las cámaras o mapeá los hablantes por la API, y después gestionás vos mismo los cortes y el render. Estos endpoints funcionan mientras el job está “ready” o “complete”:
Actualizar cortes:
PATCH /api/jobs/{jobId}/cuts
{
"cuts": [
{ "startMs": 0, "endMs": 5000, "sourceId": "source-uuid-1" },
{ "startMs": 5000, "endMs": 12000, "sourceId": "source-uuid-2" }
]
}
El mismo endpoint también acepta removedRanges (un array de { startMs, endMs }) para editar directamente los tramos de eliminación de silencios, por ejemplo para restaurar una pausa que la pasada automática eliminó. Podés mandar cuts, removedRanges, o los dos.
Cada corte tiene que nombrar una de las fuentes de video del job, o sea, una cámara. Un archivo de audio no tiene imagen: un corte sobre uno te devuelve un 422 con "code": "CUT_NOT_ON_CAMERA" y los ids en cuestión en sourceIds. Los archivos de audio igual van al sonido del episodio.
Disparar el render:
POST /api/jobs/{jobId}/render
Funciona desde “ready”, o desde “complete” para volver a renderizar después de editar los cortes. Devuelve { "jobId": "uuid", "status": "rendering" }, o un 409 con "code": "NO_CUTS" si el job no tiene cortes para renderizar, o "code": "NO_CAMERA" si solo quedan archivos de audio.
Aprobar el resultado:
POST /api/jobs/{jobId}/approve
Solo funciona una vez que el job está “complete”. Lo pasa a “approved” y manda el webhook “approved”.
Audio
WizCut mezcla el sonido a partir de tus archivos de audio originales, en calidad completa. Por defecto usa los archivos que elegiste para la detección de voces, tal como se grabaron. Hay dos cosas que cambian eso.
Volumen. Mandá loudness cuando arrancás el render:
POST /api/jobs/{jobId}/render
{ "loudness": "podcast" }
"original" deja el nivel como se grabó (por defecto), "podcast" lleva el episodio a −16 LUFS y "youtube" a −14 LUFS, en los dos casos con picos por debajo de −1 dBTP. Es una sola ganancia para todo el episodio, así que las partes bajas y las fuertes mantienen su equilibrio. Si no lo mandás, el job se queda con su última elección. Para fijar la elección sin renderizar, mandá { "loudness": "podcast" } a PUT /api/jobs/{jobId}/audio-mix (más abajo); el editor lo hace apenas elegís un nivel. El campo output_loudness del job te dice qué tan fuerte salió el último render.
La mezcla. Para leerla:
GET /api/jobs/{jobId}/audio-mix
{
"jobId": "uuid",
"audioMix": {
"balance": true,
"duck": { "enabled": true, "depthDb": -12, "fadeMs": 150, "padMs": 250 },
"tracks": {}
},
"tracks": [
{
"sourceId": "source-uuid-3",
"label": "guest-mic.wav",
"hasAudio": true,
"inMix": true,
"loudnessLufs": -26.9,
"balanceDb": 5.5,
"levelDb": 0,
"gainDb": 5.5,
"speaker": "SPEAKER_01",
"speakerChosen": false,
"centered": false,
"role": { "kind": "own", "speakers": ["SPEAKER_01"], "speechToNoiseDb": 31 }
}
],
"speakers": [{ "label": "SPEAKER_01", "name": "Maya" }],
"canBalance": true,
"canDuck": true,
"loudness": { "target": "original", "lastRender": null },
"usingDefault": false,
"defaultMix": { "sourceIds": ["source-uuid-3"], "duck": false, "reason": "picks" }
}
tracks muestra cada archivo como lo va a sonar el próximo render: si está en la mezcla y su gainDb final (balanceDb de “Equilibrar voces” más tu propio levelDb). speaker es de quién es el micrófono; WizCut lo saca de los niveles después de la detección de voces. centered es true cuando la izquierda y la derecha de un archivo tenían sonido distinto (un micrófono de un solo lado, o uno de cada lado): WizCut pasa los dos canales a los dos lados, así nadie queda sonando en un solo oído. Se marca solo durante el procesamiento.
role dice qué escucha el archivo, según sus niveles después de la detección de hablantes: own (el micrófono de una persona, 6 dB o más por encima de cualquier otra para ella), group (algunas personas a un nivel parecido) o everyone (un micrófono de ambiente o un plano general). Un speechToNoiseDb por debajo de 15 suena con ruido. Mientras no cambies nada (usingDefault), la mezcla es defaultMix, elegida según el rol: el micrófono de cada persona, uno por persona, entre todos tus archivos, bajado entre intervenciones (ownMics); si no, entre tus diarizeSourceIds, cuando cada pista elegida escucha a todos, la más limpia sola (cleanest); si no, tu selección tal cual (picks). Una pista que dejás afuera de tracks en un PUT vuelve a este predeterminado.
Para cambiarla:
PUT /api/jobs/{jobId}/audio-mix
{
"balance": true,
"duck": { "enabled": true },
"tracks": {
"source-uuid-3": { "gainDb": 2, "muted": false },
"source-uuid-4": { "gainDb": 0, "muted": false, "speaker": null }
}
}
Solo cambia lo que mandás. duck se combina campo por campo; tracks reemplaza toda la lista por pista, así que mandá cada pista que quieras ajustar.
| Campo | Qué hace |
|---|---|
balance | Equilibrar voces: sube los micrófonos más bajos al nivel del más fuerte (una ganancia por pista, como mucho +18 dB). |
duck.enabled | Baja cada micrófono mientras su persona no habla, para que las otras voces que capta no hagan sonar hueca la mezcla. Lo ajustás con depthDb (−40 a −3, por defecto −12), fadeMs (20–1000, por defecto 150) y padMs (0–1000, por defecto 250: cuánto antes de que hable se abre). |
tracks.<sourceId>.gainDb | Tu nivel para ese archivo, de −24 a +12 dB, encima de “Equilibrar voces”. |
tracks.<sourceId>.muted | true saca el archivo del sonido. |
tracks.<sourceId>.speaker | De quién es el micrófono: una etiqueta de voz, o null si no es de nadie (micrófono de ambiente o cámara, nunca se baja). Si no lo mandás, se usa lo que calcula WizCut. |
Funciona en cualquier estado. La mezcla se aplica al próximo render, así que volvé a llamar al endpoint de render para escucharla en el video. Un campo mal armado, o un speaker que no está en el episodio, devuelve 400 con "code": "INVALID_AUDIO_MIX".
Respuestas de error
Todos los endpoints devuelven errores en este formato:
{ "error": "Description of what went wrong" }
Algunos errores también traen un code legible por máquina:
| Code | HTTP | Significado |
|---|---|---|
TRACKS_ON_CREATE | 400 | POST /api/jobs recibió un mapeo de hablantes. Dejá afuera tracks y usá autoMap, o definí el mapeo más tarde. |
FILE_TOO_LARGE | 400 | Un archivo supera el límite de tamaño, ya sea por el fileSize declarado o por el tamaño real una vez subido. maxBytes indica el límite. |
INVALID_FILE_SIZE | 400 | fileSize no es un número entero de bytes. |
NOT_A_MEDIA_FILE | 422 | Un archivo no puede ser una grabación: un archivo de metadatos de macOS (su nombre empieza con ._) o un fileSize de menos de 32 KB. fileName y reason dicen cuál y por qué. Mandá directamente los archivos de cámara y de audio. |
FILE_SIZE_MISMATCH | 400 | El archivo subido es bastante más chico o más grande que su fileSize. Volvé a subirlo. |
UNKNOWN_SOURCE | 400 | Un track nombra un sourceId que no es una de las fuentes de video del job. |
CUTS_REQUIRED | 400 | Cambiar el mapeo cuando ya existen cortes requiere también los cuts actualizados. |
CUT_NOT_ON_CAMERA | 422 | Un corte nombra algo que no es una fuente de video del job, como un archivo de audio (sin imagen). sourceIds los lista. |
NOT_ENOUGH_VIDEOS | 400 | El job necesita al menos dos fuentes de video para procesarse. |
EMPTY_MAPPING | 400 | El mapeo no pone a ningún hablante en ninguna cámara. Asigná al menos un hablante. |
INVALID_IDEMPOTENCY_KEY | 400 | El header Idempotency-Key no tiene entre 1 y 255 caracteres ASCII imprimibles. |
URL_NOT_ALLOWED | 400 | Importar desde un link: no es un link https:// público. |
NOT_A_FILE | 400 | Importar desde un link: una página de YouTube o Vimeo, no un archivo. |
QUOTA_EXCEEDED | 403 | Usaste todos tus minutos. |
SOURCES_PENDING | 409 | Llamaste a /process mientras algunos archivos todavía se están subiendo o importando, o falló la importación de un archivo. pendingSourceIds los lista (importingSourceIds e importFailedSourceIds indican cuáles son importaciones): terminá esas subidas y eliminá los archivos cuya importación falló. |
INVALID_STATUS | 409 | El job no está en un estado que permita esto, por ejemplo, su mapeo ya se envió. |
NO_CUTS | 409 | No hay cortes para renderizar. |
NO_CAMERA | 409 | Al job no le queda ninguna fuente de video, solo archivos de audio, así que no hay imagen para renderizar. |
SOURCES_DELETED | 409 | Los archivos originales del job se borraron: los guardamos solo por un tiempo limitado, según el plan. Abrilo en el editor, subí los mismos archivos de nuevo y después renderizá. |
NOT_RENDERED | 409 | Todavía no hay un video terminado: downloadUrl funciona cuando el job está en complete o approved. |
IDEMPOTENCY_IN_PROGRESS | 409 | Todavía se está procesando un request con la misma Idempotency-Key. Reintentá en un momento. |
IDEMPOTENCY_KEY_REUSED | 409 | Se eliminó el job (o el archivo importado) que creó esta Idempotency-Key. Usá una key nueva. |
JOB_FULL | 409 | Importar desde un link: el job ya tiene 12 archivos. |
IDEMPOTENCY_KEY_MISMATCH | 422 | Esta Idempotency-Key ya se usó con un body distinto. |
TOO_MANY_IMPORTS | 429 | Importar desde un link: ya hay 6 importaciones corriendo en este job. Esperá lo que indica Retry-After. |
IMPORT_RATE_LIMITED | 429 | Importar desde un link: 20 importaciones en la última hora. Esperá lo que indica Retry-After, o subí los archivos. |
IMPORT_UNAVAILABLE | 503 | La importación desde un link no está disponible en este momento. Subí el archivo en su lugar. |
Códigos de estado HTTP más comunes:
| Código | Significado |
|---|---|
| 400 | Request inválido (ej. menos de dos fuentes de video al procesar) |
| 401 | API key faltante o inválida |
| 403 | Cuota superada, o la subida pertenece a otra cuenta |
| 404 | Job no encontrado o no te pertenece |
| 409 | Transición de estado inválida (ej. renderizar un job que no está listo), o un request con la misma Idempotency-Key que sigue corriendo |
| 422 | Una Idempotency-Key reutilizada con otro body |
| 429 | Demasiadas importaciones desde links a la vez, o en la última hora |
| 500 | Error del servidor |
| 502 | Un servicio de procesamiento rechazó el job o no pudo arrancar |
| 503 | Servicio no disponible |
Flujo completo
Acá está el camino feliz completo para un agente de IA o una automatización:
# 1. Crear un job con dos cámaras (archivos de hasta 5 GB cada uno,
# pasá fileSize para subidas multipart en archivos más grandes, hasta 100 GB)
JOB=$(curl -s -X POST https://wizcut.com/api/jobs \
-H "Authorization: Bearer wc_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"sources": [
{"label": "Camera 1", "kind": "video"},
{"label": "Camera 2", "kind": "video"}
],
"callbackUrl": "https://your-server.com/webhook"
}')
JOB_ID=$(echo $JOB | jq -r '.jobId')
# 2. Subir los videos a las URLs prefirmadas
curl -X PUT -T camera1.mp4 "$(echo $JOB | jq -r '.uploads | to_entries[0].value.url')"
curl -X PUT -T camera2.mp4 "$(echo $JOB | jq -r '.uploads | to_entries[1].value.url')"
# 3. Iniciar el procesamiento
curl -s -X POST "https://wizcut.com/api/jobs/$JOB_ID/process" \
-H "Authorization: Bearer wc_live_your_key"
# 4. Esperar el próximo webhook. Con el autoMap por defecto ("confident"):
# - { status: "ready", reviewUrl: "..." } → WizCut mapeó las cámaras solo
# - { status: "mapping", reviewUrl: "...", speakers: [...], cameraMap: {...} }
# → no estaba seguro. Mandar a una persona a la reviewUrl para confirmar las cámaras
# (o mandar el mapeo vos mismo a /api/jobs/$JOB_ID/tracks)
# 5. La persona revisa y edita los cortes → hace clic en Render en el editor
# Esperar el webhook: { status: "complete", outputUrl: "..." }
# 6. Descargar el video renderizado desde outputUrl
Totalmente desatendido (autoMap: "always", review: false):
# Igual que arriba, pero agregando "autoMap": "always" y "review": false en el paso 1
# WizCut mapea las cámaras solo, incluso cuando no está seguro,
# y arranca el render enseguida, sin ninguna persona de por medio
# Recibís: { status: "ready", ... } y después { status: "complete", outputUrl: "..." }
Integraciones
¿Preferís no escribir código? Podés manejar la API de WizCut desde plataformas de automatización sin necesidad de armar los requests a mano.
n8n
Mantenemos una integración oficial con n8n: el nodo de comunidad verificado @wizcut/n8n-nodes-wizcut. Instalalo desde Settings → Community Nodes en n8n (al estar verificado, también está disponible en n8n Cloud).
Incluye dos nodos:
- WizCut: acciones para Create Job, Get Job, Start Processing, Start Render y Approve.
- WizCut Trigger: un webhook trigger que arranca tu workflow cada vez que un job cambia de estado (mapping, ready, complete, approved).
Los nodos todavía no importan desde links: para los archivos que ya están en un drive en la nube, sumalos con un nodo HTTP Request como se explica en Importar archivos desde un link.
Apuntá la URL del trigger a la callbackUrl de tu job y tenés un pipeline completamente event-driven. Por ejemplo, podés avisar por Slack cuando WizCut necesita que alguien confirme quién está en cuál cámara, arrancar el render automáticamente cuando los cortes están listos, y publicar el link de descarga cuando el episodio está terminado. Los dos nodos también funcionan como tools para agentes de IA de n8n.
¿Querés arrancar con algo ya armado? Usá el template disponible: Notify and manage podcast edit status with WizCut and Slack.
Más plataformas
Las integraciones con Make.com y Zapier están en el roadmap. Si estás trabajando en otra plataforma o necesitás un template de workflow para tu setup específico, contactá a soporte de WizCut. Los pedidos de nuevas funciones son bienvenidos.