Webhooks और media job lifecycle

asynchronous media jobs की operational guide: webhook registration, statuses, polling, error codes, charges और idempotency limits — पूरी तरह code में मौजूद वर्तमान implementation के अनुसार।

1. POST /api/media/generate — सफलता पर 202 और { ok: true, jobId, status: "processing" }। API में अलग queued / running statuses नहीं हैं: job पूरा होने तक client को processing दिखता है।
2. Upstream internal stages (waiting, generating) से गुज़र सकता है — ये public API में reflect नहीं होते; polling के दौरान job processing ही रहता है।
3. Terminal statuses: success (has resultUrls, charged on success) या fail (no charge)।
4. Completion एक बार दर्ज होता है: upstream callback के ज़रिए या GET /api/media/jobs/{id} में lazy poll पर।

# 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":...}

प्रति account एक URL: mediaWebhookUrl। dashboard → Webhooks में या API के ज़रिए account session (लॉगिन के बाद का cookie) से कॉन्फ़िगर किया जाता है। endpoint accept नहीं करता sk-pv-… — केवल authenticated session।

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

जब कोई job terminal status पर पहुँचता है, तो GetVibe एक logical event बनाता है और उसे POST के ज़रिए registered mediaWebhookUrl पर deliver करता है। Delivery सीमित है: सेवा कुल अधिकतम 5 प्रयास करती है। वही payload एक से अधिक बार पहुँच सकता है।

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

• सफलता पर एक बार charge। finalizeJob में transition processing → success|fail atomic है: बार-बार callback या poll करने पर दूसरा charge नहीं बनता।
• fail — मुफ़्त। fail status पर कोई debit नहीं किया जाता।
• Admission quote. अगर creation के समय कोई quote save किया गया था, तो success पर ठीक वही charge होता है (actual upstream metering से कभी अधिक नहीं)।
• Idempotency बनाएँ — header से। header के बिना /api/media/generate पर बार-बार POST करने से नया job और सफलता पर नया charge बनता है। Idempotency-Key भेजें (255 ASCII characters तक): 24 घंटे के भीतर उसी key और body के साथ retry करने पर नया job बनाए बिना वही jobId लौटता है; अलग body के साथ वही key 422 देता है, और पहला request अभी process हो रहा हो तो 409। पेड generation का jobId GET /v1/generations में भी दिखता है (job_id field)।
• Webhook अधिकतम पाँच attempts तक सीमित है। हर terminal transition पर एक logical event बनता है, लेकिन delivery attempts दोहराए जा सकते हैं। पाँच failures के बाद event को status FAILED मिल जाता है। Client handler को jobId + status जोड़ी को deduplicate करना चाहिए।