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

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

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

# 2. опросить задачу до готовности
curl https://plusvibeapi.ru/api/media/jobs/JOB_ID \
  -H "Authorization: Bearer $PLUSVIBE_API_KEY"
# → {"status":"success","resultUrls":["https://..."],"priceRub":...}

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

# Пример (нужна сессия кабинета, не API-ключ)
curl -X PATCH https://plusvibeapi.ru/api/webhooks \
  -H "Content-Type: application/json" \
  -b "session=ВАША_СЕССИЯ" \
  -d '{"mediaWebhookUrl":"https://example.com/plusvibe/media"}'

# Очистить URL
curl -X PATCH https://plusvibeapi.ru/api/webhooks \
  -H "Content-Type: application/json" \
  -b "session=ВАША_СЕССИЯ" \
  -d '{"mediaWebhookUrl":null}'

Когда задача переходит в терминальный статус, PlusVibe создаёт одно логическое событие и доставляет его POST на зарегистрированный mediaWebhookUrl. Доставка ограничена: сервис делает до 5 попыток всего. Один и тот же payload может прийти повторно.

// POST на ваш mediaWebhookUrl при завершении задачи
{
  "jobId": "...",
  "status": "success",            // или "fail"
  "model": "veo-3.1",
  "kind": "video",                // image | video | audio | music | 3d
  "resultUrls": ["https://plusvibeapi.ru/api/media/file/..."],
  "failMsg": null,
  "createdAt": "2026-06-17T10:00:00.000Z"
}

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