Como usar o WizCut

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, descobrir quem tá em qual câmera e gerar os cortes, opcionalmente revise tudo num editor hospedado, e receba o vídeo renderizado de volta via webhook.

A especificação OpenAPI 3.1 completa fica em https://wizcut.com/openapi.json, pra geradores de código e plataformas de agentes. Prefere que o ChatGPT, o Claude ou o seu próprio agente rodem as edições por você? Dá uma olhada em Use o WizCut com ChatGPT, Claude e outros agentes de IA.

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", "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:

CampoTipoDescrição
sourcesarrayÂngulos de câmera ou arquivos de áudio, até 12 por job. Um job precisa de pelo menos duas fontes de vídeo antes de poder ser processado. Cada um tem label, kind opcional ("video" ou "audio", padrão "video"), ext opcional (mp4, mov, webm, mkv, wav, mp3, m4a ou aac; padrão "mp4" pra vídeo, "wav" pra áudio) e fileSize opcional: o tamanho exato do arquivo em bytes, até 100 GB (107374182400 bytes) por arquivo.
titlestringOpcional. Um nome pro job, tipo o título do episódio, com até 200 caracteres. Sem ele, o título é montado com os nomes das fontes e a data.
callbackUrlstringOpcional. URL pra receber notificações via webhook, veja Webhooks.
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, seja por uma pessoa, pelo seu código ou pelo próprio WizCut.
autoMapstringPadrão "confident". Define se o WizCut pode decidir sozinho quem tá em qual câmera: "off", "confident" ou "always". Veja Mapeamento automático de câmeras.
silenceobjectOpcional. Remoção automática de pausas, veja Remoção de silêncio. Omitido significa desligado.
sharebooleanPadrão true. Dá ao vídeo finalizado uma página de compartilhamento não listada, que qualquer pessoa com o link consegue abrir. Veja Links de compartilhamento e download.

Não dá pra passar o mapeamento de participantes (tracks) aqui: os IDs das fontes só existem depois que o job é criado, então ainda não tem a que associar um participante. Uma lista tracks com participantes é rejeitada com 400 e "code": "TRACKS_ON_CREATE". Use autoMap ou mapeie os participantes via API quando a detecção terminar.

Passe fileSize pra todo arquivo que você souber o tamanho. Arquivos acima de 100 MB aí ganham upload multipart: dá pra enviar as partes em paralelo, repetir só a parte que falhou, e é o único jeito de enviar arquivos maiores que 5 GB. Sem fileSize, todo arquivo recebe um PUT presigned único, que o storage limita a 5 GB.

O fileSize precisa ser exato, porque ele é assinado nas URLs de upload: um PUT com o corpo de outro tamanho é rejeitado. Um arquivo acima do limite é recusado com 400 e "code": "FILE_TOO_LARGE" antes de o job ser criado, e a resposta traz maxBytes, o limite em bytes. Um fileSize que não seja um número inteiro de bytes recebe "code": "INVALID_FILE_SIZE". Um arquivo que não pode ser uma gravação é recusado com 422 e "code": "NOT_A_MEDIA_FILE", também antes de o job ser criado: um arquivo de metadados do macOS (um label ou um fileName opcional que começa com ._; o arquivo de verdade tem o mesmo nome, sem o ._) ou um fileSize abaixo de 32 KB. A resposta traz o arquivo em fileName, o motivo em reason (macos_metadata ou too_small) e o sourceIndex dele.

Resposta:

{
  "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 é indexado pelos IDs de fonte que o WizCut atribuiu, na mesma ordem do seu array sources. Pode ignorar audioUploads: ele é usado pelos apps do WizCut, que enviam uma faixa de áudio extraída antes do vídeo.

Repetir requisições com segurança usando Idempotency-Key

Se uma requisição dá timeout ou a conexão cai, você não tem como saber se o job chegou a ser criado. Repetir às cegas pode acabar em dois jobs. Pra repetir com segurança, mande um header Idempotency-Key com um valor que você escolhe pra esse job. Um UUID funciona bem:

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": [...] }'

O header é opcional, e as requisições sem ele funcionam exatamente como antes. A gente recomenda usar em agentes e em qualquer coisa que repete requisições sozinha.

  • Mesma chave, mesmo corpo: você recebe o job que a primeira requisição criou, com o mesmo jobId e, nos uploads multipart, o mesmo uploadId, key, partSize e partCount, só que com todas as URLs de upload assinadas de novo. A resposta traz Idempotent-Replayed: true. Nenhum segundo job é criado.
  • Mesma chave, corpo diferente: 422 com "code": "IDEMPOTENCY_KEY_MISMATCH". Use uma chave nova pra uma requisição diferente. Os corpos são comparados como JSON já interpretado, então a ordem dos campos e os espaços não importam.
  • A primeira requisição ainda tá rodando: 409 com "code": "IDEMPOTENCY_IN_PROGRESS". Espere um segundo e tente de novo.
  • O job foi excluído depois: 409 com "code": "IDEMPOTENCY_KEY_REUSED". Use uma chave nova.

As chaves têm de 1 a 255 caracteres ASCII imprimíveis (qualquer outra coisa recebe 400 com "code": "INVALID_IDEMPOTENCY_KEY"), pertencem à sua conta e ficam guardadas por 24 horas. Uma requisição recusada antes de o job ser criado, por erro de validação ou porque seus minutos acabaram, não gasta a chave: dá pra corrigir e repetir com a mesma.

Fazer upload dos arquivos

Não precisa de header de autenticação pras URLs presigned, elas já se autenticam sozinhas.

Envie exatamente os bytes que você declarou. Os clientes HTTP preenchem o Content-Length a partir do corpo que mandam, então você não precisa se preocupar com ele.

"method": "put": envie o arquivo inteiro via PUT pra url dentro de uma hora.

curl -X PUT -T mic-mix.wav "https://presigned-upload-url..."

"method": "multipart": divida o arquivo em pedaços de partSize bytes (o último é menor) e envie o pedaço n via PUT pra URL da parte n. Cada URL de parte só aceita o tamanho exato daquela parte, e existem exatamente partCount partes: pedir um número de parte maior retorna 400.

  1. urls traz as URLs das primeiras partes (urls[0] é a parte 1). Peça mais conforme for avançando, até 16 por requisição:

    POST /api/jobs/{jobId}/sources/{sourceId}/parts
    
    { "uploadId": "...", "partNumbers": [5, 6, 7, 8] }
    

    A resposta mapeia números de parte pra URLs: { "urls": { "5": "https://...", "6": "https://..." } }. As URLs de parte valem por duas horas, então busque elas pouco antes de usar.

  2. Depois que todas as partes forem enviadas, finalize o upload:

    POST /api/uploads/complete
    
    { "key": "sources/uuid/source-uuid-1.mp4", "uploadId": "..." }
    

Pra desistir de um upload, mande o mesmo corpo pra POST /api/uploads/abort.

O WizCut confere o tamanho real de cada arquivo depois do upload, quando você finaliza um upload multipart e de novo quando inicia o processamento. Um arquivo acima do limite é apagado e a requisição recebe 400 com "code": "FILE_TOO_LARGE". Um arquivo bem menor ou bem maior que o fileSize declarado recebe "code": "FILE_SIZE_MISMATCH". Nos dois casos, envie o arquivo de novo pra mesma fonte.

Se as gravações já estão online (no Google Drive, no Dropbox ou no OneDrive, num link de exportação de uma plataforma de gravação, ou anexadas a uma conversa com um assistente de IA), dá pra passar o link pro WizCut em vez de subir os bytes. O WizCut baixa o arquivo em segundo plano.

Crie o job com "sources": [] (ou com os arquivos que você mesmo vai subir) e depois adicione um arquivo por chamada:

POST /api/jobs/{jobId}/sources/from-url
{
  "url": "https://drive.google.com/file/d/1AbC.../view?usp=sharing",
  "label": "Camera 1",
  "kind": "video"
}
CampoTipoDescrição
urlstringUm link https:// pra um único arquivo de vídeo ou áudio, com até 4096 caracteres.
labelstringUm nome pro arquivo, tipo "Camera 1" ou "Host mic", com até 80 caracteres.
kindstringOpcional: "video" ou "audio". Se você deixar de fora, o WizCut decide pelo arquivo. Um arquivo sem vídeo é sempre uma fonte de áudio.

Resposta (202 Accepted):

{ "sourceId": "uuid", "status": "importing" }

A chamada retorna na hora. Mande um header Idempotency-Key, como ao criar um job, pra uma nova tentativa não importar o arquivo duas vezes: a mesma chave com o mesmo corpo devolve o mesmo sourceId, com Idempotent-Replayed: true.

Quais links funcionam:

  • Links de download direto pro arquivo em si, incluindo links assinados de serviços de storage e o link de exportação de uma plataforma de gravação que aponta pro arquivo.
  • Links de compartilhamento do Google Drive, Dropbox, OneDrive e SharePoint. Compartilhe com “qualquer pessoa com o link”; o WizCut transforma eles em links de download sozinho, inclusive o aviso do Drive de que “não foi possível verificar vírus neste arquivo”, que aparece em arquivos grandes.
  • Não funcionam: páginas da web, pastas, ou páginas do YouTube, Vimeo, Riverside e Zoom. O WizCut não lê páginas pra achar um vídeo dentro delas. Use o link de download da plataforma ou suba o arquivo.

Os formatos são os mesmos do upload (MP4, MOV, M4A, WebM, MKV, WAV, MP3 e AAC), e o WizCut confere o conteúdo do arquivo, não o nome. O limite de 100 GB por arquivo também vale.

Acompanhando a importação. A fonte conta como “subindo” até a importação terminar, então, nesse meio-tempo, iniciar o processamento responde 409 com "code": "SOURCES_PENDING". O resumo do status lista todos os arquivos em 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
        }
      }
    ]
  }
}

