Webhooks и жизненный цикл медиазадач

Практическое руководство по асинхронным медиазадачам: регистрация вебхуков, статусы, опрос, коды ошибок, списания и лимиты идемпотентности — строго по текущей реализации в коде.

1. POST /api/media/generate — при успехе 202 и { ok: true, jobId, status: "processing" }. Отдельных статусов queued / running в API нет: пока задача не завершена, клиент видит processing.
2. Вышестоящий сервис может проходить внутренние стадии (waiting, generating) — они не отражаются в публичном API; во время опроса задание остаётся processing.
3. Терминальные статусы: success (есть resultUrls, списание при успехе) или fail (без списания).
4. Завершение фиксируется один раз: через обратный вызов от upstream или при отложенном опросе в 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":...}

Один URL на аккаунт: mediaWebhookUrl. Настраивается в панели → Webhooks или через API с сессией аккаунта (cookie после входа). Эндпоинт не принимает sk-pv-… — только аутентифицированную сессию.

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

Когда задача достигает терминального статуса, GetVibe создаёт одно логическое событие и доставляет его через POST на зарегистрированный mediaWebhookUrl. Доставка ограничена: сервис делает до 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"
}

• Списание один раз при успехе. В finalizeJob переход processing → success|fail атомарен: повторный callback или опрос не создаёт второго списания.
• fail — бесплатно. При статусе fail списание не производится.
• Квота при допуске. Если при создании была сохранена квота, при успехе списывается ровно она (никогда не больше фактического метеринга у провайдера).
• Идемпотентность создания — через заголовок. Повторный POST на /api/media/generate без этого заголовка создаёт новую задачу и новое списание при успехе. Передайте Idempotency-Key (до 255 ASCII-символов): повтор с тем же ключом и телом в течение 24 часов вернёт тот же jobId без создания новой задачи; тот же ключ с другим телом — 422, а 409 — пока первый запрос ещё обрабатывается. jobId платной генерации также показан в GET /v1/generations (поле job_id).
• Webhook ограничен пятью попытками. На каждый терминальный переход создаётся одно логическое событие, но попытки доставки могут повторяться. После пяти неудач событие получает статус FAILED. Обработчик на стороне клиента должен дедуплицировать пару jobId + status.