Seedance API: очередь задач и лимит параллельности

Отделите локальную очередь от внешнего статуса

Сначала создайте в своём приложении запись задачи с tenant, внутренним job ID, разрешённым типом входа, версией шаблона и состоянием queued. Эта запись — источник правды для интерфейса; внешний task ID добавляется только после подтверждённого создания. Не называйте queued обещанием, что внешняя обработка уже началась. В очереди храните минимальные метаданные и ссылку на безопасное внутреннее хранилище, а не ключи, исходные cookie или полный пользовательский prompt. Такая граница помогает объяснить пользователю, где именно находится работа: ожидает локального слота, отправляется, проверяется или требует review. При перезапуске worker запись можно восстановить по внутреннему ID, не создавая новую операцию только потому, что браузер повторил форму.

Выберите лимит конкурентности как настройку приложения

Локальный limit — это не заявление о лимите Seedance или другого поставщика. Его выбирают по наблюдаемой нагрузке вашей очереди, бюджету, времени ожидания и допустимому числу незавершённых задач на tenant. Начните с малого консервативного значения, измеряйте очередность и повышайте его только после контролируемого теста. Разделяйте общий лимит процесса и справедливый лимит пользователя: иначе один tenant способен занять все worker slots. Перед запуском worker проверяет роль, доступность входного файла, максимальный размер и текущую policy. Если условие не проходит, задача получает понятный локальный код причины вместо бесконечного ожидания. Не передавайте пользователю ложную цифру «лимита API», если она не подтверждена действующим контрактом.

Добавьте ключ идемпотентности до сетевого вызова

Повтор клика, timeout браузера или перезапуск worker не должны создавать две одинаковые video-задачи. Клиент посылает одноразовый идентификатор операции, сервер сопоставляет его с tenant и безопасным хешем нормализованного входа, а затем возвращает существующий job ID. Сам сетевой вызов выполняется только после атомарной фиксации состояния creating. Если ответ не получен, задача переходит в review_pending, пока worker не сверит наблюдаемый результат с текущим контрактом. Не отправляйте запрос автоматически заново только потому, что соединение оборвалось: вы не знаете, была ли операция принята. Локальная идемпотентность не заменяет внешнюю, но заметно сокращает дубли и помогает поддержке разбирать ситуацию по одному request ID.

Опишите конечные состояния и права на retry

Полезная state machine различает queued, creating, submitted, running, completed, failed, cancelled и review_pending. Для каждого состояния определите, кто имеет право изменить его: пользователь, worker, оператор или подтверждённый callback. Retry — это отдельный переход с причиной, числом попыток и проверкой идемпотентности; он не должен быть циклом для всех 4xx/5xx. Например, валидационная ошибка входа требует исправления человеком, а краткий сетевой сбой может получить одну ограниченную повторную попытку, если операция доказуемо не была отправлена. Источник статуса всегда нужно сверять с текущей схемой, а неизвестное поле трактовать как повод для review. Пользователь видит нейтральное сообщение и ссылку на локальный job ID, а не выдуманный процент готовности.

Проверяйте callback и polling как недоверенные сигналы

Независимо от выбранного механизма callback и ответ polling нельзя принимать как команду без server-side проверки. Ограничьте источник, проверяйте формат в соответствии с текущим контрактом, сопоставляйте внешний task ID с внутренней задачей и дедуплицируйте уже обработанное событие. Не логируйте сырое тело запроса, если в нём может быть пользовательский контент или подпись. Если подпись либо схема не подтверждены, поместите событие в review_pending и сохраните только необходимый технический контекст. Polling также нуждается в ограничении частоты и deadline; бесконечный опрос повышает нагрузку и не делает статус точнее. В интерфейсе отделите «проверяем состояние» от «результат готов»: это честнее, чем обещать срок генерации или гарантировать выдачу файла.

Подготовьте UX для очереди, отмены и результата

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

Server-side пример

Пример рассчитан на Node.js 18+ и защищённый server-side запуск. В нём нет реального ключа: это логика приложения, а не текущая спецификация внешнего API. До интеграции подтвердите маршрут, схему и ограничения в документации.

export function nextTransition(job, event) {
  if (job.status === 'queued' && event.type === 'slot_available') return { status: 'creating' };
  if (job.status === 'creating' && event.type === 'accepted') return { status: 'submitted', taskId: event.taskId };
  if (event.type === 'unknown_schema' || event.type === 'timeout') return { status: 'review_pending' };
  if (event.type === 'completed') return { status: 'completed' };
  return { status: job.status };
}
// Persist the transition server-side; do not retry a possibly accepted creation blindly.

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

Граница ответственности и данных

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

Материалы для сверки

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

• Martin Fowler: идемпотентный получатель
• OWASP: безопасность REST API
• Node.js: worker_threads