O state vai de importing pra imported, ou pra import_failed, com import.error explicando o motivo. O WizCut guarda só o host do link, nunca o link em si.

Quando uma importação falha, o job segue em frente. Remova o arquivo e coloque no lugar um link que funcione ou um upload:

DELETE /api/jobs/{jobId}/sources/{sourceId}

Se o job tem um callbackUrl, o WizCut também manda um webhook source_import_failed. Os motivos (import.error.code):

CodeSignificado
URL_NOT_ALLOWEDNão é um link https:// público: um endereço privado ou local, uma porta fora do padrão, ou usuário e senha dentro do link.
URL_NOT_REACHABLENão deu pra chegar no servidor, ou ele respondeu com um erro, tipo 404.
NOT_A_FILEO link abre uma página da web ou uma pasta, não um arquivo só.
LOGIN_REQUIREDO link pede login. Compartilhe com “qualquer pessoa com o link”.
FILE_TOO_LARGEPassa do limite de 100 GB por arquivo.
UNSUPPORTED_MEDIA_FORMATNão é um formato de vídeo ou áudio compatível, ou o arquivo tá danificado.
IMPORT_TIMEOUTO download travou ou demorou demais.
IMPORT_FAILEDDeu algo errado do lado do WizCut. Tente de novo.

Recusado na hora (nenhuma importação começa): 400 com URL_NOT_ALLOWED ou NOT_A_FILE pra links que o WizCut sabe que estão errados sem precisar abrir (http://, YouTube); 409 com INVALID_STATUS depois que o processamento começou, ou JOB_FULL com 12 arquivos; 429 com TOO_MANY_IMPORTS quando já tem 6 importações rodando no job, ou IMPORT_RATE_LIMITED depois de 20 importações em uma hora, os dois com um header Retry-After; 503 com IMPORT_UNAVAILABLE se a importação não tá disponível no momento.

Tá usando n8n, Make ou Zapier? Esse é o caminho mais fácil: sem lidar com arquivo, sem upload multipart. Crie o job com um node HTTP Request ("sources": []), adicione cada arquivo com outro node HTTP Request apontando pro link dele no Drive ou no Dropbox, e passe uma Idempotency-Key fixa por arquivo (por exemplo, o ID do arquivo no seu drive), pra um node repetido não importar duas vezes. Depois espere: faça polling em GET /api/jobs/{jobId}?view=summary a cada minuto até uploads.allUploaded ser true, ou reaja ao webhook source_import_failed. Aí inicie o processamento.

Iniciar o processamento

POST /api/jobs/{jobId}/process

Chame isso assim que todos os arquivos forem enviados. Isso dispara o pipeline: sincronização de áudio, detecção de participantes, render do proxy, mapeamento de câmeras e geração de cortes. A requisição retorna imediatamente, o processamento acontece de forma assíncrona.

Corpo opcional:

{ "diarizeSourceIds": ["source-uuid-3"] }

diarizeSourceIds escolhe quais fontes o WizCut escuta pra detecção de participantes. Elas são o seu áudio das vozes: o som do episódio também parte delas (veja a mixagem de áudio mais abaixo). Se você não passar, o WizCut usa suas fontes audio, ou a primeira fonte se não tiver nenhuma. Escolha as fontes com o áudio mais limpo de todo mundo falando: uma câmera com microfone mudo ou distante faz o job sair sem nenhum corte.

Você também pode mandar silence aqui, no mesmo formato da criação do job, por exemplo quando a opção de pausas é escolhida depois de criar o job. Se não mandar, o job fica com o que foi definido na criação. Com title funciona do mesmo jeito.

Resposta:

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

Listar jobs

GET /api/jobs

Retorna { "jobs": [...] } com seus 50 jobs mais recentes, do mais novo pro mais antigo. Cada um traz id, title, status, thumbnails, created_at e updated_at.

thumbnails traz uma imagem estática pequena em JPEG (320 px de largura) por câmera, na ordem das câmeras, como { source_id, url }. Fica [] até as prévias das câmeras ficarem prontas, alguns minutos depois que o processamento começa. As URLs são assinadas por 6 horas e mudam a cada requisição, então se você guardar as imagens em cache, use o source_id como chave. Se a imagem de uma câmera não pôde ser criada, a URL dela retorna 404: mostra um espaço reservado no lugar.

Consultar o status do job

GET /api/jobs/{jobId}

Resposta:

{
  "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"
}

O job em si fica dentro de job. As URLs assinadas na resposta (output_url, sourceUrls, audioUrl) são assinadas na hora a cada requisição, então busque o job de novo em vez de guardar elas. downloadUrl e shareUrl são os links que você pode guardar, veja Links de compartilhamento e download.

camera_map é a proposta do WizCut de quem tá em qual câmera, veja O mapa de câmeras. Ele é null até ser calculado.

Valores de status:

StatusSignificado
createdJob criado, aguardando uploads
uploadingAguardando os arquivos terminarem de subir (ex.: depois que um job com falha é reaberto)
syncingAlinhando o áudio entre as fontes
diarizingDetectando os participantes
mappingParticipantes detectados. O WizCut ainda tá descobrindo quem tá em qual câmera, ou uma pessoa (ou o seu agente) precisa confirmar
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

Resumo do status

O job completo traz todos os turnos de fala e todos os cortes, e isso fica grande. Se você só quer saber em que pé o job tá e o que fazer em seguida, por exemplo ao fazer polling num agente ou numa automação, peça o resumo:

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 é o progresso do render, de 0 a 1, enquanto o job tá em rendering, e null nos outros casos. error e failedAtStatus são os mesmos do webhook “failed”. Enquanto o job ainda recebe arquivos (created, uploading), uploads lista cada arquivo e em que pé ele tá: uploading, uploaded ou, nos arquivos importados por link, importing, imported ou import_failed com o motivo. Depois disso, vira null. nextAction.message é uma dica curta, em inglês, que você pode repassar pra uma pessoa ou pra um agente; baseie a sua lógica no nextAction.type:

typeStatusO que fazerurl
upload_filescreated, uploading; ou failed quando o envio parouEnvie os arquivos e depois inicie o processamento. Se o job falhou porque o envio parou (nada chegou em 24 horas), quem estava enviando pode continuar no app do WizCut com os mesmos arquivos; o que chegou fica guardado por uma semana.null
waitsyncing, diarizing, renderingNada, o WizCut tá trabalhando. Consulte de novo mais tarde ou espere o próximo webhook.null
map_speakersmappingConfirme quem tá em qual câmera, no editor ou via API.Link de revisão, igual ao reviewUrl do webhook “mapping”
review_or_renderreadyRevise os cortes ou inicie o render.Link de revisão
downloadcomplete, approvedBaixe o vídeo.URL do render assinada na hora (também em outputUrl)
retryfailedChame POST /api/jobs/{jobId}/retry.null
contact_supportfailedTentar de novo não resolve, por exemplo quando o arquivo não é um formato compatível. Comece um job novo ou fale com a gente.Link mailto:

Quando as fontes escolhidas pra detecção de participantes estão mudas, o type é retry, mas tentar de novo do jeito normal falharia igual: a mensagem manda repetir com uma lista diarizeSourceIds que aponte uma fonte com fala clara.

Arquivos que o WizCut não conseguiu alinhar. O WizCut alinha seus arquivos pelo som. Quando o som de um arquivo não bate com o de nenhum outro — muitas vezes uma exportação cortada ou editada em vez da gravação original —, o WizCut coloca ele mesmo assim do melhor jeito possível, mas imagem e som podem ficar fora de sincronia nele. O job não falha por isso: syncWarnings (no resumo e no GET /api/jobs/{jobId} completo) lista cada um desses arquivos com sourceId, label, kind e um reason — unverified (colocado, mas nada confirmou), not_placed (começa no início), no_audio (sem som pra alinhar) ou unreadable (não deu pra ler o som dele, então ele nem foi conferido). Um arquivo que bateu ainda pode estar drifting: o aparelho que gravou ele tem um relógio um pouquinho diferente, então ele vai saindo de sincronia ao longo do episódio, em driftMs (milissegundos, do começo ao fim). O WizCut alinha ele no meio, então o começo e o fim ficam fora mais ou menos pela metade cada um; isso ainda não é corrigido. É [] quando todos os arquivos batem, e as mensagens de map_speakers, review_or_render e download também citam os arquivos. Se não estiver vazio, peça pra uma pessoa conferir a sincronia labial antes de publicar.

Conferir a sincronia de novo. Pra um arquivo unreadable, POST /api/jobs/{jobId}/sync-recheck lê de novo o som de todos os arquivos e alinha tudo outra vez. Só a posição muda; status, falantes, mapeamento e cortes continuam iguais. A resposta vem na hora com 202, e syncRecheck (no resumo e no job completo) mostra como está: running enquanto confere (alguns minutos com arquivos grandes), failed quando a última conferência não terminou, e available quando uma conferência pode ajudar agora (tem um arquivo unreadable, o job está em mapping, ready ou complete, e nenhuma está rodando). Consulte até running virar false, leia syncWarnings de novo e só renderize depois disso, pra o vídeo usar a nova posição. Recusas: SYNC_RECHECK_NOT_NEEDED e SYNC_RECHECK_RUNNING (as duas 409). O WizCut já faz uma conferência dessas sozinho logo depois da sincronia quando um arquivo é unreadable, então normalmente você só vê running virar false; chame você mesmo quando essa não ajudou (failed).

Renderizar com arquivos fora do lugar. Um arquivo not_placed, no_audio ou unreadable fica no começo do episódio, então no vídeo ele sai fora de sincronia labial. POST /api/jobs/{jobId}/render recusa com 409 nesse caso: SYNC_RECHECK_RUNNING enquanto uma conferência ainda está alinhando os arquivos (espere uns minutos e tente de novo), FILES_NOT_SYNCED quando nada mais vai posicionar eles, com files listando quais. Mande {"allowUnsyncedFiles": true} pra renderizar mesmo assim, depois que uma pessoa escolheu isso; o vídeo leva então o aviso de render FILES_NOT_SYNCED. Jobs criados com review: false esperam uma conferência em andamento antes de renderizar sozinhos, e renderizam com o aviso se ainda tiver arquivo fora do lugar.

Renders que não saíram como você pediu. Raramente, um render termina mas não consegue fazer tudo o que você pediu. Quase sempre é um destes dois: PROGRAM_AUDIO_FAILED, quando o WizCut não conseguiu mixar o áudio do episódio a partir dos seus arquivos originais, então o vídeo usa a mixagem básica da detecção de participantes, sem o seu mix de áudio e sem o volume que você escolheu; e AV_DRIFT, quando uma parte do vídeo saiu visivelmente mais longa ou mais curta que o planejado, então imagem e som podem sair de sincronia. O job continua “complete”, e renderWarnings (no resumo e no GET /api/jobs/{jobId} completo) lista o que deu errado, cada item com um code e uma message que você pode mostrar pra uma pessoa. A mensagem de download também avisa, e o webhook “complete” traz a mesma lista em warnings. Fica [] quando o render saiu como você pediu. Renderizar de novo quase sempre resolve. Um terceiro, FILES_NOT_SYNCED, quer dizer que ele foi renderizado com allowUnsyncedFiles enquanto alguns arquivos estavam fora do lugar; renderize de novo quando estiverem alinhados.

Dá pra tentar de novo um job 5 vezes por hora. Se ele falhou de novo depois dessas tentativas, o POST /api/jobs/{jobId}/retry responde 429 com "code": "RETRY_LIMIT", e o retryAfterSeconds (também no header Retry-After) diz quando você pode tentar outra vez. Outras recusas também trazem um code: INVALID_STATUS (409, o job não tá failed), NOT_RETRYABLE (422, ele falhou numa etapa que uma nova tentativa não consegue reiniciar) e INVALID_DIARIZE_SOURCES (400, o diarizeSourceIds tá vazio ou cita fontes que o job não tem).

Podem surgir tipos novos no futuro, então trate um tipo que você não conhece como wait. Valores de view desconhecidos devolvem o job completo.

Excluir um job

DELETE /api/jobs/{jobId}

Exclui o job e todos os arquivos dele: uploads, proxies, o áudio da detecção de falantes e o render. Funciona em qualquer status; se uma etapa ainda estiver rodando, o que ela gerar é limpo quando terminar. Minutos já usados não voltam. Retorna { "ok": true }, ou 404 se o job não existir ou não for seu.

Um vídeo finalizado vem com três links. Escolha o que combina com o que você vai fazer com ele:

CampoVale porQuem pode abrirUse pra
outputUrlAlgumas horas (uma URL assinada do arquivo)Qualquer pessoa com elaPassar o arquivo pra outro serviço na hora
downloadUrlEnquanto o job existirVocê: com a sua API key, ou num navegador logado no WizCutLinks que você guarda nas suas próprias ferramentas
shareUrlEnquanto o job existir e o compartilhamento estiver ligadoQualquer pessoa com o linkMandar o vídeo pra outras pessoas, ou ter um link estável pra terceiros

Os três vêm no GET /api/jobs/{jobId} (completo e com ?view=summary) e nos webhooks “complete” e “approved”.

O downloadUrl é https://wizcut.com/api/jobs/{jobId}/output. Cada requisição redireciona (302) pra uma URL do arquivo assinada na hora, então o link em si nunca fica velho. Mande a sua API key junto. No navegador ele funciona se você estiver logado, e senão pede pra você entrar primeiro. Adicione ?download=1 pra salvar o arquivo em vez de reproduzir. Antes de o render terminar, ele responde 409 com "code": "NOT_RENDERED".

curl -L -H "Authorization: Bearer $WIZCUT_API_KEY" \
  -o episode.mp4 "https://wizcut.com/api/jobs/$JOB_ID/output"

O shareUrl é uma página não listada (https://wizcut.com/s/…) com player, título e um botão de download. Ninguém acha ela sem o link, e os buscadores não indexam. Adicione /video.mp4 ao link pra pegar o arquivo puro. Antes de o render terminar, a página avisa que o episódio ainda não tá pronto, então dá pra mandar o link antes da hora.

O compartilhamento vem ligado por padrão nos jobs novos. Desligue na criação com "share": false, ou mude depois:

PATCH /api/jobs/{jobId}
{ "share": false }
CampoTipoDescrição
sharebooleanLiga ou desliga a página de compartilhamento. Desligando e ligando de novo, o link volta a ser o mesmo.
resetShareLinkbooleantrue troca o link por um novo. O link antigo para de funcionar de vez. Use quando um link foi parar onde não devia.

Resposta:

{ "jobId": "uuid", "share": true, "shareUrl": "https://wizcut.com/s/..." }

O shareUrl é null enquanto o compartilhamento tá desligado. Também dá pra ligar e desligar o compartilhamento, copiar o link ou gerar um novo no editor do WizCut, embaixo do vídeo finalizado.

A página de compartilhamento reproduz o vídeo pra qualquer pessoa que tenha o link, então trate ela como o próprio vídeo. Se o episódio mostra outras pessoas, confirme que elas topam que ele seja compartilhado.

Transcrição e legendas

Episódios com transcrição têm "hasTranscript": true em GET /api/jobs/{jobId} (completo e com ?view=summary). A gente tá liberando as transcrições aos poucos, então a maioria dos episódios ainda não tem uma.

GET /api/jobs/{jobId}/transcript?format=srt
ParâmetroValoresDescrição
formattxt (padrão), srt, vttTexto puro com um parágrafo por pessoa, com o nome e o tempo; ou legendas em SRT ou WebVTT.
timelineedit (padrão), renderedit segue a edição como ela está agora. render bate com o último vídeo pronto, pra legendas junto de um arquivo que você já baixou.
download1Manda Content-Disposition: attachment, com o título do job como nome.

A resposta é o próprio arquivo, não JSON. Os tempos seguem a edição: o que foi cortado do episódio fica de fora, e tudo depois adianta, pra legenda bater com o vídeo. O header X-WizCut-Timeline diz qual edição eles seguem; ele diz edit quando você pediu render mas o vídeo foi feito antes de o WizCut registrar o que um render corta.

curl -H "Authorization: Bearer $WIZCUT_API_KEY" \
  -o episodio.srt "https://wizcut.com/api/jobs/$JOB_ID/transcript?format=srt&timeline=render"

Erros: 404 com "code": "NO_TRANSCRIPT" quando o episódio não tem, 409 com "code": "INVALID_STATUS" antes de estar cortado, e 409 com "code": "NOT_RENDERED" pra timeline=render sem um vídeo pronto.

Capítulos, descrição e notas do episódio

Pros episódios com transcrição, o WizCut também escreve capítulos, um rascunho de descrição e notas do episódio. detailsStatus em GET /api/jobs/{jobId} (completo e com ?view=summary) mostra como estão: none, pending (sendo feitos, menos de um minuto), ready ou failed.

GET /api/jobs/{jobId}/details
ParâmetroValoresDescrição
timelineedit (padrão), renderOs tempos dos capítulos na edição atual, ou no último vídeo pronto.
formatjson (padrão), youtube, podcastyoutube é a lista de capítulos pra descrição do YouTube, em texto (0:00 Título por linha, pelo menos três capítulos). podcast são capítulos JSON do Podcasting 2.0.
{
  "status": "ready",
  "language": "pt",
  "chapters": [
    { "startMs": 0, "sourceMs": 0, "title": "Por que a Anna começou o programa", "summary": "A Anna conta pro Ben como o podcast começou.", "origin": "ai" },
    { "startMs": 412000, "sourceMs": 431250, "title": "Gravando na estrada", "summary": "", "origin": "user" }
  ],
  "description": "A Anna e o Ben falam de como o programa começou e de gravar viajando.",
  "showNotes": ["Como o podcast começou", "Um kit de gravação pra viagem"],
  "youtube": null,
  "warnings": ["TOO_FEW_FOR_YOUTUBE"],
  "revision": 1,
  "edited": true
}

Os capítulos seguem a edição: startMs é onde o capítulo começa no vídeo, sourceMs onde começa na gravação. Se um capítulo começa num trecho que você cortou, ele passa pra onde o episódio continua; se foi cortado inteiro, some até esse trecho voltar. Depois valem as regras do YouTube: o primeiro capítulo em 0:00 e cada um com pelo menos 10 segundos. Os participantes aparecem com os nomes que você deu no WizCut. warnings traz códigos: NEWER_VERSION, CHAPTERS_CUT_OUT, CHAPTERS_TOO_SHORT, TOO_FEW_FOR_YOUTUBE.

Pra mudar, manda tudo de volta com a revision que você leu:

PUT /api/jobs/{jobId}/details
{ "revision": 1, "chapters": [{ "sourceMs": 0, "title": "Por que a Anna começou o programa" }], "description": "…", "showNotes": ["…"] }

Os tempos dos capítulos são sourceMs, em ordem; títulos de 1 a 80 caracteres, no máximo 30 capítulos, uma descrição de até 2.000 caracteres e até 20 notas de 300. Um capítulo sem summary mantém o resumo. Os capítulos que a edição esconde no momento ficam guardados. O primeiro salvamento cria a sua própria versão, e é ela que o WizCut mostra daí em diante. POST /api/jobs/{jobId}/details/regenerate refaz tudo a partir da transcrição (202, depois status: "pending"); a sua versão fica até você descartar com DELETE /api/jobs/{jobId}/details?revision=….

Erros: 404 com "code": "NO_DETAILS" quando não tem nada no formato pedido, 409 com "code": "NOT_RENDERED" pra timeline=render sem vídeo pronto, ao salvar 400 com "code": "INVALID_DETAILS" e 409 com "code": "EDIT_CHANGED" (alguém salvou depois da sua revision), e 404 com "code": "NO_TRANSCRIPT" ao refazer um episódio sem transcrição.

Webhooks

Quando você fornece um callbackUrl, o WizCut manda uma requisição POST em JSON sempre que um job chega em um dos status abaixo. O WizCut tenta cada entrega até três vezes e espera até 10 segundos pela resposta do seu endpoint.

Todo webhook vem assinado, então dá pra conferir que ele veio mesmo do WizCut: veja Verificar webhooks. Faça polling como plano B também, caso alguma entrega se perca.

Webhook “mapping” (uma pessoa precisa confirmar quem tá em qual câmera):

{
  "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"], "...": "..." }
    ]
  }
}

