Seedance — модель генерации видео от ByteDance, которую часто используют для рекламных материалов, коротких роликов для электронной коммерции и раскадровок. Её API устроен совсем не как у текстовых моделей: один запрос не возвращает видео сразу — сначала создаётся задача, затем опрашивается статус и только потом скачивается результат. Если писать код по аналогии с Chat Completions, обычно спотыкаются уже на первом шаге.

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

Примечание: Seedance, Doubao, Volcano Engine и другие названия — товарные знаки их правообладателей; статья носит технический характер. Пути интерфейсов и имена моделей в примерах приведены только для демонстрации; перед реальным вызовом сверьте их с официальной или сайтовой документацией. Цены смотрите на странице тарифов.

1. Для чего подходит Seedance API

  • Видео с показом товаров для электронной коммерции и главных изображений;
  • черновики рекламных материалов для лент и коротких видео;
  • раскадровки, концепт-ролики и тесты стиля;
  • вертикальный контент для социальных сетей;
  • превью для игр и анимации.

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

2. Базовый процесс асинхронной задачи

Прочитать конфигурацию → аутентификация → отправить задачу генерации → получить task_id
        → опрашивать статус (в очереди / выполняется / успех / ошибка)
        → успех: скачать видео или получить временный URL
        → ошибка: прочитать код и решить, повторять или отказаться

По сравнению с текстовым интерфейсом у видеозадач есть три дополнительных издержки: время в очереди, повторные попытки и хранение результатов. Их нужно заложить в архитектуру, иначе после запуска появятся «тайм-аут запроса, хотя задача ещё выполняется» и «повторная отправка привела к двойному списанию».

3. Аутентификация и подготовка

  1. Проверьте канал: доступна ли возможность Seedance в документации на сайте, какие модели, длительности и разрешения поддерживаются.
  2. Создайте ключ: в консоли заведите отдельный ключ с именем seedance-test или seedance-prod.
  3. Уточните имя модели: скопируйте его со страницы цен или из документации, не восстанавливайте суффикс версии по памяти.
  4. Определите способ уведомления: одни каналы поддерживают webhook, другие — только опрос.
  5. Подготовьте материалы: первый кадр и референсные изображения заранее разместите по общедоступному URL или загрузите согласно документации.
  6. Задайте бюджет: установите лимит для тестового ключа, чтобы отладка не привела к крупному счёту.

Аутентификация обычно выполняется через Authorization: Bearer <API_KEY>, но часть платформ использует подпись AK/SK или временный токен. Ориентируйтесь на фактическую документацию и не переносите способ аутентификации одной платформы на другую.

4. Пример постановки задачи

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

export SEEDANCE_API_KEY="ваш-ключ"
export BASE_URL="https://ваш-шлюз-или-официальный-адрес"

curl -X POST "$BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-video",
    "content": [
      {"type": "text", "text": "Улица Шанхая после дождя, медленный наезд камеры, кинематографично, 16:9"},
      {"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "watermark": false
  }'

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

5. Опрос статуса и скачивание

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

Типичные статусы: в очереди, выполняется, успешно, ошибка. Рекомендации:

  • Начинайте с интервала опроса 5 секунд и постепенно увеличивайте до 15–30 секунд;
  • Задайте общий тайм-аут, например 10 минут; по истечении помечайте задачу ошибкой, а не ждите бесконечно;
  • URL видео в успешном ответе обычно имеет срок действия — сразу переносите файл в собственное объектное хранилище;
  • Для неудачных задач сохраняйте код ошибки и параметры запроса для последующего разбора.

6. Ключевые параметры

Параметр Назначение Практический совет
prompt / text Описание сцены, действия, камеры и стиля Сначала субъект, затем камера и свет
Первый кадр Управление начальным изображением Берите чёткое изображение без спорных прав
duration Длительность видео Сначала тестируйте минимальное значение
resolution Разрешение Для тестов низкое, для финала повышайте
ratio Соотношение сторон Для вертикальной ленты выбирайте 9:16
seed Случайное зерно Фиксируйте для сравнения параметров
watermark Наличие водяного знака До коммерческого использования проверьте правила платформы

Имена параметров на разных платформах могут отличаться: где-то image, где-то image_url, а длительность может передаваться строкой. Ориентируйтесь на документацию и не копируйте тело запроса другой платформы.

7. Чек-лист перед запуском

  1. Проходит ли аутентификация и перехватывается ли 401.
  2. Успешно ли выполняется задача с минимальной длительностью и разрешением.
  3. Стабильно ли возвращается идентификатор задачи и можно ли по нему получить статус.
  4. Заданы ли тайм-аут опроса и максимальное число повторов.
  5. Читаема ли причина ошибки, различаются ли отказ модерации и системная ошибка.
  6. Проверены ли срок действия URL результата и логика переноса в хранилище.
  7. Совпадает ли тарификация с ожидаемой и списываются ли деньги за неудачные задачи.
  8. Не срабатывает ли ограничение скорости при параллельной отправке.

8. Как оценить стоимость

Видео обычно стоит значительно дороже текста, поэтому при оценке недостаточно смотреть только на цену за единицу:

Стоимость одного ролика =
  цена × длительность × коэффициент разрешения
+ стоимость повторов
+ хранение и трафик
+ время ручной проверки

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

9. Модерация и риски авторских прав

  • Право на изображение: для загрузки фото реального человека или генерации узнаваемого лица нужно разрешение.
  • Авторское право: референсы, стиль, музыка и товарные знаки могут принадлежать третьим лицам.
  • Политика контента: насилие, порнография, нарушения закона и дезинформация приводят к отказу или удалению.
  • Ложная реклама: не создавайте материалы, показывающие товар не соответствующим действительности.
  • Безопасность данных: загруженные изображения и видео могут содержать данные клиентов; соблюдайте обезличивание и сроки хранения.
  • Коммерческое использование: возможность зависит от условий платформы и прав на ваши материалы.

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

10. Рекомендации по стабильности

  • Храните таблицу задач с временем отправки, статусом, длительностью и стоимостью;
  • Разделяйте отправку и опрос, чтобы один запрос не ждал синхронно несколько минут;
  • Для 429 и 5xx применяйте экспоненциальную задержку, а при ошибках параметров 4xx не повторяйте вслепую;
  • Подготовьте резервный канал или модель: в пиковые часы видеоканал может ставить задачи в очередь;
  • Отслеживайте долю успеха, P95 времени выполнения и стоимость одного ролика, сверяйте ежедневно.

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

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

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

Можно ли вызывать сервис напрямую из Китая?

Зависит от канала, аккаунта и требований комплаенса. Перед использованием проверьте условия обслуживания, политику контента и местное законодательство.

Сколько времени занимает генерация одного видео?

На это влияют очередь, длительность, разрешение и загрузка вышестоящего сервиса: типичны сроки от десятков секунд до нескольких минут. В производстве обязательно задавайте тайм-аут и повторы.

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

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

Можно ли использовать своё изображение как первый кадр?

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

Что дальше

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

Похожие материалы: