Vidu API: обработка неуспешной задачи без бесконечных повторов

Практические особенности сценария

Ошибка transport, timeout или ответ с временным кодом не доказывают, что задача не была принята. Сначала найдите свой request_id и внутренний operation_id, затем запросите состояние по документированному маршруту. Если состояние известно, покажите пользователю его вместо нового запуска. Если состояние неизвестно, применяйте короткое окно проверки и явно ограниченное число попыток, зафиксированных в политике приложения.

Полезно различать invalid_input, access_denied, quota_exceeded, temporary_unavailable и upstream_unknown. Пользовательский текст должен объяснять следующий шаг без URL поставщика, заголовков Authorization, тела внешней ошибки или внутренних правил маршрутизации. Техническая запись содержит время, tenant, размер запроса, версию adapter и безопасный код причины — не полный prompt, изображение, ключ или cookie.

Повтор допустим только после определения семантики операции. Для генерации медиа повтор может создать отдельную задачу и расходы, поэтому клиент не должен самостоятельно менять request_id. Сервер хранит ключ операции и связывает новые попытки с предыдущими наблюдениями. Если договорённая идемпотентность не подтверждена для актуального endpoint, относитесь к повтору как к новому действию и запрашивайте понятное решение пользователя или workflow.

Для диагностики подготовьте синтетический тест: короткий разрешённый prompt, минимальные параметры и test tenant. Проверьте пустой вход, слишком большой вход, неизвестную модель, отмену, временную ошибку и повтор того же request_id. Убедитесь, что ни один ответ, журнал или алерт не раскрывает секрет. Успешный smoke test показывает только поведение в момент проверки, а не постоянную доступность или качество генерации.

В production измеряйте долю unknown-состояний, длительность ожидания, частоту повторов и число дублей по tenant. При росте ошибок выключайте маршрут feature flag, сохраняйте минимальную техническую трассу и возвращайтесь к прозрачному статусу ожидания. Не обещайте, что retry всегда исправит задачу: причина может быть в данных, правах, лимите, контракте или внешней инфраструктуре.

Короткий ответ и граница сценария

Для создания видео-задачи используйте один server-side adapter, собственный request_id и явную политику приложения. Не переносите в клиент ключ, URL внешнего поставщика, model ID или право принимать решение. Vidu в этой статье — название поискового сценария; фактические возможности RussiaAPI, поля и доступ проверяют перед запуском.

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

Проверяйте вход на сервере

Клиент может передать неполные, ошибочные или намеренно изменённые данные. Поэтому backend получает аутентификацию и tenant из своей сессии, ограничивает тип, размер и допустимые поля, а затем формирует минимальный запрос для создания видео-задачи. Секрет хранится только в окружении server-side процесса.

Не логируйте исходный материал, ключ, cookie, Authorization или полный ответ внешней системы. Для поддержки обычно достаточно request_id, tenant, размера, времени, версии adapter и безопасного класса результата. Доступ к этим данным отделяйте от права пользователя запускать операцию.

Версионируйте контракт и тесты

Сохраните версию правила, схему запроса и дату сверки с текущей документацией. Новое обязательное поле, изменение статуса или model ID сначала проверяйте на test tenant. Fixture должен быть синтетическим и обезличенным; в репозиторий не попадают реальные файлы, credentials или временные ссылки.

Добавьте позитивный и негативный набор: корректный минимальный вход, пустое поле, неизвестный параметр, отсутствие прав, слишком большой файл или текст, повтор request_id и временная ошибка. Тест проверяет свой контракт приложения, а не заявляет постоянную характеристику внешней модели.

Состояния, повторы и отмена

Отделяйте принятие запроса от завершения создания видео-задачи. Внутренние состояния queued, processing, completed, failed и unknown помогают показать честный статус, даже если внешний API меняет названия полей. Не транслируйте наружу сырой текст ошибки или конфигурацию адаптера.

Повтор ограничивают по времени и числу попыток. Перед новым действием сервер проверяет предыдущий operation_id, потому что timeout не доказывает отсутствие побочного эффекта. Если документированный контракт не подтверждает идемпотентность, новый запуск рассматривается как отдельное действие и требует безопасной политики.

Наблюдаемость без лишних данных

Измеряйте только то, что помогает управлять качеством workflow: класс ошибки, длительность, количество отмен, долю неизвестных статусов и повторов. Связывайте данные с request_id, а не с содержимым материала. Метрики не публикуйте как обещание SLA, доступности или точности.

Перед production включайте feature flag для малого test tenant и заранее определяйте условие отката. При аномалии выключите маршрут, сохраните минимальную техническую трассу и вернитесь к контролируемому ручному процессу. Это безопаснее, чем скрыто менять параметры или бесконечно повторять запросы.

Server-side пример

Пример показывает локальную проверку на сервере. Ключи берутся только из окружения; перед запуском подтвердите маршрут, model ID и параметры в актуальном каталоге RussiaAPI.

export function nextAction({ state, attempts }) {
  if (state === 'completed' || state === 'processing') return { action: 'show_status' };
  if (state === 'invalid_input' || state === 'access_denied') return { action: 'stop' };
  if (state === 'temporary_unavailable' && attempts < 2) return { action: 'recheck_later' };
  return { action: 'manual_review' };
}
// Persist request_id and operation_id server-side. Confirm actual status fields in current docs.

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