Техническое руководство
Vidu API: webhook timeout и безопасная сверка статуса
Запрос «Vidu API webhook timeout сверка статуса» не означает, что задача не выполнилась. Сначала сохраните внутренний task ID, дедуплицируйте событие и отделите timeout приложения от результата. RussiaAPI — независимый сторонний gateway и не обещает порядок, доставку или повтор webhook.
Timeout webhook — это неизвестный итог
Локальный таймаут говорит только о том, что ваш обработчик не получил или не завершил событие за отведённое время. Он не подтверждает отмену, ошибку или успешное видео-задание. Если сразу создать новую задачу, пользователь может получить дубль, а команда — два разных статуса без ясной связи.
Создайте внутренний operation ID до постановки задачи и храните отдельно техническое состояние: pending, event_received, review_required или closed. Не объявляйте готовность результата по отсутствию webhook. Сначала сверяйте допустимым для вашего маршрута способом только тот статус, который реально умеет обработать приложение, и фиксируйте время последней попытки.
Дедуплицируйте события локально
Один webhook может прийти повторно, поздно или в неожиданном порядке. Ваша база должна принимать событие идемпотентно: ключом служат внутренний task ID и идентификатор события, если он подтверждён контрактом. Если таких полей нет, создайте локальный ключ корреляции при запуске и не превращайте временную метку в доказательство уникальности.
Обработчик сначала валидирует форму входа, затем ищет существующее состояние и только потом меняет его. Не публикуйте видео и не запускайте downstream действие внутри ветки «новое событие» без дополнительной проверки. Порядок событий поставщика может измениться, поэтому локальная state machine должна безопасно принимать неизвестный или повторный сигнал.
Разделите приём, работу и ответ
Webhook endpoint должен быстро подтвердить только то, что приложение безопасно приняло минимальное событие. Тяжёлая сверка, загрузка результата и публикация выполняются отдельной управляемой очередью. Такой дизайн уменьшает риск второго timeout, но не обещает доставку или время обработки внешнего сервиса.
Сохраняйте в очереди короткие технические данные: внутренний task ID, нормализованную категорию события, счётчик попыток и следующий разрешённый шаг. Не кладите туда полный prompt, медиа URL, чужой Authorization header или ключ. Если ошибка валидации повторяется, отправьте задачу на review вместо бесконечного повтора одного и того же события.
Сверяйте статус без нового запуска
Перед повторной генерацией проверьте, есть ли у приложения известный локальный task ID и финальное состояние. Если итог не подтверждён, пометьте его как unknown и покажите пользователю честное сообщение. Не подменяйте это новой задачей: повтор имеет иной operation ID, меняет расход и не помогает понять, была ли первая операция завершена.
Сверка должна быть ограничена policy: максимальное число попыток, срок ожидания и владелец review. Не предполагается, что Vidu поддерживает конкретный polling endpoint, повторную доставку или формат подписи; эти свойства проверяются по текущему документированному контракту выбранного маршрута.
Добавьте сценарии отказа
На staging проверьте повтор события, пустой task ID, событие после закрытия, обрыв очереди и неизвестный статус. Все они должны приводить к предсказуемому внутреннему состоянию, а не к повторной генерации. Внешний webhook — недоверенный ввод: валидируйте формат и доступ до записи в бизнес-объект.
Продолжите с выбором polling или webhook, асинхронной генерацией видео и очередью ошибок video API. Материалы не заявляют, что конкретный callback всегда придёт или будет упорядочен.
Сначала зафиксируйте границу решения
Название модели, HTTP-статус или успешный тест не заменяют решение приложения. До интеграции команда определяет, кто может запускать задачу, какой сценарий разрешён, что считать неизвестным результатом и когда требуется человек. Такая граница защищает продукт от скрытого автопереключения и от неверного вывода, будто внешний маршрут гарантирует бизнес-результат.
Проверяйте правила на синтетических значениях. Не кладите в fixture настоящий prompt, пользовательское вложение, cookie, авторизационный заголовок или ключ. Для технической записи обычно достаточно времени, версии адаптера, внутреннего operation ID, категории исхода и хэша нормализованной структуры. Это позволяет искать регрессии, не превращая журнал в копию пользовательских данных.
Проверяйте контракт небольшим сценарием
Минимальный контрактный тест должен различать корректный ответ, ошибку валидации, отказ локальной policy, временную сеть и неизвестный итог. Для каждого состояния заранее назначьте действие: безопасно остановить, повторить только идемпотентную операцию или передать её на review. Бесконечный retry не исправляет несовместимый формат и не доказывает, что внешнее действие не случилось.
Запишите дату, версию клиента и условия проверки. Если обновились SDK, каталог, формат ответа или ваш адаптер, повторите короткий синтетический тест до расширения трафика. Один удачный вызов показывает лишь наблюдаемый путь в конкретной конфигурации; он не является обещанием постоянной совместимости, качества или пропускной способности.
Минимизируйте технические данные
Не делайте секрет, полный пользовательский текст, исходный media URL или сырой ответ модели стандартным полем лога. Отделите понятное сообщение для пользователя от защищённой server-side записи. Доступ к журналам ограничьте ролями, а срок хранения определите локальной политикой и классификацией данных, а не предположением о правилах поставщика.
Если для разбора инцидента нужны дополнительные сведения, включайте их временно, с явной целью и владельцем. По умолчанию оставляйте короткий correlation ID, тип события, длительность и нормализованную причину. Не показывайте в браузере диагностические объекты, которые могут содержать внутренние детали маршрута или токены.
Оставьте обратимый путь
Новый routing rule, обработчик webhook или набор параметров включайте так, чтобы его можно было отключить без изменения пользовательских данных. Сохраните известный безопасный сценарий, критерий остановки и короткую запись решения. При неясном статусе направляйте операцию на review вместо повторной отправки, публикации результата или автоматического побочного действия.
Это не разрешение нарушать правила, ограничения или условия поставщика. Наоборот, обратимый rollout помогает команде соблюдать собственные процедуры и остановиться при расхождении контракта. Не сообщайте пользователю цену, готовность результата или доступность функции, пока ваш текущий разрешённый маршрут не подтвердил их в конкретном сценарии.
Разделите локальную policy и внешний сервис
Локальная allowlist, лимит очереди, ручная проверка и журнал — это функции вашего приложения. Они не равны каталогу моделей, внешнему rate limit, остаткам, SLA или сертификации поставщика. Такое разделение делает ответ пользователю честным: приложение управляет собственным риском, а свойства маршрута нужно подтверждать отдельно в актуальном каталоге, договоре и документации.
Ключ RussiaAPI используйте только на сервере через переменную окружения или совместимое хранилище секретов. Не переносите в новый gateway чужой ключ, cookie или Authorization header. Перед реальным запросом подтвердите доступный маршрут и model ID в своём аккаунте; пример ниже намеренно не вызывает сеть и не доказывает поддержку endpoint.
Планируйте отрицательные тесты
Happy path полезен, но не показывает, как система поведёт себя при пустом идентификаторе, неизвестном параметре, повторном событии, обрыве клиента или устаревшей версии policy. Добавьте такие случаи до релиза. Если проверка не может определить безопасный итог, верните локальную понятную ошибку или запросите review, а не пытайтесь угадать состояние задачи.
Регулярно пересматривайте владельца policy, тестовую дату и условия rollback. Чем проще структура решения, тем легче обнаружить изменение контракта. Не записывайте для этого полный prompt и не расширяйте права «на всякий случай»: наблюдаемость должна помогать разбирать проблему, а не создавать новую поверхность утечки.
Server-side пример без сетевого вызова
Пример демонстрирует только локальную проверку приложения. Он не содержит настоящего ключа, не вызывает сеть и не подтверждает конкретный endpoint. Для реальной интеграции используйте собственный ключ RussiaAPI на сервере через RUSSIAAPI_API_KEY и предварительно сверяйте текущий каталог и контракт.
function applyWebhook(state, event) {
if (!event?.localTaskId || !event?.eventId) return { ok: false, code: 'invalid_event' };
if (state.seenEventIds?.includes(event.eventId)) return { ok: true, code: 'duplicate_ignored', state };
if (state.status === 'closed') return { ok: false, code: 'review_required' };
return { ok: true, state: { ...state, status: 'event_received', seenEventIds: [...(state.seenEventIds || []), event.eventId] } };
}Проверьте синтаксис через node --check, добавьте аутентификацию своего маршрута и негативные тесты. Не логируйте тело запроса или заголовки лишь ради отладки.
Источники для дальнейшей проверки
Ссылки дают общий инженерный контекст. Перед production-изменением сопоставьте их со своим договором, текущим каталогом RussiaAPI и тестом конкретного маршрута.
Проверьте сценарий в RussiaAPI
Создайте собственный тестовый ключ в консоли, подтвердите доступный маршрут и выполните обезличенный server-side smoke test. Расширяйте доступ и нагрузку только после измеримой проверки.
FAQ
Означает ли timeout, что видео не создано?
Нет. Timeout описывает состояние вашего обработчика или соединения, а не итог внешней задачи. Сохраните неизвестный статус, сверяйте допустимый маршрут и не создавайте новый запуск только из-за отсутствия callback.
Можно ли повторить webhook?
Не предполагайте поддержку повторной доставки. Сделайте свой обработчик идемпотентным, валидируйте вход и сохраняйте внутренний task ID. Возможность replay, подписи и формат события нужно проверить в актуальном контракте.
Что журналировать при инциденте?
Минимум: внутренний task ID, время, нормализованный тип события, результат локальной проверки и correlation ID. Не записывайте ключи, полный prompt, raw headers или ссылку на исходный пользовательский файл.