Webhooks und der Lebenszyklus von Medienaufträgen

Betriebsleitfaden für asynchrone Medienjobs: Webhook-Registrierung, Status, Abfragen, Fehlercodes, Abrechnung und Idempotenzlimits — strikt gemäß der aktuellen Implementierung im Code.

1. POST /api/media/generate – bei Erfolg 202 und { ok: true, jobId, status: "processing" }. In der API gibt es keine separaten Statuswerte queued / running: Bis der Job abgeschlossen ist, sieht der Client processing.
2. Der Upstream kann interne Phasen durchlaufen (waiting, generating) — diese werden in der öffentlichen API nicht widergespiegelt; während des Pollings bleibt der Job processing.
3. Terminalstatus: success (enthält resultUrls, wird bei Erfolg berechnet) oder fail (keine Berechnung).
4. Der Abschluss wird einmal erfasst: über den Upstream-Callback oder bei einer verzögerten Abfrage unter 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":...}

Eine URL pro Konto: mediaWebhookUrl. Konfiguriert unter Dashboard → Webhooks oder über die API mit einer Kontositzung (einem Cookie nach der Anmeldung). Der Endpunkt akzeptiert sk-pv-… — ausschließlich eine authentifizierte Sitzung.

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

Wenn ein Auftrag einen endgültigen Status erreicht, erstellt GetVibe ein logisches Ereignis und übermittelt es über POST an den registrierten mediaWebhookUrl. Die Zustellung ist begrenzt: Der Dienst unternimmt insgesamt bis zu 5 Versuche. Dieselbe Nutzlast kann mehr als einmal eintreffen.

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

• Wird bei Erfolg einmal berechnet. In finalizeJob ist der Übergang processing → success|fail atomar: Ein wiederholter Callback oder Polling-Vorgang erzeugt keine zweite Berechnung.
• fail – kostenlos. Bei einem fail-Status wird keine Belastung vorgenommen.
• Aufnahmeangebot. Wenn bei der Erstellung ein Angebot gespeichert wurde, wird bei Erfolg genau dieses berechnet (niemals mehr als die tatsächliche Abrechnung des Upstreams).
• Idempotenz erstellen – per Header. Ein wiederholter POST an /api/media/generate ohne den Header erstellt einen neuen Job und berechnet bei Erfolg erneut. Senden Sie Idempotency-Key (bis zu 255 ASCII-Zeichen): Ein erneuter Versuch mit demselben Schlüssel und Body innerhalb von 24 Stunden gibt dieselbe jobId ohne einen neuen Job zurück; derselbe Schlüssel mit einem anderen Body ergibt 422 und 409, solange die erste Anfrage noch verarbeitet wird. Die jobId einer kostenpflichtigen Generierung wird auch in GET /v1/generations angezeigt (im Feld job_id).
• Der Webhook ist auf fünf Versuche begrenzt. Für jeden endgültigen Statuswechsel wird ein logisches Ereignis erstellt, die Zustellversuche können sich jedoch wiederholen. Nach fünf Fehlversuchen erhält das Ereignis den Status FAILED. Der Client-Handler muss das Paar jobId + status deduplizieren.