Manda uma pessoa pra reviewUrl pra mapear os participantes nas fontes de câmera e revisar os cortes, ou mapeia eles via API. Os links de revisão valem por 72 horas. speakers lista os participantes detectados, do que mais fala pro que menos fala.

cameraMap é a proposta do WizCut, no mesmo formato do camera_map do job, veja O mapa de câmeras. Ele não vem quando ainda não tem proposta.

Quando esse webhook chega depende do autoMap:

  • "confident" ou "always": o job espera em “mapping” sem mandar webhook enquanto o WizCut descobre as câmeras, o que leva alguns minutos depois que os proxies ficam prontos. Aí ele ou mapeia as câmeras sozinho, e o próximo webhook que você recebe é o “ready”, ou manda “mapping” com a proposta anexada. Se o WizCut não conseguir calcular uma proposta (por exemplo, porque um proxy falhou), o “mapping” vai sem cameraMap, no máximo uns 30 minutos depois da detecção de participantes.
  • "off": o “mapping” é enviado logo depois da detecção de participantes, normalmente sem cameraMap. A proposta aparece no GET /api/jobs/{jobId} alguns minutos depois.

Webhook “ready” (mapeamento de participantes enviado, por uma pessoa, pelo seu código ou pelo WizCut, e 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...",
  "downloadUrl": "https://wizcut.com/api/jobs/uuid/output",
  "shareUrl": "https://wizcut.com/s/..."
}

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

