Webhooks et cycle de vie des tâches multimédias

Guide opérationnel des tâches multimédias asynchrones : enregistrement des webhooks, statuts, interrogation périodique, codes d’erreur, frais et limites d’idempotence, strictement selon l’implémentation actuelle du code.

1. POST /api/media/generate — en cas de succès, 202 et { ok: true, jobId, status: "processing" }. L’API ne comporte pas de statuts distincts queued / running : jusqu’à la fin du job, le client voit processing.
2. L’amont peut passer par des étapes internes (waiting, generating) qui ne sont pas reflétées dans l’API publique ; pendant l’interrogation, la tâche reste processing.
3. États du terminal : success (contient resultUrls, facturé en cas de succès) ou fail (aucun frais).
4. La complétion est enregistrée une seule fois : via le callback en amont ou lors d’une interrogation différée dans 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":...}

Une URL par compte : mediaWebhookUrl. Configurée dans dashboard → Webhooks ou via l’API avec une account session (un cookie après la connexion). L’endpoint n’accepte pas sk-pv-… : uniquement une session authentifiée.

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

Lorsqu’une tâche atteint un statut final, GetVibe crée un événement logique unique et le distribue via POST au mediaWebhookUrl enregistré. La livraison est limitée : le service effectue au total jusqu’à 5 tentatives. Le même payload peut être reçu plusieurs fois.

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

• Facturé une seule fois en cas de succès. Dans finalizeJob, la transition processing → success|fail est atomique : un callback ou un sondage répété ne déclenche pas de seconde facturation.
• fail — gratuit. Aucun débit n’est effectué pour un statut fail.
• Cotation d’admission. Si une cotation a été enregistrée lors de la création, c’est exactement ce montant qui est facturé en cas de succès (jamais davantage que le décompte réel du fournisseur amont).
• Créez l’idempotence — via un en-tête. Un POST répété vers /api/media/generate sans l’en-tête crée un nouveau job et une nouvelle facturation en cas de succès. Envoyez Idempotency-Key (jusqu’à 255 caractères ASCII) : une nouvelle tentative avec la même clé et le même corps dans les 24 heures renvoie le même jobId sans créer de nouveau job ; la même clé avec un corps différent renvoie 422, et 409 tant que la première requête est encore en cours de traitement. Le jobId d’une génération payante apparaît également dans GET /v1/generations (le champ job_id).
• Le webhook est limité à cinq tentatives. Un événement logique est créé pour chaque transition finale, mais les tentatives de livraison peuvent se répéter. Après cinq échecs, l’événement reçoit le statut FAILED . Le gestionnaire client doit dédupliquer la paire jobId + status.