Сначала ресурсы: более быстрая и надёжная передача изображений и видео

Кратко: преобразование текста в видео не затронуто и возвращает идентификатор задачи примерно за секунду. Как только запрос содержит изображение или видео, сначала загрузите медиафайл в библиотеку ресурсов, получите идентификатор ресурса asset:// и укажите его в запросе на генерацию. Размер тела запроса уменьшается с мегабайт до нескольких десятков байт, эндпоинт создания задачи отвечает немедленно, а проверка содержимого медиафайла выполняется во время загрузки.Эта страница посвящена скорости и надёжности отправки запросов. Документацию по каждому эндпоинту библиотеки ресурсов см. в разделе Библиотека ресурсов; исполняемый код для полного сценария см. в Руководстве по ссылкам на ресурсы.

Сначала определите: медленной является отправка или генерация?

Seedance — это асинхронный API на основе задач. Создание одного клипа включает два отдельных этапа, и задержка на каждом из них возникает по совершенно разным причинам:

Этап	Что вы получаете	Обычная длительность	Почему это может замедлиться
1. Отправка: `POST .../generations/tasks`	ID задачи, `{"id": "cgt-..."}`	Около секунды для преобразования текста в видео; увеличивается с размером медиафайлов, если они прикреплены	Ваши медиафайлы должны пройти через сеть до APIYI, затем быть перенаправлены в Volcengine, где они декодируются и проверяются — ID задачи возвращается только после завершения всех этих операций
2. Генерация: опрашивайте `GET .../tasks/{id}` до `succeeded`	Готовый клип, `content.video_url`	Обычно 2–5 минут (дольше для 1080p или большой длительности)	Очередь и инференс на стороне провайдера — это нормальная скорость

Эти два этапа независимы. «Отправка заняла 60 секунд» и «генерация заняла 5 минут» — это две разные проблемы, поэтому сначала определите, какой именно этап выполняется медленно, и только потом что-либо изменяйте. Столбец длительности в журнале консоли показывает время до получения первого байта, что соответствует этапу 1, а не общему времени создания клипа. См. раздел Длительность в консоли и время ожидания на стороне клиента.

Распространённая ошибка диагностики: установить тайм-аут чтения в 60 секунд для запроса с изображением, а затем считать тайм-аут признаком того, что «сервис не работает», и немедленно отправить запрос повторно. На самом деле медиафайл всё ещё передавался — повторная отправка лишь загружает те же данные ещё раз, конкурирует за ту же пропускную способность исходящего канала и может создать дублирующую задачу, за которую будет начислена плата.

Сравнение трёх способов передачи медиафайлов

Для одного и того же изображения эти три варианта ведут себя совершенно по-разному при отправке:

Метод	Размер тела запроса	Время получения ID задачи	Основной риск
Base64 / data URL, встроенные данные	Того же порядка, что и размер файла, плюс примерно треть объёма из-за кодирования — часто несколько МБ	Линейно увеличивается с размером и пропускной способностью вашего исходящего канала, а при передаче нескольких изображений это время складывается	Тайм-ауты чтения на клиенте; при каждой повторной попытке весь объём передаётся заново
Публичный URL	Небольшой, но вышестоящий сервис должен получить файл в этот момент	Зависит от скорости, с которой ваш хост отдаёт файл, и его размера	Медленный хост, хост с лимитом запросов, требующий авторизации или находящийся в другом регионе, увеличивает это время или приводит к полному сбою
ID ресурса `asset://`	Несколько десятков байт	Примерно такое же, как для обычного преобразования текста в видео	Требуется один предварительный шаг загрузки

Ни один из первых двух вариантов не определяется моделью или инференсом: они зависят от пропускной способности каналов на обоих концах и размера файла, поэтому оба варианта медленные и непредсказуемые — один и тот же код сегодня может выполняться 8 секунд, а завтра — 90 секунд. Ссылка на asset:// переносит эти затраты однократно, заранее, на этап загрузки; после этого при каждой генерации передаётся только короткая строка.

Сначала — ресурсы, а не только скорость

Время отправки не зависит от размера файла

Тело запроса содержит только промпт и ID ресурса, поэтому задержка создания задачи возвращается к уровню text-to-video, а тайм-аута клиента в 30–60 секунд достаточно.

Повторные попытки почти ничего не стоят

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

Проверки содержимого выполняются раньше

Медиаданные проверяются во время загрузки и отслеживаются до Active, поэтому любые несоответствия выявляются сразу, а не приводят к сбою задачи генерации на полпути.

Ресурсы можно использовать повторно

Загрузите ресурс один раз и используйте его без ограничений по времени — ссылка на один и тот же ID ресурса в разных сценах и эпизодах также обеспечивает более стабильное отображение персонажа.

В одном случае это обязательное требование, а не оптимизация: медиаданные с фотореалистичными человеческими лицами нельзя передавать как прямое референсное изображение (защита от дипфейков), поэтому их необходимо загрузить и указать как asset://. См. Библиотека ресурсов.