{
  "jobId": "uuid",
  "status": "approved",
  "outputUrl": "https://presigned-download-url...",
  "downloadUrl": "https://wizcut.com/api/jobs/uuid/output",
  "shareUrl": "https://wizcut.com/s/..."
}

Webhook “failed” (o job falhou, em qualquer etapa):

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

error traz a mesma mensagem que o GET /api/jobs/{jobId} retorna em error_message, e failedAtStatus diz em qual etapa deu erro, tipo syncing, diarizing ou rendering. Na maioria das falhas de sincronização, detecção de participantes e render, o WizCut já tenta de novo uma vez sozinho: se esse webhook chegou, é porque a segunda tentativa também não deu certo.

A exceção é um arquivo que o WizCut não consegue ler. Todo upload é verificado antes de ser processado, e qualquer coisa que não seja um arquivo MP4, MOV, M4A, WebM, MKV, WAV, MP3 ou AAC, não importa o que a extensão diga, derruba o job na hora, sem tentar de novo, porque o mesmo arquivo falharia do mesmo jeito. Vale também pra arquivo danificado ou cortado no meio. O error cita o arquivo pelo label, por exemplo "Camera 2" isn't a supported video or audio format, or the file is damaged. (a API devolve essa mensagem em inglês). Envie um arquivo compatível num job novo.

