WizCut
Editor Web
← Back to docs

WizCut API

Envie, processe e renderize edições de podcasts multicam de forma programática com a WizCut API.

A WizCut API deixa você automatizar a edição de podcasts multicam. Envie os ângulos de câmera, deixa o WizCut detectar os participantes e gerar os cortes, opcionalmente revise tudo num editor hospedado, e receba o vídeo renderizado de volta via webhook.

Autenticação

Crie uma API key em wizcut.com/settings. Coloca ela em toda requisição:

Authorization: Bearer wc_live_your_key_here

As keys podem ser revogadas a qualquer momento pela página de configurações.

Criar um 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:

CampoTipoDescrição
sourcesarrayÂngulos de câmera ou arquivos de áudio. Cada um tem label, kind opcional ("video" ou "audio", padrão "video"), ext opcional (padrão "mp4").
tracksarrayMapeamento de participantes pra fontes. Passe speakers vazio [] pra deixar o WizCut atribuir automaticamente depois da análise.
callbackUrlstringURL pra receber notificações via webhook nas mudanças de status.
reviewbooleanPadrão true. Quando true, o job pausa no status “ready” pra revisão humana dos cortes antes de renderizar. Quando false, a renderização começa automaticamente assim que o mapeamento de participantes é enviado.

Resposta:

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

Fazer upload dos arquivos

Envie seus arquivos de vídeo via PUT pra cada URL presigned da resposta. Não precisa de header de autenticação — a URL já se autentica sozinha.

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

Iniciar o processamento

POST /api/jobs/{jobId}/process

Isso dispara o pipeline: sincronização de áudio, detecção de participantes, geração de cortes e render do proxy. A requisição retorna imediatamente — o processamento acontece de forma assíncrona.

Resposta:

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

Consultar o status do job

GET /api/jobs/{jobId}

Retorna o objeto completo do job, incluindo status atual, fontes, turnos e cortes.

Valores de status:

StatusSignificado
createdJob criado, aguardando uploads
syncingAlinhando o áudio entre as fontes
diarizingDetectando os participantes
mappingAguarda mapeamento de participantes pras fontes
readyCortes gerados, pronto pra revisão ou renderização
renderingRender final em andamento
completeRender concluído, output_url disponível
approvedOutput aprovado por uma pessoa
failedAlgo deu errado, veja error_message

Webhooks

Quando você fornece um callbackUrl, o WizCut envia requisições POST nas transições de status:

Webhook “mapping” (participantes detectados, precisa de mapeamento humano):

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

Manda uma pessoa pra reviewUrl pra mapear os participantes nas fontes de câmera e revisar os cortes.

Webhook “ready” (mapeamento de participantes completo, cortes gerados):

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

Webhook “complete” (render finalizado):

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

Webhook “approved” (output aprovado via interface de revisão):

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

Webhook “failed”:

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

Mapeamento de participantes e revisão (human-in-the-loop)

Depois da detecção de participantes, o job entra no status “mapping”. Uma pessoa precisa mapear os participantes detectados nas fontes de câmera — a diarization identifica quando alguém fala, mas não em qual câmera essa pessoa aparece.

O webhook “mapping” inclui uma reviewUrl — um link assinado pro editor do WizCut. Manda uma pessoa pra lá. No editor, ela vai:

  1. Mapear cada participante detectado pra uma fonte de câmera
  2. Visualizar e editar os cortes gerados automaticamente
  3. Clicar em “Render” quando estiver satisfeita (se review: true, que é o padrão)
  4. Opcionalmente clicar em “Approve” depois de revisar o output renderizado

Com review: false, a renderização começa automaticamente assim que o mapeamento de participantes é enviado — a pessoa não tem a chance de revisar os cortes antes de renderizar.

Avançado: controle programático dos cortes

Pra pipelines totalmente automatizados que pulam a interface, você pode gerenciar os cortes e a renderização via API:

Atualizar cortes:

PATCH /api/jobs/{jobId}/cuts

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

Acionar renderização:

POST /api/jobs/{jobId}/render

Aprovar output:

POST /api/jobs/{jobId}/approve

Respostas de erro

Todos os endpoints retornam erros neste formato:

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

Códigos HTTP comuns:

CódigoSignificado
401API key ausente ou inválida
403Cota excedida
404Job não encontrado ou não pertence a você
409Transição de status inválida (ex.: renderizar um job que ainda não tá pronto)
500Erro no servidor
503Serviço indisponível

Fluxo completo

O caminho feliz completo pra um agente de IA ou automação:

# 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

Com render automático após o mapeamento (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: "..." }
WizCut API – WizCut Docs