Vidu API: повтор получения результата без новой генерации

Почему новый запрос не является первым ответом

Ошибка выдачи результата, timeout браузера или потерянный callback не доказывают, что видео-задача не завершилась. Повторная генерация в такой ситуации может создать дубль, дополнительный расход или две разные публикации. Сначала приложение ищет собственный operation ID, последнюю нормализованную запись статуса и время последней попытки.

Если записи нет или она противоречива, честный исход — unknown, а не completed и не failed. Пользовательский интерфейс может предложить повторную проверку статуса или ручный review, не создавая скрытую новую задачу. Это правило относится к вашей очереди и интерфейсу; оно не предполагает, что конкретный внешний API поддерживает тот или иной способ получения результата.

Локальная state machine для video-задачи

Определите небольшое число состояний: created, awaiting-status, result-ready, review-needed и closed. Переход разрешён только при наличии внутреннего task ID и проверяемого события. Внешний ответ сначала нормализуется, а неизвестные поля не должны сами переводить задачу в success. Такая модель упрощает анализ повторного callback и случайного двойного клика.

Сохраняйте время перехода, версию адаптера и безопасную категорию причины, но не полную ссылку на media. URL может быть временным или содержать параметры доступа. Если для защищённого расследования ссылка всё же нужна, ограничьте её доступ и срок отдельной policy, а не обычным application log.

Когда допустимо повторно запросить статус

Повторная проверка допустима только как ограниченная идемпотентная операция вашего приложения: с лимитом частоты, correlation ID и понятным критерием остановки. Она не должна менять исходный prompt, создавать новую задачу или автоматически публиковать файл. После нескольких неизвестных ответов переходите к review, а не увеличивайте количество запросов бесконечно.

Даже успешный ответ проверяйте на соответствие внутреннему task ID и допустимому состоянию. Если связь не установлена, результат не выдаётся пользователю. Эта проверка защищает от смешения tenant и старых событий. Она не подтверждает подлинность, права, качество или срок хранения результата — для них нужны отдельные локальные процессы.

Выдача результата после проверки

Перед публикацией убедитесь, что задача принадлежит нужному tenant, состояние result-ready подтверждено локально, а последующее действие разрешено policy. Если файл уже скачан, проверяйте тип и целостность отдельной процедурой. Не показывайте технический объект статуса в браузере и не сообщайте пользователю, что внешний процесс гарантированно завершён.

Свяжите кнопку выдачи с внутренним operation ID, чтобы повторный запрос пользователя не создал дубликат публикации. Любая неясность остаётся видимой как review-needed. Такой UX менее эффектный, но он честнее: он не маскирует неизвестность автоматической генерацией и помогает оператору разобраться в одной задаче, а не в нескольких копиях.

Начните с локальной политики

Название модели, один успешный запрос или знакомый SDK не дают приложению права считать поведение внешнего маршрута постоянным. До запуска зафиксируйте, какие данные разрешены, кто утверждает исключения, какая версия адаптера тестируется и какое событие останавливает поток. Это превращает технический материал в проверяемый процесс, а не в рекламное обещание.

Для проверки используйте синтетический tenant, обезличенную фикстуру и локальный operation ID. Не нужны production prompt, cookie, заголовок Authorization, реальный API key, персональные данные или ссылка на пользовательское медиа. Минимальная фикстура должна проверять форму входа, ожидаемую локальную категорию результата и безопасный путь для неизвестного итога.

Не раскрывайте содержимое в диагностике

Полезная запись для эксплуатации обычно состоит из времени, внутреннего ID проекта, версии policy, типа операции, длительности и нормализованного исхода. Полный prompt, ответ модели, media URL и заголовки не должны попадать в стандартный журнал. Доступ к расширенной диагностике задают отдельно: с целью, ролями, сроком хранения и последующей очисткой.

Клиенту показывайте короткое нейтральное сообщение и идентификатор обращения, а детальную причину оставляйте на server-side. Если статус нельзя определить, честно сохраните категорию unknown и направьте сценарий на review. Не восстанавливайте его смысл из личных данных и не отправляйте объект ошибки в браузер: там могут оказаться технические детали маршрута или токены.

Проверяйте отрицательные сценарии

Один happy path не показывает, что произойдёт с пустым полем, повторным событием, устаревшей версией или оборванным соединением. Добавьте эти фикстуры до rollout и заранее решите действие: безопасно остановить, повторить только идемпотентную операцию либо передать её человеку. Негативный набор нужен для поведения приложения, а не для заявления о свойствах поставщика.

Неизвестный результат нельзя автоматически выдавать за успех. Если операция способна создать публикацию, списание, уведомление или изменение состояния, сначала сверяйте локальный operation ID и сохранённый статус. Бесконечный retry не доказывает совместимость. Контролируемая остановка и ручная проверка уменьшают риск дублей и упрощают rollback.

Оставьте обратимый rollout

Новое правило включайте так, чтобы его можно было отключить без изменения пользовательских данных. Сохраните предыдущую проверенную конфигурацию, дату теста, владельца решения и критерий rollback. При расхождении схемы, policy или локальной метрики остановите rollout, а не подменяйте результат скрытым маршрутом.

Периодически возвращайтесь к синтетической проверке после обновления SDK, адаптера или внутренней policy. Она не заменяет актуальные договоры и документацию поставщика, но помогает обнаружить изменение на контролируемом уровне. Так команда отделяет измеренное поведение собственного приложения от предположений об API.

Безопасный server-side пример

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

const task = { operationId: 'op_video_17', state: 'awaiting-status', attempts: 1, tenantId: 'tenant_a' };
function canRecheck(input) {
  return input.tenantId === 'tenant_a' && input.state === 'awaiting-status' && input.attempts < 3;
}
if (!canRecheck(task)) throw new Error('LOCAL_REVIEW_REQUIRED');
console.log({ operationId: task.operationId, action: 'recheck_status_only' });

Источники и границы

AWS: Idempotent APIs · MDN: AbortController

Источники объясняют общие инженерные практики. Они не подтверждают, что конкретная функция включена у RussiaAPI или в вашем аккаунте. Соблюдайте применимые требования и не передавайте секреты в браузер или технический журнал.

FAQ

Можно ли сразу запустить новую генерацию, если результата не видно?

Нет. Отсутствие результата в интерфейсе не доказывает, что исходная задача не завершилась. Сначала сверяйте внутренний operation ID и локальное состояние; при неясности используйте review, а не скрытый повтор, который может создать дубль.

Подтверждает ли повторная проверка права на публикацию?

Нет. Она помогает установить локальное состояние одной задачи. Права на исходные материалы, согласие, допустимость контента и правила публикации должны проверяться отдельными процессами.

Нужно ли писать временную result URL в обычный лог?

Обычно нет. Достаточно внутреннего task ID, времени, категории исхода и версии адаптера. Временная ссылка может содержать параметры доступа; при необходимости расследования ограничьте её доступ и срок хранения.

Следующий шаг

Откройте RussiaAPI, подтвердите допустимый маршрут в своём аккаунте и выполните синтетическую проверку на staging. Затем изучите связанные материалы: Vidu API: timeout webhook и сверка статуса · Video API: идемпотентная обработка webhook · Video API: checksum результата после загрузки.