Webhook “source_import_failed” (um arquivo adicionado por link não pôde ser importado):

{
  "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."
}

Esse webhook é sobre um arquivo só, não sobre o job: o job continua onde estava. Remova a fonte com DELETE /api/jobs/{jobId}/sources/{sourceId} e adicione um link que funcione ou um upload. O code é um dos códigos de falha da importação. Importações que dão certo não mandam webhook; confira o resumo do status.

O outputUrl nos webhooks “complete” e “approved” vale por sete dias depois que o render termina. O GET /api/jobs/{jobId} sempre retorna um output_url assinado na hora. Pra guardar um link, use downloadUrl ou shareUrl (o shareUrl é null quando o compartilhamento tá desligado), veja Links de compartilhamento e download.

Verificar webhooks

O WizCut assina todo webhook seguindo a especificação Standard Webhooks, então as bibliotecas oficiais standardwebhooks conseguem conferir a assinatura por você. Cada entrega traz três headers:

HeaderValor
webhook-idÚnico por evento, tipo msg_2b6f0c…. Uma nova tentativa do mesmo evento traz o mesmo id, então use ele pra ignorar entregas duplicadas.
webhook-timestampQuando essa tentativa foi enviada, em segundos Unix.
webhook-signatureUma ou mais assinaturas, separadas por espaço, cada uma no formato v1,<base64>.

Seu segredo de assinatura fica na página de configurações, em “Segredo de assinatura dos webhooks”. Ele tem o formato whsec_…, e um único segredo vale pra todos os seus jobs.

Cada assinatura é o HMAC-SHA256 em base64 de {webhook-id}.{webhook-timestamp}.{body}, usando como chave os bytes do seu segredo: a parte depois de whsec_, decodificada de base64. Pra conferir uma entrega:

  1. Calcule a assinatura em cima do corpo cru da requisição, exatamente como chegou, e não de um JSON que você interpretou e serializou de novo.
  2. Aceite a entrega se qualquer assinatura v1 do header bater. Compare em tempo constante.
  3. Rejeite timestamps a mais de 5 minutos de diferença do seu relógio, pra uma entrega capturada não poder ser reenviada depois.
  4. Guarde os webhook-ids que você já tratou e ignore os repetidos.

Com o pacote 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: a assinatura cobre o corpo exatamente como foi enviado
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    // Confere a assinatura e a janela de 5 minutos do timestamp; lança erro se uma das duas falhar
    event = wh.verify(req.body.toString("utf8"), req.headers);
  } catch {
    return res.status(400).send("Invalid signature");
  }
  // event.jobId, event.status, ...
  res.sendStatus(200);
});

