Webhook dan siklus hidup pekerjaan media

Panduan operasional untuk job media asinkron: pendaftaran webhook, status, polling, kode error, biaya, dan batas idempotensi — sepenuhnya sesuai implementasi saat ini di dalam kode.

1. POST /api/media/generate — saat berhasil 202 dan { ok: true, jobId, status: "processing" }. Tidak ada status queued / running terpisah di API: sampai job selesai, klien melihat processing.
2. Upstream dapat melewati tahap internal (waiting, generating) — ini tidak tercermin di API publik; selama polling, job tetap processing.
3. Status terminal: success (memiliki resultUrls, dikenai biaya saat berhasil) atau fail (tanpa biaya).
4. Penyelesaian dicatat sekali: melalui callback upstream atau pada polling lazy di 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":...}

Satu URL per akun: mediaWebhookUrl. Dikonfigurasi di dashboard → Webhooks atau melalui API dengan sesi akun (cookie setelah login). Endpoint tidak menerima sk-pv-… — hanya sesi yang terautentikasi.

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

Saat pekerjaan mencapai status terminal, GetVibe membuat satu peristiwa logis dan mengirimkannya melalui POST ke mediaWebhookUrl yang terdaftar. Pengiriman dibatasi: layanan melakukan hingga 5 percobaan total. Payload yang sama dapat tiba lebih dari sekali.

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

• Ditagih sekali saat berhasil. Di finalizeJob transisi processing → success|fail bersifat atomik: callback atau poll yang berulang tidak menciptakan tagihan kedua.
• fail — gratis. Tidak ada pendebitan yang dilakukan pada status fail.
• Kutipan penerimaan. Jika kutipan disimpan saat pembuatan, tepat itulah yang ditagih saat berhasil (tidak pernah lebih dari metering upstream yang sebenarnya).
• Idempotensi create — melalui header. POST berulang ke /api/media/generate tanpa header tersebut akan membuat job baru dan tagihan baru saat berhasil. Kirim Idempotency-Key (hingga 255 karakter ASCII): percobaan ulang dengan key dan body yang sama dalam 24 jam mengembalikan jobId yang sama tanpa job baru; key yang sama dengan body berbeda menghasilkan 422, dan 409 selama permintaan pertama masih diproses. jobId dari generasi berbayar juga ditampilkan di GET /v1/generations (field job_id).
• Webhook dibatasi maksimal lima percobaan. Satu event logis dibuat per transisi terminal, tetapi percobaan pengiriman bisa berulang. Setelah lima kegagalan, event mendapat status FAILED . Handler di sisi klien harus melakukan deduplikasi terhadap pasangan jobId + status.