Миграция в три шага

Загрузите медиаданные и получите идентификатор ресурса

Загрузите данные через веб-интерфейс без написания кода или выполните пакетную загрузку через API — оба способа используют одну и ту же библиотеку. См. Библиотеку ресурсов. Повторяйте запрос до тех пор, пока статус не станет Active (около 13 секунд для одного изображения) и ресурс не будет готов к использованию.Библиотека ресурсов бесплатна при использовании Seedance API — без ежегодной платы.

Замените встроенные данные на asset:// в запросе на генерацию

Структура content, значения role и все остальные параметры остаются без изменений. Изменяется только значение image_url.url: вместо URL данных используется asset://<Id>. Ссылайтесь на медиаданные в промпте как на «изображение 1», «изображение 2» в порядке их передачи — не указывайте идентификатор ресурса в тексте промпта.

Сохраните идентификатор ресурса в собственной базе данных

Идентификаторы ресурсов имеют длительный срок действия, поэтому никогда не загружайте один и тот же файл дважды. Сохраняйте соответствие между локальными медиаданными и их идентификаторами ресурсов и используйте его при каждой последующей генерации.

До и после отличается ровно одно значение поля:

До: всё изображение встроено в запрос, размер тела запроса — несколько МБ

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "The person in image 1 smiles at the camera, slow push-in" },
    { "type": "image_url",
      "image_url": { "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg... (millions of characters)" },
      "role": "reference_image" }
  ],
  "ratio": "adaptive", "duration": 5, "resolution": "720p"
}

После: размер тела запроса — несколько сотен байт, идентификатор задачи возвращается сразу

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "The person in image 1 smiles at the camera, slow push-in" },
    { "type": "image_url",
      "image_url": { "url": "asset://asset-2026090200000000-abcde" },
      "role": "reference_image" }
  ],
  "ratio": "adaptive", "duration": 5, "resolution": "720p"
}

Полный готовый к запуску скрипт (загрузка, добавление в библиотеку, генерация, скачивание) см. в Руководстве по ресурсам.

Что насчёт задач с первым и последним кадром?

Первый/последний кадр (role: "first_frame" / "last_frame") и мультимодальная ссылка (role: "reference_image") — это взаимоисключающие режимы входных данных с разной семантикой, поэтому не следует бездумно заменять один другим:

Если вам действительно нужны точные начальный и конечный кадры — например, чтобы бесшовно соединить их с предыдущим клипом, — оставайтесь в режиме первого/последнего кадра и замените встроенный URL данных на публичный URL. Размер тела запроса сразу уменьшится с нескольких мегабайт до нескольких сотен байт, а оставшаяся стоимость загрузки будет перенесена на upstream. Разместите изображения где-нибудь с высокой скоростью доступа, без аутентификации и с достаточными ресурсами.
Если на самом деле вам нужен согласованный персонаж или сцена, а граничные кадры не обязаны совпадать до каждого пикселя, переключитесь на мультимодальную генерацию со ссылкой с идентификатором актива asset://. Это самый надёжный путь и тот, который рекомендуется на этой странице.

Чтобы объединить клипы в более длинное видео, не нужно самостоятельно извлекать последний кадр: передайте return_last_frame: true и получите PNG последнего кадра без водяного знака, который можно использовать как первый кадр следующей задачи.

Эталонное видео и аудио

Эталонное видео (role: "reference_video") на порядок больше изображения, поэтому встраивание Base64 — наиболее вероятная причина тайм-аута при отправке. Избегайте этого:

Используйте общедоступный URL, размещённый на быстром, не требующем аутентификации и надёжно обеспеченном ресурсом.
Группы ресурсов с верифицированной персоной поддерживают загрузку видео и аудио (видео: mp4 / mov, 2–15 секунд, менее 50 МБ; аудио: mp3 / wav, 2–15 секунд, менее 15 МБ) через процесс верификации личности в Библиотеке ресурсов.
Обратите внимание: задачи с эталонным видео относятся к более низкому ценовому уровню — $7.56 за миллион token при наличии видеовхода против $12.60 без него. См. Цены на модели в обзоре.

Что делать после тайм-аута

Если запрос POST для создания задачи завершается по тайм-ауту, клиент не может определить, была ли создана задача: заголовки ответа не поступили, поэтому отсутствует ID задачи для запроса. Действуйте в следующем порядке:

Проверьте наличие записи, прежде чем повторно что-либо отправлять

Найдите этот момент в журналах консоли APIYI или в данных о тарификации. Если запись существует, задача была создана и тарифицирована — ID задачи указан в записи, поэтому сразу опрашивайте её состояние. Только отсутствие записи означает, что запрос не был завершён. Повторная отправка вслепую создаёт дублирующиеся задачи и приводит к повторной тарификации.

Одновременно измените тайм-аут чтения и способ передачи медиафайлов