Com crypto puro (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

Trocar o segredo. “Trocar segredo” na página de configurações cria um segredo novo. O antigo continua valendo por 24 horas: nesse período toda entrega traz duas assinaturas, a do segredo novo primeiro, então seu servidor confere com qualquer um dos dois que tiver. Passe pro segredo novo dentro dessas 24 horas. Se você trocar de novo antes de as 24 horas acabarem, o segredo mais antigo para de valer na hora: só o atual e o anterior a ele assinam.

Se o WizCut não conseguir assinar uma entrega, ele manda mesmo assim, sem os headers de assinatura, em vez de descartar. Aceitar ou não uma entrega sem assinatura fica por sua conta; se você rejeitar, busque o job com GET /api/jobs/{jobId} pra ver o que mudou.

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

Depois da detecção de participantes, o job entra no status “mapping”. Os participantes detectados precisam ser mapeados pras fontes de câmera: essa detecção identifica quando alguém fala, mas não em qual câmera essa pessoa aparece.

O WizCut tenta resolver isso por você. As pessoas se mexem quando falam: gesticulam, balançam a cabeça, se inclinam. Então o WizCut compara a fala de cada participante com o movimento de cada câmera e propõe quem tá em qual. O quanto ele decide sozinho é com você, via autoMap.

Quando precisa de uma pessoa, o WizCut manda o webhook “mapping”. Ele inclui uma reviewUrl, um link assinado pro editor do WizCut. Manda uma pessoa pra lá. No editor, ela vai:

  1. Conferir qual participante tá em qual câmera (as câmeras de que o WizCut tem certeza já vêm selecionadas)
  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.

Mapeamento automático de câmeras

Defina autoMap quando criar o job:

ModoO que o WizCut fazEscolha quando
"off"Nunca mapeia as câmeras sozinho. Manda “mapping” logo depois da detecção de participantes; a proposta aparece no job alguns minutos depois, pra uma pessoa ou o seu agente usar.Uma pessoa sempre revisa o mapeamento de qualquer jeito.
"confident"Padrão. Mapeia as câmeras sozinho quando tem certeza de que achou um close de cada participante e depois segue pra “ready”. Senão, manda “mapping” com a proposta anexada. Uma câmera wide ou de dois planos é usada na edição, mas nunca conta como a câmera própria de um participante.A maioria das integrações. Você só ouve falar do WizCut quando ele precisa de ajuda.
"always"Não espera por ninguém. Usa as respostas de que tem certeza, depois as prováveis, e coloca quem sobrar nas câmeras que restam por tempo de fala. Só manda “mapping” se não conseguir calcular nenhuma proposta (por exemplo, porque um proxy falhou).Pipelines totalmente sem supervisão, que preferem receber uma edição no chute a um job parado.

“Ter certeza de todo participante” quer dizer: todo mundo com pelo menos um minuto de fala tá numa câmera que o WizCut respondeu com confiança high. Câmeras de que ele não tem certeza ficam sem participantes, então a edição não corta pra elas. Se quiser que sejam usadas, ajuste isso no editor.

Conte com o “confident” chamar uma pessoa com certa frequência. Ele fica de pé atrás com material em que o movimento não acompanha um participante só: estúdios de TV com feeds alternados, eventos, câmeras na mão ou operadas. Ele também precisa de uns 20 minutos de conversa pra ter certeza, então clipes curtos normalmente acabam em “mapping”. Nos nossos testes até agora, o WizCut nunca colocou um participante na câmera errada quando disse que tinha certeza, mas a amostra ainda é pequena.

Combinados com review: false, "confident" e "always" significam que um job pode ser renderizado sem ninguém olhar. Esse é o objetivo em pipelines sem supervisão; se você quer que uma pessoa veja cada edição, mantenha review: true.

O mapa de câmeras

A proposta fica no job como camera_map (e no webhook “mapping” como cameraMap). Ela é null até ser calculada, o que leva alguns minutos depois que os proxies ficam prontos. Aqui vai um exemplo de um programa com duas pessoas, um close de cada uma e um plano aberto com as duas:

{
  "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âmera:

CampoDescrição
sourceIdUma das fontes de vídeo do job.
kindO que a câmera mostra: closeup (uma pessoa), twoshot (duas pessoas lado a lado), wide (três pessoas), multi (várias pessoas, uma de cada vez, geralmente uma câmera operada ou com feed alternado) ou unknown.
confidencehigh (o WizCut tem certeza), low (uma resposta provável, mas sem certeza) ou none (sem resposta).
speakersQuem a câmera mostra. Vazio quando confidence é none. Em dois planos e wides, da esquerda pra direita.
positionsSó em dois planos e wides: quem tá na left, no middle e na right do quadro.
reasonVem como no_motion quando não deu pra analisar a câmera de jeito nenhum.
z, lagErrorSNúmeros de diagnóstico por participante: o quanto o movimento da câmera acompanha a fala dessa pessoa, e quantos segundos de diferença deu o melhor encaixe. Úteis pra depurar, mas não pra construir em cima.

Nível superior:

CampoDescrição
speakersOs participantes que o WizCut avaliou: todo mundo com pelo menos um minuto de fala.
unassignedSpeakersParticipantes avaliados que não estão em nenhuma câmera high. Se não estiver vazio, o “confident” deixa a decisão pra uma pessoa.
droppedSpeakersParticipantes com fala curta demais pra avaliar, normalmente um rótulo perdido ou uma interjeição rápida. O WizCut não coloca eles numa câmera.

Pra aceitar a proposta do jeito que tá, transforme cada câmera em que você confia num track (o sourceId e os speakers dela) e envie.

Mapear participantes via API

Se você já sabe quem senta na frente de qual câmera, ou o seu agente já conferiu a proposta, envie o mapeamento você mesmo enquanto o job estiver no status “mapping”:

POST /api/jobs/{jobId}/tracks
{
  "tracks": [
    { "sourceId": "source-uuid-1", "speakers": ["SPEAKER_00"] },
    { "sourceId": "source-uuid-2", "speakers": ["SPEAKER_01"] }
  ]
}

Use os nomes de participante do webhook “mapping” (ou os turns do GET /api/jobs/{jobId}) e os IDs das suas fontes de vídeo. Uma câmera pode mostrar mais de um participante. Aí o WizCut gera os cortes, move o job pra “ready”, manda o webhook “ready” e, com review: false, começa o render. A resposta traz os novos cuts.

Todo sourceId precisa ser uma das fontes de vídeo do job; qualquer outro gera um 400 com "code": "UNKNOWN_SOURCE". Dá pra enviar enquanto o WizCut ainda tá descobrindo as câmeras: vale quem chegar primeiro. Se o mapeamento já foi enviado, por exemplo automaticamente, você recebe um 409 com "code": "INVALID_STATUS".

Avançado: corrigir um mapeamento depois que os cortes existem. Quando o job tá “ready” ou “complete”, o mesmo endpoint ainda consegue mudar o mapeamento, mas não gera mais os cortes por você: envie os cuts corrigidos junto com os tracks (e opcionalmente removedRanges), ou você recebe um 400 com "code": "CUTS_REQUIRED". O WizCut salva os dois juntos, então um recut posterior usa o mapeamento corrigido. Se um trecho de um corte cai fora do arquivo da câmera dele (porque ela começa depois ou para antes), ele passa pra uma câmera que tem imagem naquele momento. Os cuts da resposta são os que foram salvos. Não manda webhook nem inicia render: dispare um se precisar de um novo output. O editor do WizCut faz tudo isso por você quando alguém corrige um mapeamento lá.

Remoção de silêncio

O WizCut consegue encurtar ou remover pausas longas automaticamente antes de gerar os cortes. Isso acontece primeiro, então a troca de câmera é decidida em cima da conversa já apertada, você nunca tem um corte pra uma câmera que perde a maior parte do seu tempo de tela pra uma pausa removida logo em seguida.

Ative com o campo silence na criação do job:

{ "silence": { "mode": "tighten" } }

Modos:

ModoComportamento
offMantém todas as pausas como gravadas (padrão quando silence é omitido).
tightenEncurta pausas longas pra um ritmo natural (~0,7 s). Recomendado: mantém a conversa soando humana.
removeCorta as pausas longas quase por completo, deixando só o padding necessário pra não cortar palavras.

Ajustes finos opcionais (os padrões funcionam bem pra maioria das gravações):

CampoPadrãoFaixaDescrição
minPauseSec1.50.3–10Só pausas mais longas que isso são mexidas.
keepPauseSec0.70–3O ritmo deixado no lugar de uma pausa apertada (só no modo tighten).
paddingSec0.250–1Margem de segurança mantida em volta da fala em cada trecho removido.

A detecção é conservadora: uma pausa só é removida onde a detecção de falantes e uma análise de energia do áudio concordam que tá quieto, então risadas e outros momentos que não são fala sobrevivem.

O objeto do job (GET /api/jobs/{jobId}) inclui removed_ranges: os trechos removidos em tempo da fonte como { startMs, endMs }, junto com cuts. O render final pula esses trechos; o editor de revisão mostra eles como seções restauráveis com hachura.

Mude isso depois do processamento com o endpoint de recut:

POST /api/jobs/{jobId}/recut
{ "silence": { "mode": "remove", "minPauseSec": 1.0 } }

O recut regenera os cortes e os trechos removidos a partir dos participantes já detectados, sem reprocessar, então retorna na hora com os novos cuts, removedRanges e savedMs (quanto mais curto o resultado fica). Passe { "mode": "off" } pra desligar a remoção de silêncio de novo; omita silence inteiramente pra manter a configuração salva do job. Com o ritmo de corte é igual: inclua "presetId" ("relaxed", "balanced" ou "dynamic") pra mudar, ou deixe de fora pra manter o ritmo atual do job.

Nota sobre cobrança: o uso é medido em minutos de entrada (o material que você envia), então a remoção de silêncio não muda o custo do job, só deixa o resultado mais enxuto.

Avançado: controle programático dos cortes

Pra pipelines totalmente automatizados que pulam a interface, deixa o WizCut mapear as câmeras ou mapeia os participantes via API e depois gerencie os cortes e a renderização você mesmo. Esses endpoints funcionam enquanto o job está “ready” ou “complete”:

Atualizar cortes:

PATCH /api/jobs/{jobId}/cuts
{
  "cuts": [
    { "startMs": 0, "endMs": 5000, "sourceId": "source-uuid-1" },
    { "startMs": 5000, "endMs": 12000, "sourceId": "source-uuid-2" }
  ]
}

O mesmo endpoint também aceita removedRanges (array de { startMs, endMs }) pra editar diretamente os trechos de remoção de silêncio, por exemplo, pra restaurar uma pausa que a passada automática removeu. Você pode enviar cuts, removedRanges, ou os dois.

Cada corte tem que apontar pra uma das fontes de vídeo do job, ou seja, uma câmera. Arquivo de áudio não tem imagem: um corte nele volta um 422 com "code": "CUT_NOT_ON_CAMERA" e os ids em sourceIds. Os arquivos de áudio continuam indo pro som do episódio.

Acionar renderização:

POST /api/jobs/{jobId}/render

Funciona a partir de “ready”, ou de “complete” pra renderizar de novo depois de editar os cortes. Retorna { "jobId": "uuid", "status": "rendering" }, ou um 409 com "code": "NO_CUTS" se o job não tiver cortes pra renderizar, ou "code": "NO_CAMERA" se só sobraram arquivos de áudio.

Aprovar output:

POST /api/jobs/{jobId}/approve

Só funciona quando o job já está “complete”. Move ele pra “approved” e manda o webhook “approved”.

Áudio

O WizCut mixa o som a partir dos seus arquivos de áudio originais, em qualidade total. Por padrão ele usa os arquivos que você escolheu pra detecção de vozes, do jeito que foram gravados. Duas coisas mudam isso.

Volume. Mande loudness quando começar o render:

POST /api/jobs/{jobId}/render
{ "loudness": "podcast" }

"original" deixa o nível como foi gravado (o padrão), "podcast" leva o episódio a −16 LUFS e "youtube" a −14 LUFS, os dois com picos abaixo de −1 dBTP. É um ganho só pro episódio inteiro, então trechos baixos e altos mantêm o equilíbrio. Sem o campo, o job fica com a última escolha. Pra definir a escolha sem renderizar, manda { "loudness": "podcast" } pro PUT /api/jobs/{jobId}/audio-mix (mais abaixo); o editor faz isso assim que você escolhe um nível. O campo output_loudness do job diz o volume com que o último render saiu.

A mixagem. Pra ler:

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 mostra cada arquivo do jeito que o próximo render vai tocar: se está na mixagem e o gainDb final (balanceDb do “Equilibrar vozes” mais o seu próprio levelDb). speaker é de quem é o microfone; o WizCut descobre isso pelos níveis depois da detecção de vozes. centered é true quando a esquerda e a direita de um arquivo tinham som diferente (um microfone só de um lado, ou um de cada lado): o WizCut toca os dois canais dos dois lados, pra ninguém ficar num ouvido só. Isso é marcado sozinho no processamento.

role diz o que o arquivo ouve, a partir dos níveis dele depois da detecção de participantes: own (o microfone de uma pessoa, 6 dB ou mais acima de qualquer outra pra ela), group (algumas pessoas num nível parecido) ou everyone (um microfone de ambiente ou um plano aberto). Um speechToNoiseDb abaixo de 15 soa com ruído. Enquanto você não mudar nada (usingDefault), a mixagem é defaultMix, escolhida pelo papel: o microfone de cada pessoa, um por pessoa, entre todos os seus arquivos, abaixado entre as falas (ownMics); senão, entre os seus diarizeSourceIds, quando cada faixa escolhida ouve todo mundo, a mais limpa sozinha (cleanest); senão a sua seleção do jeito que está (picks). Uma faixa que você deixar fora de tracks num PUT volta pra esse padrão.

Pra mudar:

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 }
  }
}

