- Нужны аккаунт BytePlus, доступ к модели, настроенный биллинг и ключ для авторизации.
- Отделяйте создание задания от получения результата.
- Для текстового ролика используйте endpoint создания видеозадания.
- Статус проверяется отдельным запросом к API получения видеозадачи.
- После успешного POST-запроса сохраните полученный ID задачи.
Seedance API нужен, когда видео создают из сайта, корпоративной панели или собственного приложения. В отличие от ручной генерации через браузер здесь важно управлять очередью задач, отслеживать расходы и вовремя сохранять готовые файлы. Для подключения используется инфраструктура BytePlus ModelArk. Ниже — последовательность, которую можно положить в основу минимальной интеграции.
Что подготовить перед первым вызовом
Нужны аккаунт BytePlus, доступ к модели, настроенный биллинг и ключ для авторизации. Условия активации Seedance 2.5 могут включать требования к балансу или пакету; проверьте их в своём кабинете. API-расходы не равны стоимости подписки Dreamina. Разрабатывайте сначала на тестовом проекте с лимитом бюджета и отдельным API-ключом.
Секретный ключ храните на сервере, в переменной окружения или менеджере секретов. Не вставляйте его в JavaScript на странице сайта и не отправляйте в браузер пользователю. Если клиентская форма запускает генерацию, она должна обращаться к вашему серверу, а сервер уже к BytePlus.
Как устроен цикл задачи
- Сервер получает запрос пользователя и проверяет его допустимость.
- Приложение отправляет задание в API генерации и получает идентификатор.
- Очередь сохраняет ID, модель, стоимость проекта и статус обработки.
- Фоновый обработчик периодически проверяет статус по ID.
- После успешного завершения сервер сохраняет видео в собственное хранилище.
- Пользователь получает ссылку на ваш файл, а не временный адрес сервиса.
Отделяйте создание задания от получения результата. Генерация занимает время, поэтому синхронный HTTP-запрос из страницы до финального файла ненадёжен: браузер может закрыться, а серверный таймаут истечь.
Пример запроса к BytePlus
Для текстового ролика используйте endpoint создания видеозадания. Пример ниже демонстрирует структуру задания для Seedance 2.5. Перед запуском укажите доступную вашему аккаунту модель и региональный адрес API.
Задайте на сервере переменную ARK_BASE_URL для API-хоста своего региона и ARK_API_KEY для авторизации.
curl -X POST "$ARK_BASE_URL/api/v3/contents/generations/tasks" \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $ARK_API_KEY' \
-d '{
"model": "dreamina-seedance-2-5-260628",
"content": [
{"type":"text","text":"A ceramic cup on a desk. Slow camera push in, soft morning light, five seconds."}
],
"duration": 5,
"ratio": "16:9",
"resolution": "480p",
"generate_audio": true
}'
Ответ содержит данные задачи, в том числе идентификатор для дальнейшего опроса. Сохраняйте его в базе вместе с пользователем и идентификатором своего заказа. При отказе из-за параметров исправляйте запрос, а не повторяйте его без изменений.
Получение статуса и обработка результата
Статус проверяется отдельным запросом к API получения видеозадачи. Когда он указывает на успешное завершение, скачайте файл из поля результата и сохраните под собственным именем. Для BytePlus срок доступности выдаваемого URL ограничен 24 часами. Поэтому не оставляйте временную ссылку единственной копией видео. Учитывайте также срок жизни идентификатора задания.
На сервере храните статус created, running, succeeded или failed в соответствии с фактическими кодами API, время последней проверки, текст ошибки и путь к сохранённому результату. Устанавливайте максимальное число повторов и паузу между проверками, чтобы не перегружать API.
Пример получения статуса и адреса готового видео
После успешного POST-запроса сохраните полученный ID задачи. Для проверки используйте GET к тому же региональному хосту. Пример ниже исполняется из серверного терминала при заданных переменных ARK_BASE_URL, ARK_API_KEY и VIDEO_TASK_ID:
curl -sS -X GET "$ARK_BASE_URL/api/v3/contents/generations/tasks/$VIDEO_TASK_ID" \
-H "Authorization: Bearer $ARK_API_KEY"
Отслеживайте поле статуса. Для завершённой задачи API возвращает адрес в content.video_url; скачивайте файл на сервер и связывайте его с внутренним ID заказа. Адрес готового файла действует ограниченное время — 24 часа, поэтому внешний URL не годится как постоянная ссылка для посетителей сайта.
Типичный порядок обработки на сервере: создать запись заказа → отправить задачу → сохранить полученный ID → проверять статус с ограниченным интервалом → скачать готовый файл → сохранить путь к собственной копии → показать результат пользователю. При отказе запишите код ошибки, но не логируйте ключ или приватные медиафайлы. Если API отвечает ошибкой 429, применяйте контролируемую очередь и повтор с увеличением задержки.
Для режимов редактирования и продления проверяйте специальный параметр omni_reference_task_type и связанные ограничения: пример text-to-video нельзя без изменений переносить на задание с видеореференсом. Подробная расшифровка типичных отказов есть в статье об ошибках Seedance.
Лимиты и ошибки, которые важны в продакшене
| Ситуация | Реакция системы |
|---|---|
| 429 Too Many Requests | Очередь, задержка и повтор с ограничением частоты |
| Некорректный файл | Валидация до отправки в API |
| Недостаточно средств | Остановить новые задачи и уведомить владельца |
| Ошибка обработки | Сохранить ID и описание для диагностики |
| Временная ссылка истекла | Хранить файлы у себя после получения |
Ограничения частоты создания заданий и параллельного выполнения различаются для разных типов аккаунтов. Не зашивайте числовые лимиты навсегда в код: храните действующие значения в конфигурации продукта. Не стоит запускать новый запрос после сетевого таймаута, пока не выяснено, создалась ли предыдущая задача: иначе можно получить две платные генерации.
Как контролировать расходы и данные пользователей
Добавьте максимальный бюджет на пользователя и проект, отдельный лимит длительности ролика, журнал списаний и блокировку повторного нажатия кнопки. До отправки проверяйте тип и размер файлов. Для исходных фотографий клиентов установите срок хранения, правила удаления и доступ по ролям. Если изображение содержит персональные данные, оцените законность передачи поставщику и применимое соглашение об обработке данных.
Расходы зависят от токенов, длительности, разрешения и входных материалов. Финансовую модель разбирает статья о стоимости Seedance. Правила использования результата и договорные риски — материал о Seedance для бизнеса.
Важный нюанс тестового доступа
Условия BytePlus ModelArk Playground могут ограничивать использование результатов личными некоммерческими целями. До вывода проекта в продакшен проверяйте условия именно купленного API-продукта, а не переносите права из тестовой среды на коммерческую интеграцию.