Webhooks e o ciclo de vida do trabalho de mídia

Guia operacional para jobs de mídia assíncronos: registro de webhook, status, polling, códigos de erro, cobranças e limites de idempotência — estritamente conforme a implementação atual no código.

1. POST /api/media/generate — em caso de sucesso, 202 e { ok: true, jobId, status: "processing" }. Não há status separados de queued / running na API: até o job ser concluído, o cliente vê processing.
2. O upstream pode passar por etapas internas (waiting, generating) — elas não são refletidas na API pública; durante o polling, o job permanece processing.
3. Status do terminal: success (contém resultUrls, cobrado em caso de sucesso) ou fail (sem cobrança).
4. A conclusão é registrada uma vez: por meio do callback upstream ou em uma consulta lazy em GET /api/media/jobs/{id}.

# 2. poll the job until it is ready
curl https://getvibeapi.com/api/media/jobs/JOB_ID \
  -H "Authorization: Bearer $GETVIBE_API_KEY"
# → {"status":"success","resultUrls":["https://..."],"priceRub":...}

Uma URL por conta: mediaWebhookUrl. Configurada em dashboard → Webhooks ou pela API com uma account session (um cookie após o login). O endpoint não aceita sk-pv-… — somente uma sessão autenticada.

# Example (a dashboard session is required, not an API key)
curl -X PATCH https://getvibeapi.com/api/webhooks \
  -H "Content-Type: application/json" \
  -b "session=YOUR_SESSION" \
  -d '{"mediaWebhookUrl":"https://example.com/webhooks/media"}'

# Clear the URL
curl -X PATCH https://getvibeapi.com/api/webhooks \
  -H "Content-Type: application/json" \
  -b "session=YOUR_SESSION" \
  -d '{"mediaWebhookUrl":null}'

Quando um trabalho atinge um status final, o GetVibe cria um evento lógico e o entrega via POST ao mediaWebhookUrl registrado. A entrega é limitada: o serviço faz até 5 tentativas no total. O mesmo payload pode chegar mais de uma vez.

// POST to your mediaWebhookUrl when a job finishes
{
  "jobId": "...",
  "status": "success",            // or "fail"
  "model": "veo-3.1",
  "kind": "video",                // image | video | audio | music | 3d
  "resultUrls": ["https://getvibeapi.com/api/media/file/..."],
  "failMsg": null,
  "createdAt": "2026-06-17T10:00:00.000Z"
}

• Cobrado uma vez em caso de sucesso. Em finalizeJob, a transição processing → success|fail é atômica: uma chamada de retorno ou consulta repetida não gera uma segunda cobrança.
• fail — gratuito. Nenhum débito é realizado com um status fail.
• Cotação de admissão. Se uma cotação foi salva na criação, exatamente esse valor é cobrado em caso de sucesso (nunca mais do que a medição real do upstream).
• Crie a idempotência por meio do cabeçalho. Um POST repetido para /api/media/generate sem o cabeçalho cria um novo job e uma nova cobrança em caso de sucesso. Envie Idempotency-Key (até 255 caracteres ASCII): uma nova tentativa com a mesma chave e o mesmo corpo dentro de 24 horas retorna o mesmo jobId sem um novo job; a mesma chave com um corpo diferente retorna 422, e 409 enquanto a primeira solicitação ainda estiver sendo processada. O jobId de uma geração paga também é exibido em GET /v1/generations (o campo job_id).
• O webhook é limitado a cinco tentativas. Um único evento lógico é criado por transição terminal, mas as tentativas de entrega podem se repetir. Após cinco falhas, o evento recebe o status FAILED . O handler do cliente deve eliminar duplicatas do par jobId + status.