Só muda o que você mandar. duck é mesclado campo a campo; tracks substitui a lista inteira por faixa, então mande toda faixa que você quer ajustar.

CampoO que faz
balanceEquilibrar vozes: sobe os microfones mais baixos pro nível do mais alto (um ganho por faixa, no máximo +18 dB).
duck.enabledAbaixa cada microfone enquanto a pessoa dele não está falando, pra que as outras vozes que ele capta não deixem a mixagem com som oco. Dá pra ajustar com depthDb (−40 a −3, padrão −12), fadeMs (20–1000, padrão 150) e padMs (0–1000, padrão 250: quanto antes da fala ele abre).
tracks.<sourceId>.gainDbO seu nível pra esse arquivo, de −24 a +12 dB, em cima do “Equilibrar vozes”.
tracks.<sourceId>.mutedtrue tira o arquivo do som.
tracks.<sourceId>.speakerDe quem é o microfone: um rótulo de voz, ou null pra ninguém (microfone de ambiente ou câmera, nunca é abaixado). Deixe de fora pra usar o palpite do WizCut.

Funciona em qualquer status. A mixagem vale pro próximo render, então chame o endpoint de render de novo pra ouvir no vídeo. Um campo malformado, ou um speaker que não existe no episódio, devolve 400 com "code": "INVALID_AUDIO_MIX".

Respostas de erro

Todos os endpoints retornam erros neste formato:

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

Alguns erros também trazem um code que dá pra ler por máquina:

