Библиотека изображений Seedance

Библиотека позволяет подготовить каждое изображение отдельно и затем передавать его asset://<id> в обычном запросе POST /v1/videos. Используйте библиотеку, когда она подключена для вашего аккаунта и модели. Полученный id — ID зарегистрированного материала; дополнительный file_id не нужен.

Для библиотеки используйте seedance-2.0 или seedance-2.5, если эта возможность подключена для вашего аккаунта и ключа. Доступ к генерации видео сам по себе не означает доступ к библиотеке.

BASE_URL — HTTPS origin без /v1. Для запросов используйте BASE_URL, API_KEY и ту же модель. Файлы передавайте с вашего сервера; API-ключ не размещайте в браузере конечного пользователя.

Создайте группу

Сохраните группу для повторных загрузок. Используйте purpose: "ordinary" для обычных материалов. Создание группы само по себе не подтверждает личность или право использовать изображение человека.

curl --fail-with-body "$BASE_URL/v1/seedance/asset-groups" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reference-group-001" \
  -d '{"model":"seedance-2.5","purpose":"ordinary","name":"Референсы"}'

При подтверждённом создании возвращается HTTP 201:

{
  "object": "seedance.asset_group",
  "id": "group_ID",
  "operation_id": "op_ID",
  "status": "created"
}

Один Idempotency-Key длиной 8–128 символов используйте только для одной группы с неизменными параметрами. Повтор возвращает существующий результат; изменённые параметры с тем же ключом дают HTTP 409.

Загрузите каждое изображение отдельно

curl --fail-with-body "$BASE_URL/v1/seedance/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'model=seedance-2.5' \
  -F 'group_id=group_ID' \
  -F 'file=@reference.png'

Один запрос содержит один настоящий JPEG/PNG до 10 MiB и 36 мегапикселей. Повреждённый файл или превышение лимита сразу дают HTTP 400 с понятной причиной. Пригодность изображения для выбранной модели определяется результатом проверки.

Загрузка и одобрение — разные этапы. Ответ содержит состояние этого файла:

{
  "object": "seedance.asset",
  "id": "asset_ID",
  "operation_id": "op_ID",
  "status": "Processing",
  "ready": false
}

Точного процента прогресса и гарантированного срока проверки API не выдаёт. Показывайте отдельный статус каждого файла. Кнопку создания видео включайте после готовности всех выбранных референсов.

Проверяйте состояние и сохраняйте ID

curl --fail-with-body \
  "$BASE_URL/v1/seedance/assets/asset_ID?model=seedance-2.5" \
  -H "Authorization: Bearer $API_KEY"

В этом API поле model обязательно также при чтении статуса и удалении: используйте модель, с которой созданы группа и материал.

Для готового изображения ответ содержит status: "Active", ready: true и uri: "asset://asset_ID". Проверяйте статус с паузой, например 3 секунды, увеличивая её при HTTP 429/503. Временный сбой проверки не означает отказ.

Если ID пока не подтверждён, сохраните operation_id и опрашивайте операцию:

curl --fail-with-body \
  "$BASE_URL/v1/seedance/asset-operations/op_ID?model=seedance-2.5" \
  -H "Authorization: Bearer $API_KEY"

При submission_unknown не создавайте замену и не придумывайте ID из имени файла. Повтор той же загрузки не отправляет материал на новую регистрацию. При requires_support: true передайте operation_id поддержке.

Создайте видео с готовыми материалами

curl --fail-with-body "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"seedance-2.5",
    "prompt":"Объект из референса плавно поворачивается.",
    "seconds":"4",
    "size":"1280x720",
    "input_reference":"asset://asset_ID"
  }'

Для нескольких изображений используйте image_urls: ["asset://asset_ID"]. Для явных ролей — image_with_roles: [{"url":"asset://asset_ID","role":"reference_image"}]. Порядок изображений и роли сохраняются. Неготовые, удалённые, чужие или несовместимые материалы отклоняются. Здесь поддерживаются только image assets; audio/video assets и загрузка asset-ссылок через multipart запроса генерации не поддерживаются.

Сохраните id видео и проверяйте его обычным GET /v1/videos/{id}. Повтор запроса создания видео может создать новую задачу; не повторяйте его автоматически после таймаута. Одобрение референса не гарантирует одобрение каждого будущего видео: промпт и итоговый контент также должны соответствовать правилам.

Переиспользование и удаление

Сохраните ID в своей библиотеке и передавайте его в следующих видео. Одинаковые байты в той же группе, аккаунте и модели повторно не регистрируются, в том числе после одновременных загрузок. Изменение файла, группы или модели создаёт другой контекст; совместимость между моделями не предполагается.

Библиотека ограничена аккаунтом, группой, моделью и подключением. Разные ключи могут видеть один материал только при совпадении этих условий. Если ваше приложение обслуживает нескольких пользователей, ваш сервер должен хранить принадлежность групп/материалов и проверять доступ пользователя к ним.

curl --fail-with-body -X DELETE \
  "$BASE_URL/v1/seedance/assets/asset_ID?model=seedance-2.5" \
  -H "Authorization: Bearer $API_KEY"

После ответа deleted: true материал больше нельзя использовать через API. Это не удаляет ранее созданные видео и не подтверждает удаление всех копий исходного файла. Повторная загрузка того же удалённого материала в ту же группу не восстанавливает его; используйте новую группу, если повторная регистрация действительно нужна и разрешена.

HTTP 403 означает отсутствие доступа, 404 — отсутствующий или недоступный материал, 409 — неготовый материал либо конфликт ключа, 429 — временный лимит, 503 — недоступность проверки. Для поддержки достаточно модели, времени, HTTP-статуса и operation_id/id; API-ключ и секретные ссылки не отправляйте.