> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Сначала ресурсы: более быстрая и надёжная передача изображений и видео
> Когда вызов Seedance содержит изображения или видео, эндпоинту create-task могут потребоваться десятки секунд для возврата идентификатора задачи — или клиент может получить тайм-аут. Сначала загрузите медиафайлы, получите идентификатор asset:// и вместо этого укажите его: размер тела запроса сокращается с мегабайт до нескольких десятков байт, отправка выполняется немедленно, а проверки содержимого переносятся на этап загрузки. Включает разбор задержки, рекомендации на случай тайм-аута и шаги миграции.
**Кратко**: преобразование текста в видео не затронуто и возвращает идентификатор задачи примерно за секунду. **Как только запрос содержит изображение или видео, сначала загрузите медиафайл в библиотеку ресурсов, получите идентификатор ресурса `asset://` и укажите его в запросе на генерацию.** Размер тела запроса уменьшается с мегабайт до нескольких десятков байт, эндпоинт создания задачи отвечает немедленно, а проверка содержимого медиафайла выполняется во время загрузки.
Эта страница посвящена скорости и надёжности **отправки запросов**. Документацию по каждому эндпоинту библиотеки ресурсов см. в разделе [Библиотека ресурсов](/ru/api-capabilities/seedance2/asset-library); исполняемый код для полного сценария см. в [Руководстве по ссылкам на ресурсы](/ru/api-capabilities/seedance2/asset-reference).
## Сначала определите: медленной является отправка или генерация?
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, а не общему времени создания клипа. См. раздел [Длительность в консоли и время ожидания на стороне клиента](/ru/faq/log-duration-vs-client-wait).
**Распространённая ошибка диагностики**: установить тайм-аут чтения в 60 секунд для запроса с изображением, а затем считать тайм-аут признаком того, что «сервис не работает», и немедленно отправить запрос повторно. На самом деле медиафайл всё ещё передавался — повторная отправка лишь загружает те же данные ещё раз, конкурирует за ту же пропускную способность исходящего канала и может создать дублирующую задачу, за которую будет начислена плата.
## Сравнение трёх способов передачи медиафайлов
Для одного и того же изображения эти три варианта ведут себя совершенно по-разному при отправке:
| Метод | Размер тела запроса | Время получения ID задачи | Основной риск |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Base64 / data URL, встроенные данные** | Того же порядка, что и размер файла, плюс примерно треть объёма из-за кодирования — часто несколько МБ | Линейно увеличивается с размером и **пропускной способностью вашего исходящего канала**, а при передаче нескольких изображений это время складывается | Тайм-ауты чтения на клиенте; при каждой повторной попытке весь объём передаётся заново |
| **Публичный URL** | Небольшой, но вышестоящий сервис должен получить файл в этот момент | Зависит от **скорости, с которой ваш хост отдаёт файл**, и его размера | Медленный хост, хост с лимитом запросов, требующий авторизации или находящийся в другом регионе, увеличивает это время или приводит к полному сбою |
| **ID ресурса `asset://`** | Несколько десятков байт | Примерно такое же, как для обычного преобразования текста в видео | Требуется один предварительный шаг загрузки |
Ни один из первых двух вариантов не определяется моделью или инференсом: **они зависят от пропускной способности каналов на обоих концах и размера файла, поэтому оба варианта медленные и непредсказуемые** — один и тот же код сегодня может выполняться 8 секунд, а завтра — 90 секунд. Ссылка на `asset://` переносит эти затраты **однократно, заранее**, на этап загрузки; после этого при каждой генерации передаётся только короткая строка.
## Сначала — ресурсы, а не только скорость
Тело запроса содержит только промпт и ID ресурса, поэтому задержка создания задачи возвращается к уровню text-to-video, а тайм-аута клиента в 30–60 секунд достаточно.
Повторный запуск с другим промптом, соотношением сторон или длительностью повторно отправляет несколько десятков байт вместо нескольких мегабайт медиаданных.
Медиаданные проверяются во время **загрузки** и отслеживаются до `Active`, поэтому любые несоответствия выявляются сразу, а не приводят к сбою задачи генерации на полпути.
Загрузите ресурс один раз и используйте его без ограничений по времени — ссылка на один и тот же ID ресурса в разных сценах и эпизодах также обеспечивает более стабильное отображение персонажа.
В одном случае это **обязательное требование**, а не оптимизация: медиаданные с фотореалистичными человеческими лицами нельзя передавать как прямое референсное изображение (защита от дипфейков), поэтому их необходимо загрузить и указать как `asset://`. См. [Библиотека ресурсов](/ru/api-capabilities/seedance2/asset-library).
## Миграция в три шага
Загрузите данные через веб-интерфейс без написания кода или выполните пакетную загрузку через API — оба способа используют одну и ту же библиотеку. См. [Библиотеку ресурсов](/ru/api-capabilities/seedance2/asset-library). Повторяйте запрос до тех пор, пока статус не станет `Active` (около 13 секунд для одного изображения) и ресурс не будет готов к использованию.
Библиотека ресурсов **бесплатна при использовании Seedance API — без ежегодной платы**.
Структура `content`, значения `role` и все остальные параметры остаются без изменений. Изменяется только значение `image_url.url`: вместо URL данных используется `asset://`. Ссылайтесь на медиаданные в промпте как на «изображение 1», «изображение 2» в порядке их передачи — **не указывайте идентификатор ресурса в тексте промпта**.
Идентификаторы ресурсов имеют длительный срок действия, поэтому никогда не загружайте один и тот же файл дважды. Сохраняйте соответствие между локальными медиаданными и их идентификаторами ресурсов и используйте его при каждой последующей генерации.
До и после отличается ровно одно значение поля:
```json До: всё изображение встроено в запрос, размер тела запроса — несколько МБ theme={null}
{
"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"
}
```
```json После: размер тела запроса — несколько сотен байт, идентификатор задачи возвращается сразу theme={null}
{
"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"
}
```
Полный готовый к запуску скрипт (загрузка, добавление в библиотеку, генерация, скачивание) см. в [Руководстве по ресурсам](/ru/api-capabilities/seedance2/asset-reference).
## Что насчёт задач с первым и последним кадром?
Первый/последний кадр (`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 МБ) через процесс верификации личности в [Библиотеке ресурсов](/ru/api-capabilities/seedance2/asset-library).
* Обратите внимание: задачи с эталонным видео относятся к **более низкому ценовому уровню** — \$7.56 за миллион token при наличии видеовхода против \$12.60 без него. См. [Цены на модели в обзоре](/ru/api-capabilities/seedance2/overview).
## Что делать после тайм-аута
Если запрос POST для создания задачи завершается по тайм-ауту, **клиент не может определить, была ли создана задача**: заголовки ответа не поступили, поэтому отсутствует ID задачи для запроса. Действуйте в следующем порядке:
Найдите этот момент в журналах консоли APIYI или в данных о тарификации. **Если запись существует, задача была создана и тарифицирована** — ID задачи указан в записи, поэтому сразу опрашивайте её состояние. Только отсутствие записи означает, что запрос не был завершён. Повторная отправка вслепую создаёт дублирующиеся задачи и приводит к повторной тарификации.
Одно лишь увеличение тайм-аута чтения устраняет только симптом. После перехода на `asset://` тайм-аута **30–60 секунд** для запроса создания достаточно — сам асинхронный эндпоинт работает быстро, а фактическая обработка выполняется на стороне задачи. Если необходимо и дальше встраивать большие медиафайлы непосредственно в запрос, задайте тайм-аут подключения и тайм-аут чтения **отдельно**, а значение тайм-аута чтения рассчитайте с учётом размеров файлов и пропускной способности исходящего канала.
Несколько параллельных запросов создания с большими медиафайлами используют один и тот же исходящий канал, из-за чего каждый запрос завершается по тайм-ауту ровно по истечении заданного значения. Сначала добейтесь успешного выполнения одного запроса, затем постепенно увеличивайте количество параллельных запросов.
Разные базовые URL используют разные сетевые маршруты, поэтому большие загрузки могут работать на них по-разному. Измерьте время отправки для каждой доступной точки доступа с собственного сервера и используйте самый быстрый вариант. Список эндпоинтов и сведения о выборе см. в разделе [Настройка базового URL](/ru/faq/base-url-config).
Общие сведения об устранении проблем с тайм-аутами — о том, каким должно быть значение тайм-аута клиента и как определить проблемный уровень, — см. в разделе [Как избежать тайм-аутов API](/ru/faq/timeout-configuration).
## Часто задаваемые вопросы
Нет. Если к запросу не прикреплены медиафайлы, тело запроса содержит только промпт, эндпоинт создания задачи возвращает идентификатор задачи примерно за секунду, и всё это не применяется.
Предварительная обработка одного изображения и его передача в `Active` занимают около 13 секунд — полностью автоматически, без ручной проверки.
Суть в том, что **это происходит один раз**. После этого на один и тот же ресурс можно ссылаться неограниченное время, тогда как при встроенной загрузке вся передача повторяется **при каждой** генерации. Чем больше клипов вы создаёте, тем заметнее разница.
Нет. Идентификаторы ресурсов остаются пригодными для использования в течение длительного времени, в отличие от URL готового клипа. Ресурсы привязаны к вашей учётной записи icover.ai, поэтому вы видите и используете только собственные ресурсы.
Нет. Она **предоставляется бесплатно вместе с Seedance API — без ежегодной платы**. Собственная библиотека ресурсов Volcengine — это отдельно приобретаемое дополнение для клиентов без рамочного соглашения, стоимостью в сотни тысяч CNY в год.
`content.video_url` — это подписанная прямая ссылка, действительная в течение **24 часов**. Скопируйте файл в собственное хранилище сразу после успешного выполнения задачи и не используйте этот URL как постоянный адрес.
Нет — это два разных ключа, не перепутайте их. **KEY библиотеки ресурсов** создаётся на icover.ai и используется только для загрузки, обработки и запроса ресурсов. **Видео token Seedance APIYI** создаётся на api.apiyi.com, требует выбрать группу `SeeDance2` и используется только для API генерации видео.
## Связанные страницы
Все эндпоинты библиотеки ресурсов, веб-интерфейс без кода и проверка личности
Готовые к запуску скрипты полного цикла: от загрузки и добавления до скачивания
Выбор модели, цены, таблицы разрешений и часто задаваемые вопросы