CodeHTTPSignificado
TRACKS_ON_CREATE400O POST /api/jobs recebeu um mapeamento de participantes. Deixe tracks de fora e use autoMap, ou defina o mapeamento depois.
FILE_TOO_LARGE400Um arquivo passa do limite de tamanho, seja o declarado em fileSize ou o encontrado depois do upload. maxBytes traz o limite.
INVALID_FILE_SIZE400O fileSize não é um número inteiro de bytes.
NOT_A_MEDIA_FILE422Um arquivo não pode ser uma gravação: um arquivo de metadados do macOS (o nome começa com ._) ou um fileSize abaixo de 32 KB. fileName e reason dizem qual e por quê. Mande direto os arquivos de câmera e de áudio.
FILE_SIZE_MISMATCH400O arquivo enviado é bem menor ou bem maior que o fileSize declarado. Envie de novo.
UNKNOWN_SOURCE400Um track cita um sourceId que não é uma das fontes de vídeo do job.
CUTS_REQUIRED400Mudar o mapeamento depois que os cortes existem exige também os cuts atualizados.
CUT_NOT_ON_CAMERA422Um corte aponta pra algo que não é fonte de vídeo do job, tipo um arquivo de áudio (sem imagem). sourceIds lista eles.
NOT_ENOUGH_VIDEOS400O job precisa de pelo menos duas fontes de vídeo pra ser processado.
EMPTY_MAPPING400O mapeamento não coloca nenhum participante em nenhuma câmera. Atribua pelo menos um participante.
INVALID_IDEMPOTENCY_KEY400O header Idempotency-Key não tem de 1 a 255 caracteres ASCII imprimíveis.
URL_NOT_ALLOWED400Importação por link: não é um link https:// público.
NOT_A_FILE400Importação por link: uma página do YouTube ou do Vimeo, não um arquivo.
QUOTA_EXCEEDED403Seus minutos acabaram.
SOURCES_PENDING409O /process foi chamado enquanto ainda tem arquivo subindo ou sendo importado, ou a importação de um arquivo falhou. pendingSourceIds lista quais são (importingSourceIds e importFailedSourceIds dizem quais são importações): termine esses uploads e remova os arquivos cuja importação falhou.
INVALID_STATUS409O job não tá num status que permite isso, por exemplo, o mapeamento dele já foi enviado.
NO_CUTS409Não tem cortes pra renderizar.
NO_CAMERA409O job não tem mais nenhuma fonte de vídeo, só arquivos de áudio, então não tem imagem pra renderizar.
SOURCES_DELETED409Os arquivos originais do job foram apagados: a gente só guarda os originais por um tempo limitado, dependendo do plano. Abre ele no editor, sobe os mesmos arquivos de novo e depois renderiza.
NOT_RENDERED409Ainda não tem vídeo finalizado. O downloadUrl funciona assim que o job tá complete ou approved.
IDEMPOTENCY_IN_PROGRESS409Uma requisição com o mesmo Idempotency-Key ainda tá sendo processada. Tente de novo daqui a pouco.
IDEMPOTENCY_KEY_REUSED409O job (ou o arquivo importado) criado por esse Idempotency-Key foi excluído. Use uma chave nova.
JOB_FULL409Importação por link: o job já tem 12 arquivos.
IDEMPOTENCY_KEY_MISMATCH422Esse Idempotency-Key já foi usado com outro corpo de requisição.
TOO_MANY_IMPORTS429Importação por link: já tem 6 importações rodando nesse job. Espere o tempo do Retry-After.
IMPORT_RATE_LIMITED429Importação por link: 20 importações na última hora. Espere o tempo do Retry-After ou suba os arquivos.
IMPORT_UNAVAILABLE503A importação por link não tá disponível no momento. Suba o arquivo no lugar.

Códigos HTTP comuns:

CódigoSignificado
400Requisição inválida (ex.: menos de duas fontes de vídeo ao processar)
401API key ausente ou inválida
403Cota excedida, ou o upload pertence a outra conta
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), ou uma requisição com o mesmo Idempotency-Key ainda rodando
422Um Idempotency-Key reutilizado com outro corpo de requisição
429Importações por link demais ao mesmo tempo, ou na última hora
500Erro no servidor
502Um serviço de processamento rejeitou o job ou falhou ao iniciar
503Serviço indisponível

Fluxo completo

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

# 1. Criar um job com duas câmeras (arquivos de até 5 GB cada, passe
#    fileSize pra ganhar upload multipart em arquivos maiores, até 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. Enviar os vídeos pras URLs presigned
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 o processamento
curl -s -X POST "https://wizcut.com/api/jobs/$JOB_ID/process" \
  -H "Authorization: Bearer wc_live_your_key"

# 4. Esperar o próximo webhook. Com o autoMap padrão ("confident"):
#    - { status: "ready", reviewUrl: "..." } — o WizCut mapeou as câmeras sozinho
#    - { status: "mapping", reviewUrl: "...", speakers: [...], cameraMap: {...} }
#      — ele não teve certeza. Mandar uma pessoa pra reviewUrl confirmar as câmeras
#      (ou enviar o mapeamento você mesmo via POST pra /api/jobs/$JOB_ID/tracks)

# 5. A pessoa revisa e edita os cortes → clica em Render no editor
#    Esperar o webhook: { status: "complete", outputUrl: "..." }

# 6. Baixar o vídeo renderizado da outputUrl

Totalmente sem supervisão (autoMap: "always", review: false):

# Igual acima, mas com "autoMap": "always" e "review": false no passo 1
# O WizCut mapeia as câmeras sozinho, mesmo quando não tem certeza,
# e começa a renderizar logo em seguida, sem nenhuma pessoa envolvida
# Você recebe: { status: "ready", ... } e depois { status: "complete", outputUrl: "..." }

Integrações

Prefere não escrever código? Você consegue usar a WizCut API direto de plataformas de automação, sem precisar montar nenhuma das requisições acima.

n8n

A gente mantém uma integração oficial com n8n, o community node verificado @wizcut/n8n-nodes-wizcut. Instale pelo Settings → Community Nodes dentro do n8n (já é verificado, então funciona no n8n Cloud também).

O node vem com dois blocos:

  • WizCut: ações para Create Job, Get Job, Start Processing, Start Render e Approve.
  • WizCut Trigger: um webhook trigger que inicia o seu workflow sempre que um job muda de status (mapping, ready, complete, approved).

Aponta a URL do trigger pro callbackUrl do job e você tem um pipeline totalmente orientado a eventos. Por exemplo: avisa no Slack quando o WizCut precisa que alguém confirme quem tá em qual câmera, começa o render automaticamente quando os cortes ficam prontos e posta o link de download quando o episódio tá finalizado. Os dois nodes também funcionam como ferramentas pra agentes de IA do n8n.

Os nodes ainda não importam por link: pra arquivos que já estão num drive na nuvem, adicione eles com um node HTTP Request, como descrito em Importar arquivos por link.

Quer sair com vantagem? Pega o template pronto: Notify and manage podcast edit status with WizCut and Slack.

Mais plataformas

As integrações com Make.com e Zapier estão no roadmap. Usando uma plataforma diferente ou precisa de um template de workflow pro seu setup específico? Fala com o suporte do WizCut, pedidos de novas funcionalidades são bem-vindos.

WizCut API – WizCut Docs