Webhooks and the media job lifecycle

Operational guide to asynchronous media jobs: webhook registration, statuses, polling, error codes, charges and idempotency limits — strictly per the current implementation in the code.

1. POST /api/media/generate — on success 202 and { ok: true, jobId, status: "processing" }. There are no separate queued / running statuses in the API: until the job finishes, the client sees processing.
2. Upstream may go through internal stages (waiting, generating) — these are not reflected in the public API; while polling, the job stays processing.
3. Terminal statuses: success (has resultUrls, charged on success) or fail (no charge).
4. Completion is recorded once: via the upstream callback or on a lazy poll in 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":...}

One URL per account: mediaWebhookUrl. Configured in dashboard → Webhooks or via the API with an account session (a cookie after login). The endpoint does not accept sk-pv-… — only an 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}'

When a job reaches a terminal status, GetVibe creates one logical event and delivers it via POST to the registered mediaWebhookUrl. Delivery is capped: the service makes up to 5 attempts total. The same payload may arrive more than once.

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

• Charged once on success. In finalizeJob the transition processing → success|fail is atomic: a repeated callback or poll does not create a second charge.
• fail — free. No debit is performed on a fail status.
• Admission quote. If a quote was saved at creation, exactly it is charged on success (never more than the actual upstream metering).
• Create idempotency — by header. A repeated POST to /api/media/generate without the header creates a new job and a new charge on success. Send Idempotency-Key (up to 255 ASCII characters): a retry with the same key and body within 24 hours returns the same jobId without a new job; the same key with a different body is 422, and 409 while the first request is still being processed. The jobId of a paid generation is also shown in GET /v1/generations (the job_id field).
• Webhook is capped at five attempts. One logical event is created per terminal transition, but delivery attempts may repeat. After five failures the event gets the status FAILED . The client handler must deduplicate the pair jobId + status.