Seedance API: allowlist параметров видео до постановки задачи

Allowlist — это договор вашего приложения

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

Храните allowlist рядом с контрактным тестом: дата проверки, владелец, использованный адаптер и действие при ошибке. Если клиент отправил неизвестное поле, верните безопасную ошибку до внешнего запроса. Не игнорируйте поле молча: пользователь решит, что настройка применена, хотя продукт не имеет оснований это подтверждать.

Валидируйте форму и связи полей

Проверка типа недостаточна. Строка может быть слишком длинной, число — вне локального диапазона, а комбинация параметров — неразрешённой для вашего интерфейса. Опишите зависимости явно: какие поля обязательны вместе, какие взаимоисключающие и какие доступны только после ручного review. Это правило приложения, а не описание возможностей поставщика.

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

Фиксируйте дату и тестовую матрицу

Перед разрешением нового параметра выполните маленькую синтетическую матрицу: корректное значение, неверный тип, граничный размер и недопустимая комбинация. Сохраните только нормализованный исход и дату, без исходного медиа или prompt. Если тест не завершился однозначно, параметр не добавляется в production allowlist.

Не публикуйте статическую таблицу «всех параметров Seedance», когда у вас нет текущего подтверждения. Каталог и контракт меняются. Пользователю полезнее увидеть понятное ограничение продукта и следующий безопасный шаг, чем получить неподтверждённое поле, которое потом исчезнет или изменит смысл без rollback.

Обрабатывайте неизвестные значения как review

Неизвестное поле не нужно преобразовывать в ближайшее известное значение: это меняет пользовательское намерение и создаёт спорный результат. Верните код приложения вроде parameter_not_allowed, покажите краткое сообщение и предложите поддержку или review. Для рискованного изменения не повторяйте задачу автоматически и не добавляйте поле в allowlist на основании одного инцидента.

Если параметр проходит review, обновите policy отдельным изменением, добавьте тест и укажите дату. Так команда понимает, почему значение появилось, а будущий rollback не зависит от памяти одного разработчика. Журналируйте лишь категорию отказа и внутренний request ID, не весь исходный объект.

Проверьте boundary перед релизом

На staging проверьте лишнее поле, неверный тип, устаревшую policy, повтор одного request ID и отказ очереди. Все сценарии должны завершаться до сетевого вызова или идти на review. Это особенно важно для видео: непонятный параметр не должен незаметно запускать новую обработку или менять ожидание пользователя.

Читайте также генерацию видео через Seedance API, асинхронные video API задачи и dead-letter очередь для видео. Эти ссылки дают инженерный контекст, но не подтверждают внешний набор параметров.

Сначала зафиксируйте границу решения

Название модели, 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 validateVideoParams(input, policy) {
  const allowed = policy?.allowed || {};
  if (!input || typeof input !== 'object') return { ok: false, code: 'invalid_input' };
  for (const key of Object.keys(input)) if (!(key in allowed)) return { ok: false, code: 'parameter_not_allowed', key };
  for (const [key, rule] of Object.entries(allowed)) if (key in input && typeof input[key] !== rule.type) return { ok: false, code: 'invalid_parameter_type', key };
  return { ok: true, value: Object.fromEntries(Object.keys(allowed).filter((key) => key in input).map((key) => [key, input[key]])) };
}

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

Источники для дальнейшей проверки

• JSON Schema validation specification
• OWASP Input Validation Cheat Sheet

Ссылки дают общий инженерный контекст. Перед production-изменением сопоставьте их со своим договором, текущим каталогом RussiaAPI и тестом конкретного маршрута.

FAQ

Читайте также

• Генерация видео через Seedance API
• Асинхронные задачи video API
• Dead-letter очередь для видео