Генерация видео через Seedance работает по асинхронной модели: запрос на создание задачи возвращает только идентификатор, видео не появляется в ответе сразу. Интеграция должна сама проверять статус, обрабатывать сбои и сохранять результат до истечения ссылки.

Если писать код по синхронной логике Chat Completions, обычно тайм-аут случается уже на первом шаге. Ниже — практический порядок подключения: base URL, аутентификация, создание задачи, опрос, скачивание, callback и идемпотентность.

Примечание: Seedance, ByteDance, Doubao, Volcengine, Volcengine Ark и другие названия и товарные знаки принадлежат соответствующим правообладателям. Статья носит технический характер и не означает сотрудничество, агентские или лицензионные отношения; пути интерфейсов, имена моделей и цены определяются официальной документацией или материалами на сайте.

1. Параметры подключения: base URL, модель и аутентификация

Официальный base URL уровня данных Volcengine Ark — https://ark.cn-beijing.volces.com/api/v3, путь создания видеозадачи — /contents/generations/tasks. Аутентификация: Authorization: Bearer $ARK_API_KEY, тело запроса в JSON.

В поле model можно указать Model ID или Endpoint ID. Разница в способе аутентификации: с API-ключом обычно работают оба варианта; при подписи AK/SK, как правило, обязателен Endpoint ID, а Model ID напрямую указывать нельзя. Это одна из самых частых ловушек при миграции и диагностике.

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

Операция Метод и путь Описание
Создать задачу POST /contents/generations/tasks Возвращает ID задачи, видео не возвращает
Проверить задачу GET /contents/generations/tasks/{id} Статус и результат
Список задач GET /contents/generations/tasks Пакетная сверка и компенсация
Отменить задачу Интерфейс отмены или удаления по документации Обычно действует только для задач в очереди

Поддержка отмены, удаления и списка различается по платформам; перед подключением сверяйтесь с документацией. Не добавляйте /api/v3 повторно в конец base URL, иначе путь окажется неверным.

2. Создание задачи: что передать в POST

Ниже типичный запрос создания задачи; поля приведены только как пример:

export ARK_API_KEY="your-api-key"
export BASE_URL="https://ark.cn-beijing.volces.com/api/v3"

curl -sS -X POST "$BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
      {"type": "text", "text": "Утренний порт, погрузка контейнеров, медленный облёт с дрона, реалистичный стиль"},
      {"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}, "role": "first_frame"}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "watermark": false,
    "callback_url": "https://api.example.com/callbacks/seedance"
  }'

На что обратить внимание:

  • content — массив; текст, первый кадр, референсное изображение и референсное видео задаются разными type и role.
  • Диапазоны duration, ratio и resolution зависят от версии модели; не копируйте их из чужой документации.
  • watermark влияет на водяной знак в результате; до коммерческого использования проверьте правила платформы.
  • callback_url принимает уведомление о завершении; поддержка зависит от платформы.
  • Поля seed, camera_fixed, return_last_frame поддерживаются не всеми моделями.

После успешного создания сразу сохраните ID задачи в базу и привяжите к номеру бизнес-заказа. От этого ID зависят опрос, повторы, сверка и отнесение затрат.

3. Опрос: состояния и задержки

Для проверки задачи нужен только её ID:

curl -sS "$BASE_URL/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $ARK_API_KEY"

Типичные состояния и действия:

status Значение Рекомендация
queued В очереди Продолжать ждать, при необходимости отменить
running Генерация Продолжать опрос, не отправлять повторно
succeeded Успех Прочитать результат и сразу сохранить
failed Сбой Записать код ошибки и решить, возможен ли повтор
expired Прервано по тайм-ауту Изменить тайм-аут или параметры и отправить заново
cancelled Отменено Уточнить, не отменил ли бизнес

Не опрашивайте строго раз в секунду. Начните с 5 секунд, затем переходите к 10 и 20 секундам, с верхним пределом около 30 секунд и небольшим случайным разбросом, чтобы несколько экземпляров не били в upstream одновременно. Общий тайм-аут задайте по бизнесу, например 10 минут; после истечения помечайте задачу как требующую проверки, а не ждите бесконечно.

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

4. Скачивание и сохранение результата

После успеха в ответе будет адрес видео. Обычно он временный: в официальной документации указано около 24 часов, а некоторые модели ограничивают число скачиваний. Не передавайте этот адрес во фронтенд или клиенту как долгоживущий CDN.

Правильный порядок: получив успешный статус, сразу скачать видео, сохранить в своё объектное хранилище и записать ID задачи, номер заказа, путь объекта, размер файла и контрольную сумму. После сохранения записать внутренний адрес в бизнес-базу. Тогда даже при истечении ссылки upstream исторические заказы можно воспроизвести и передать.

При скачивании учитывайте большие файлы, докачку, лимит параллелизма и повторы. Если в ответе есть первый кадр или аудио, сохраните их отдельно по полям, а не только видео.

