WizCut
Editor Web
← Back to docs

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 speakers y genera los cortes, opcionalmente los revisás en un editor online, y recibís el video renderizado por webhook.

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" },
    { "label": "Camera 2", "kind": "video", "ext": "mp4" }
  ],
  "tracks": [
    { "sourceId": "auto", "speakers": [] }
  ],
  "callbackUrl": "https://your-server.com/webhook",
  "review": true
}

Campos:

CampoTipoDescripción
sourcesarrayÁngulos de cámara o archivos de audio. Cada uno tiene label, kind opcional ("video" o "audio", por defecto "video"), y ext opcional (por defecto "mp4").
tracksarrayMapeo de speakers a fuentes. Pasá speakers vacíos [] para que WizCut los asigne automáticamente después del análisis.
callbackUrlstringURL que recibe las notificaciones webhook en los cambios de estado.
reviewbooleanPor 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 después de que se envía el mapeo de speakers.

Respuesta:

{
  "jobId": "uuid",
  "uploadUrls": {
    "source-uuid-1": "https://presigned-upload-url...",
    "source-uuid-2": "https://presigned-upload-url..."
  }
}

Subir archivos

Hacé PUT de los archivos de video a cada URL prefirmada que devuelve la respuesta. No necesitás header de autenticación — la URL ya trae la autenticación incorporada.

curl -X PUT -T camera1.mp4 "https://presigned-upload-url..."
curl -X PUT -T camera2.mp4 "https://presigned-upload-url..."

Iniciar el procesamiento

POST /api/jobs/{jobId}/process

Esto arranca el pipeline: sincronización de audio, detección de speakers, generación de cortes y render de proxy. El request devuelve inmediatamente — el procesamiento ocurre de forma asincrónica.

Respuesta:

{ "jobId": "uuid", "status": "syncing" }

Ver el estado del job

GET /api/jobs/{jobId}

Devuelve el objeto completo del job, incluyendo el estado actual, fuentes, turnos y cortes.

Valores de estado:

EstadoSignificado
createdJob creado, esperando las subidas
syncingAlineando audio entre las fuentes
diarizingDetectando speakers
mappingNecesita mapeo de speaker a fuente
readyCortes generados, listo para revisión o render
renderingRender final en progreso
completeRender terminado, output_url disponible
approvedUn humano aprobó el resultado
failedAlgo salió mal, revisá error_message

Webhooks

Cuando proporcionás una callbackUrl, WizCut envía requests POST en cada transición de estado:

Webhook “mapping” (speakers detectados, necesita mapeo humano):

{
  "jobId": "uuid",
  "status": "mapping",
  "reviewUrl": "https://wizcut.com/jobs/uuid/edit?reviewToken=..."
}

Mandá a alguien a la reviewUrl para mapear los speakers a las fuentes de cámara y revisar los cortes.

Webhook “ready” (mapeo de speakers completo, 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..."
}

Webhook “approved” (humano aprobó desde la UI de revisión):

{
  "jobId": "uuid",
  "status": "approved",
  "outputUrl": "https://presigned-download-url..."
}

Webhook “failed”:

{
  "jobId": "uuid",
  "status": "failed",
  "error": "description of what went wrong"
}

Mapeo de speakers y revisión (human-in-the-loop)

Después de la detección de speakers, el job pasa al estado “mapping”. Un humano tiene que mapear los speakers detectados a las fuentes de cámara — esta detección identifica cuándo habla alguien, pero no en qué cámara está.

El webhook “mapping” incluye una reviewUrl — un link firmado al editor de WizCut. Mandá a alguien ahí. En el editor, la persona:

  1. Mapea cada speaker detectado a una fuente de cámara
  2. Previsualiza y edita los cortes generados automáticamente
  3. Hace clic en “Render” cuando está listo (si review: true, que es el valor por defecto)
  4. 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 speakers — la persona no tiene la opción de revisar los cortes antes del render.

Avanzado: control programático de cortes

Para pipelines completamente automatizados que saltean la UI por completo, podés gestionar los cortes y el render por API:

Actualizar cortes:

PATCH /api/jobs/{jobId}/cuts

{
  "cuts": [
    { "startMs": 0, "endMs": 5000, "sourceId": "source-uuid-1" },
    { "startMs": 5000, "endMs": 12000, "sourceId": "source-uuid-2" }
  ]
}

Disparar el render:

POST /api/jobs/{jobId}/render

Aprobar el resultado:

POST /api/jobs/{jobId}/approve

Respuestas de error

Todos los endpoints devuelven errores en este formato:

{ "error": "Description of what went wrong" }

Códigos de estado HTTP más comunes:

CódigoSignificado
401API key faltante o inválida
403Cuota superada
404Job no encontrado o no te pertenece
409Transición de estado inválida (ej. renderizar un job que no está listo)
500Error del servidor
503Servicio no disponible

Flujo completo

Acá está el camino feliz completo para un agente de IA o una automatización:

# 1. Create a job with two cameras
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. Upload video files to the presigned URLs
curl -X PUT -T camera1.mp4 "$(echo $JOB | jq -r '.uploadUrls | to_entries[0].value')"
curl -X PUT -T camera2.mp4 "$(echo $JOB | jq -r '.uploadUrls | to_entries[1].value')"

# 3. Start processing
curl -s -X POST "https://wizcut.com/api/jobs/$JOB_ID/process" \
  -H "Authorization: Bearer wc_live_your_key"

# 4. Wait for webhook: { status: "mapping", reviewUrl: "..." }
#    Send a human to reviewUrl to map speakers and review cuts

# 5. Human maps speakers → edits cuts → clicks Render in the editor
#    Wait for webhook: { status: "complete", outputUrl: "..." }

# 6. Download the rendered video from outputUrl

Con render automático después del mapeo (review: false):

# Same as above, but add "review": false to step 1
# Human still maps speakers at the reviewUrl (step 4)
# But rendering starts automatically after mapping — no cut review step
# You'll get: { 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).

Apuntá la URL del trigger a la callbackUrl de tu job y tenés un pipeline completamente event-driven. Por ejemplo, podés notificar a Slack cuando se detectan los speakers, 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.

API de WizCut – WizCut Docs