Одно лишь увеличение тайм-аута чтения устраняет только симптом. После перехода на asset:// тайм-аута 30–60 секунд для запроса создания достаточно — сам асинхронный эндпоинт работает быстро, а фактическая обработка выполняется на стороне задачи. Если необходимо и дальше встраивать большие медиафайлы непосредственно в запрос, задайте тайм-аут подключения и тайм-аут чтения отдельно, а значение тайм-аута чтения рассчитайте с учётом размеров файлов и пропускной способности исходящего канала.

Уменьшите количество параллельных запросов, прежде чем продолжать поиск причины

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

Проверьте базовый URL

Разные базовые URL используют разные сетевые маршруты, поэтому большие загрузки могут работать на них по-разному. Измерьте время отправки для каждой доступной точки доступа с собственного сервера и используйте самый быстрый вариант. Список эндпоинтов и сведения о выборе см. в разделе Настройка базового URL.

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

Часто задаваемые вопросы

Нужна ли для преобразования текста в видео также библиотека ресурсов?

Нет. Если к запросу не прикреплены медиафайлы, тело запроса содержит только промпт, эндпоинт создания задачи возвращает идентификатор задачи примерно за секунду, и всё это не применяется.

Сколько времени занимает сама обработка ресурсов? Разве это не просто перенос затрат?

Предварительная обработка одного изображения и его передача в Active занимают около 13 секунд — полностью автоматически, без ручной проверки.Суть в том, что это происходит один раз. После этого на один и тот же ресурс можно ссылаться неограниченное время, тогда как при встроенной загрузке вся передача повторяется при каждой генерации. Чем больше клипов вы создаёте, тем заметнее разница.

Истекает ли срок действия идентификаторов ресурсов?

Нет. Идентификаторы ресурсов остаются пригодными для использования в течение длительного времени, в отличие от URL готового клипа. Ресурсы привязаны к вашей учётной записи icover.ai, поэтому вы видите и используете только собственные ресурсы.

Взимается ли дополнительная плата за библиотеку ресурсов?

Нет. Она предоставляется бесплатно вместе с Seedance API — без ежегодной платы. Собственная библиотека ресурсов Volcengine — это отдельно приобретаемое дополнение для клиентов без рамочного соглашения, стоимостью в сотни тысяч CNY в год.

Как долго остаётся действительным URL сгенерированного видео?

content.video_url — это подписанная прямая ссылка, действительная в течение 24 часов. Скопируйте файл в собственное хранилище сразу после успешного выполнения задачи и не используйте этот URL как постоянный адрес.

Совпадает ли KEY библиотеки ресурсов с token Seedance?

Нет — это два разных ключа, не перепутайте их. KEY библиотеки ресурсов создаётся на icover.ai и используется только для загрузки, обработки и запроса ресурсов. Видео token Seedance APIYI создаётся на api.apiyi.com, требует выбрать группу SeeDance2 и используется только для API генерации видео.

Связанные страницы

Библиотека ресурсов

Все эндпоинты библиотеки ресурсов, веб-интерфейс без кода и проверка личности

Руководство по справочнику ресурсов

Готовые к запуску скрипты полного цикла: от загрузки и добавления до скачивания

Обзор Seedance 2.0 / 2.5

Выбор модели, цены, таблицы разрешений и часто задаваемые вопросы

Основы

Базовый API

Image API (официальный)

Video API (официальный)

API мультимодального понимания

Генерация текста

Audio API (официальный)

Поиск и безопасность

Сначала ресурсы: более быстрая и надёжная передача изображений и видео

Сначала определите: медленной является отправка или генерация?

Сравнение трёх способов передачи медиафайлов

Сначала — ресурсы, а не только скорость

Время отправки не зависит от размера файла

Повторные попытки почти ничего не стоят

Проверки содержимого выполняются раньше

Ресурсы можно использовать повторно

Миграция в три шага

Что насчёт задач с первым и последним кадром?

Эталонное видео и аудио

Что делать после тайм-аута

Часто задаваемые вопросы

Связанные страницы

Библиотека ресурсов

Руководство по справочнику ресурсов

Обзор Seedance 2.0 / 2.5

​Сначала определите: медленной является отправка или генерация?

​Сравнение трёх способов передачи медиафайлов

​Сначала — ресурсы, а не только скорость

Время отправки не зависит от размера файла

Повторные попытки почти ничего не стоят

Проверки содержимого выполняются раньше

Ресурсы можно использовать повторно

​Миграция в три шага

​Что насчёт задач с первым и последним кадром?

​Эталонное видео и аудио

​Что делать после тайм-аута

​Часто задаваемые вопросы

​Связанные страницы

Библиотека ресурсов

Руководство по справочнику ресурсов

Обзор Seedance 2.0 / 2.5

Сначала определите: медленной является отправка или генерация?

Сравнение трёх способов передачи медиафайлов

Сначала — ресурсы, а не только скорость

Миграция в три шага

Что насчёт задач с первым и последним кадром?

Эталонное видео и аудио

Что делать после тайм-аута

Часто задаваемые вопросы

Связанные страницы