5. Webhook или опрос

Оба способа дают результат, разница в задержке и эксплуатационных затратах:

Способ Плюсы Минусы Сценарии
Webhook Низкая задержка, меньше лишних запросов Нужен публичный адрес, проверка подписи, защита от повторов Production-задачи
Опрос Простая реализация, не нужен публичный адрес Задержка, лишние запросы Внутренние инструменты, тесты, резерв
Гибрид Callback основной, опрос резервный Нужна дедупликация состояний Большинство production-систем

В production надёжнее «callback плюс сверка»: callback даёт низкую задержку, а периодическая задача сканирует записи, долго не приходящие в конечное состояние. Callback обязан проверять подпись и быть идемпотентным, иначе одно уведомление создаст дубликат в базе или повторно запустит downstream. Потеря callback не редкость, поэтому нельзя делать его единственным каналом уведомления.

6. Идемпотентность и повторная отправка

Видеозадача дорогая и долгая, поэтому цена повторной отправки намного выше, чем у текстового интерфейса. Контролируйте на четырёх уровнях:

  • Перед отправкой создайте бизнес-ключ идемпотентности, например номер заказа плюс версию, и сначала проверьте базу.
  • Сделайте уникальный индекс по ID задачи и номеру заказа, чтобы база блокировала дубликаты.
  • Тайм-аут запроса не равен сбою задачи. Сначала проверьте базу по ключу идемпотентности или список задач и убедитесь, что задача не создана, затем повторяйте.
  • Повторяйте только 429, 5xx и сетевые ошибки; 400 из-за параметров и отказ модерации контента повторять вслепую нельзя.

Отмену и повторную отправку тоже фиксируйте с причиной. Иначе по одному заказу может появиться несколько видео, что увеличивает расход и усложняет сверку. Рекомендуется ежедневная сверка статусов задач, затрат и артефактов.

7. Частые ошибки и диагностика

  • 401 AuthenticationError: ключ отсутствует, отозван или неверный формат заголовка; также возможно несоответствие base URL и ключа.
  • 403 AccessDenied, AccountOverdueError: недостаточно прав, задолженность или услуга не подключена.
  • 404 ModelNotOpen, UnsupportedModel: модель не открыта или ошибка в имени.
  • 400 SensitiveContentDetected: промпт или материал не прошёл модерацию; меняйте материал, а не повторяйте.
  • 400 InvalidParameter: имя поля, длительность, пропорции или разрешение вне допустимого диапазона.
  • 429 RateLimitExceeded: снизьте параллелизм и используйте экспоненциальную задержку; при необходимости запросите большую квоту.
  • failed или expired: прочитайте error.code и error.message, разделяя ошибку параметров, отказ модерации и сбой upstream.

Строки кодов ошибок могут обновляться вместе с платформой; при диагностике ориентируйтесь на фактический ответ и документацию. Записывайте в журнал исходный код, request ID и обезличенные параметры запроса — это заметно сокращает поиск.

8. Чек-лист миграции

При переходе с официального интерфейса на шлюз или между платформами проверьте по пунктам:

  1. Заменены ли base URL и способ аутентификации целиком, а не только ключ.
  2. Указан ли в model Model ID или Endpoint ID и соответствует ли это текущей аутентификации.
  3. Входят ли имена полей, длительность, пропорции и разрешение в поддерживаемый диапазон нового канала.
  4. Покрывает ли перечисление состояний очередь, выполнение, успех, сбой, тайм-аут и отмену.
  5. Проверены ли срок действия ссылки, лимит скачиваний и логика сохранения.
  6. Доступен ли callback по публичному адресу, реализованы ли проверка подписи и идемпотентность.
  7. Внедрены ли ключ идемпотентности, таблица задач, сверка и оповещения.
  8. Проведены ли нагрузочные тесты лимитов, тайм-аутов, повторов и параллелизма.

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

Частые вопросы

Seedance API возвращает видео синхронно?

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

Как долго хранятся ID задачи и результат?

По официальной документации записи задач доступны около 7 дней, а ссылка на видео действует около 24 часов. Для долгого хранения результат нужно самостоятельно перенести в объектное хранилище.

Какой интервал опроса выбрать?

Можно начать с 5 секунд и постепенно увеличить до 15–30 секунд, задав общий тайм-аут. Частый фиксированный опрос тратит запросы и повышает риск лимитов.

Поддерживается ли Webhook?

В официальном интерфейсе создания задачи есть поле callback_url, но доставка зависит от сети и политики платформы. Поддержку callback в шлюзе уточняйте по документации на сайте; в production оставляйте резервный опрос.

Списываются ли средства за неудачную задачу?

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

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

Сначала прогоните одну задачу с минимальной длительностью и низким разрешением, затем добавьте таблицу задач, опрос, сохранение и сверку. Для единого входа можно зарегистрироваться в ZSQH AI Gateway и проверить канал Seedance и тарификацию на странице цен на модели.

Что читать дальше: