Руководство
Учебник по API seedance-2.5-flash для генерации видео из изображения: curl и Python Requests
Практическое руководство по интеграции для разработчиков: структура запроса, входные данные первого/последнего кадра, асинхронный опрос и устранение ошибок
На этой странице
Что на самом деле делает вызов генерации видео из изображения
Прежде чем писать первую строку кода, полезно понять, что API делает на другой стороне. Вызов seedance-2.5-flash/image-to-video — это не синхронный запрос, блокирующий выполнение до возврата видеофайла. Это двухэтапный асинхронный рабочий процесс: вы отправляете задачу, затем опрашиваете её результат.
Этап отправки
Вы отправляете POST-запрос с входным изображением и настройками генерации. API проверяет тело запроса, ставит задачу в очередь и немедленно возвращает ответ, содержащий идентификатор задачи и начальный статус. Этот процесс быстрый — обычно мгновенный — поскольку на данном этапе ещё не отрендерено ни одного пикселя. Ваша задача — захватить этот идентификатор и сохранить его.
Этап рендеринга
Генерация происходит в фоновом режиме. В зависимости от длины фрагмента и настроек это может занять значительное реальное время. В течение этого окна не ожидайте, что конечный URL видео уже будет доступен. Вместо этого следует запрашивать статус задачи.
Этап результата
В конечном итоге задача достигает терминального состояния: либо успех с загружаемым видеоартефактом, либо ошибка с сообщением для диагностики. Как только достигнуто терминальное состояние, опрос следует прекратить.
Почему это важно для вашего кода
Поскольку модель асинхронна, наиболее распространённые ошибки интеграции носят архитектурный, а не синтаксический характер: предположение, что первый ответ уже содержит видео, ожидание с фиксированным интервалом вместо опроса поля статуса, а также неспособность отличить временное состояние processing от окончательной ошибки. Весь учебник построен вокруг чистого цикла «отправить → опросить → выйти», поэтому держите эти три этапа в уме при чтении.
Предварительные требования и структура запроса
Что нужно подготовить перед первым вызовом
- Учётные данные API. Ваш ключ HiAPI API, отправляемый с каждым запросом. Храните его в переменной окружения (
HIAPI_API_KEY), а не в системе контроля версий — примеры ниже читают его именно так. - Идентификатор модели. В этом учебнике строка фиксирована:
seedance-2.5-flash/image-to-video. Считайте её непрозрачной константой; не собирайте её из частей. - Исходное изображение. Публичный URL или поддерживаемая встроенная ссылка на изображение. Модели требуется как минимум одно изображение первого кадра.
- HTTP-клиент.
curlдля дымового теста иrequestsдля всего, что вы планируете сохранить.
Логические поля тела запроса
Независимо от языка, тело запроса на генерацию видео из изображения состоит из нескольких концептуальных групп. Понимание их по отдельности облегчает чтение JSON:
Модель и входные данные
- Идентификатор модели.
- Объект входных данных, содержащий изображение первого кадра и, опционально, изображение последнего кадра. В главе 4 объясняется, как они взаимодействуют.
Настройки вывода
- Параметры, связанные с разрешением и длительностью.
- Переключатель нативного аудио, определяющий, будет ли сгенерированный фрагмент сопровождаться звуковой дорожкой. В главе 5 объясняется, когда его включать.
Что возвращается
Успешная отправка возвращает объект задачи. Поля, которые вам действительно нужны, — это идентификатор задачи и текущий статус. Всё остальное — метаданные, которые можно логировать или игнорировать. Не пытайтесь с первого дня парсить весь ответ в типизированную модель — сначала логируйте, изучайте, затем сужайте.
Быстрая проверка реальности перед продолжением: если ваше тело запроса содержит поля, назначение которых вы не можете объяснить одним предложением, удалите их и начните с минимума. Страница модели seedance-2.5-flash/image-to-video — это справочник по точным именам принимаемых полей.
Отправка задачи с помощью curl
Начните с минимального запроса, который может работать, затем добавляйте поля по одному. Ниже приведена минимальная отправка с помощью curl:
curl -X POST "$HIAPI_BASE_URL/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/image-to-video",
"input": {
"first_frame_image": "https://your-bucket.example.com/frame-001.jpg"
}
}'
Пояснения по каждому полю
Authorization— ваш ключ API в виде bearer-токена. Если здесь ошибка, вы получите ошибку аутентификации до запуска любой проверки, поэтому при отладке проверяйте в первую очередь.Content-Type: application/json— обязателен; его отсутствие приводит к запутанным ошибкам на последующих этапах.model— фиксированный идентификатор модели. Опечатка здесь даст 4xx, а не тихий откат.input.first_frame_image— изображение, с которого начинается фрагмент. Используйте URL, реально доступный из вашей сети; приватные или просроченные URL завершатся ошибкой при получении, а не при отправке.
Чтение ответа
Ответ — это JSON, содержащий идентификатор задачи и статус. Немедленно сохраните идентификатор — именно его вы будете опрашивать в главе 7. Быстрый способ извлечь его в shell:
# После приведённого выше curl, передать через jq
# {"job_id": "...", "status": "queued"}
Добавление последнего кадра
Чтобы также управлять конечным кадром, добавьте второе изображение в тот же объект input. Имя поля и допустимые форматы указаны в документации модели — не угадывайте альтернативные написания; API отклонит неизвестные ключи, а не проигнорирует их.
Как только минимальный запрос заработает, у вас появится дымовой тест, который можно перезапустить при возникновении проблем. Сохраните его в файле; когда сервис сломается в два часа ночи, он будет ценнее любого длинного объяснения.
Входные данные первого и последнего кадра
Входные изображения — главный фактор успеха задачи. Они формируют содержимое фрагмента и одновременно являются наиболее частым источником отклонённых запросов.
Что контролирует первый кадр
Изображение первого кадра задаёт начальное состояние генерируемого фрагмента: композицию, субъект, освещение и цвет. Модель генерирует движение и продолжение из этой начальной точки, поэтому изображение должно выглядеть как кадр, который вы действительно хотите видеть в момент времени ноль. Размытые, обрезанные или сильно сжатые исходные изображения не станут волшебным образом лучше на последующих этапах.
Что контролирует последний кадр
Предоставление изображения последнего кадра фиксирует конечное состояние. Это полезно, когда фрагмент должен завершиться на определённом кадре — кадр с изображением продукта, появление логотипа, совпадающий переход в монтаже. Если его опустить, модель сама выберет концовку, что нормально для исследовательской работы, но непредсказуемо для производства.
Как они взаимодействуют
Когда предоставлены оба, модель интерполирует между ними. Это имеет практические последствия:
- Непрерывность важнее контраста. Два кадра одной сцены с умеренной амплитудой движения дают более связный фрагмент, чем два несвязанных изображения. Если кадры сильно различаются, ожидайте видимой деформации, а не правдоподобного перехода.
- Соотношения сторон должны совпадать. Несовпадение соотношений сторон первого и последнего кадров вынуждает модель выполнять неудобное перекомпонование. Обрежьте оба до одинаковой пропорции перед отправкой.
- Разрешения должны быть сопоставимы. Отправка чёткого первого кадра и низкоразрешённого последнего даёт модели противоречивые сигналы.
Контрольный список перед отправкой
Перед отправкой убедитесь: оба URL изображений общедоступны и не истекут в середине задачи; оба в поддерживаемом формате; оба имеют одинаковое соотношение сторон; ни один не является скриншотом с элементами интерфейса, которые вы не хотите визуализировать. Быстрый HEAD-запрос к каждому URL дешевле неудачной задачи генерации и выявляет большинство этих проблем.
Если вы всё же получили отказ, сообщение об ошибке обычно указывает на объект входных данных. Сначала проверьте изображения локально — размеры, формат и доступность — и только потом подозревайте API.
Настройки разрешения и нативного аудио
Настройки вывода — это место, где разработчики склонны к избыточной конфигурации. Хорошая новость в том, что значения по умолчанию разумны; риск заключается в копировании значений из документации другой модели.
Разрешение
Разрешение определяет размер поставляемого видео и, следовательно, влияет на время генерации и объём вывода. Два эмпирических правила:
- Выбирайте под целевую площадку, а не под цифру. Фрагмент для мобильной ленты не нужно рендерить в большом размере, чтобы потом уменьшать. Выберите минимальное разрешение, удовлетворяющее целевую платформу.
- Предпочитайте одно из пресетов в документации. Передача произвольных или неподдерживаемых значений — частая причина отклонения запроса. Если вам нужен определённый кадр, обрежьте или масштабируйте после генерации, а не боритесь с валидатором запросов.
Нативное аудио
Переключатель нативного аудио определяет, будет ли сгенерированный фрагмент содержать звуковую дорожку, созданную вместе с видео. Подумайте, нужно ли вам это:
- Включите, если фрагмент является конечным продуктом для просмотра со звуком — социальный контент, короткие промо, сцены с персонажами, где окружающий звук усиливает ощущение движения.
- Отключите, если вы добавите свою музыку или закадровый голос в редакторе, или если фрагмент является промежуточным активом. Генерация аудио, которое вы потом выбросите, — пустая трата работы, усложняющая последующую обработку.
Длительность
Длительность связана со всем остальным: более длинные фрагменты генерируются дольше и более подвержены дрейфу согласованности субъекта. Для первой интеграции начинайте с коротких. Убедитесь, что конвейер работает от начала до конца на коротком фрагменте, а затем удлиняйте, доверяя процессу.
Держите объект настроек компактным
Если вы ловите себя на добавлении настроек для исправления качества, остановитесь и проверьте, не кроется ли проблема на самом деле во входных изображениях. Большинство разочаровывающих результатов восходит к главе 4, а не к отсутствующей ручке. Настраивайте осознанно, записывайте точный объект настроек вместе с каждым идентификатором задачи, и вы сможете связать изменения качества с конкретными корректировками.
Тот же запрос на Python
Запрос curl напрямую переносится на Python. Цель здесь — не фреймворк, а небольшой читаемый клиент, который отправляет задачу и возвращает идентификатор, чтобы слой опроса оставался отдельным.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "seedance-2.5-flash/image-to-video"
def submit_job(first_frame_url: str, last_frame_url: str | None = None) -> dict:
payload = {
"model": MODEL,
"input": {"first_frame_image": first_frame_url},
}
if last_frame_url:
payload["input"]["last_frame_image"] = last_frame_url
response = requests.post(
f"{BASE_URL}/image-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()
Почему такая структура
- Конфигурация через переменные окружения. Базовый URL и ключ находятся вне кода, поэтому один и тот же клиент может работать в разных средах.
timeout=30при отправке. Отправка быстрая; зависание отправки указывает на сетевую проблему или проблему аутентификации, которую вы хотите обнаружить рано, а не блокировать рабочий процесс на неопределённый срок.raise_for_status()перед разбором. Тело ответа 4xx обычно является JSON-объектом ошибки, а не задачей. Немедленное исключение сохраняет нормальный путь чистым и позволяет вызывающему коду явно обрабатывать сбои.- Отправка отделена от опроса.
submit_jobделает только одну вещь. Цикл опроса из следующей главы получает возвращённый словарь и отвечает за ожидание.
Перенос в сервис
В реальном сервисе оберните вызов так, чтобы сбои проявлялись в виде типизированных исключений, несущих код состояния и тело ответа — при отладке в производстве вам понадобится исходное тело ответа. Записывайте тело запроса вместе с возвращённым идентификатором задачи; когда коллега спросит, почему какой-то фрагмент выглядит неправильно, эта строка лога станет всем расследованием.
Имена полей точно такие же, как в примере с curl. Если вы понимаете один, вы понимаете другой — именно поэтому стоит потратить пять минут на curl в начале.
Опрос результатов без перегрузки API
Теперь задача существует и имеет идентификатор. Наивный подход — поспать шестьдесят секунд и помолиться — имеет два способа провалиться: тратит время, если задача завершится раньше, и полностью проваливается, если задача займёт больше времени.
Опрашивайте поле статуса, а не часы
Напишите цикл, который запрашивает текущий статус задачи и ветвится в зависимости от него:
import time
import requests
def wait_for_job(job_id: str, timeout_s: int = 600) -> dict:
deadline = time.monotonic() + timeout_s
delay = 2.0
while time.monotonic() < deadline:
r = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
r.raise_for_status()
job = r.json()
status = job.get("status")
if status == "succeeded":
return job
if status == "failed":
raise RuntimeError(f"job failed: {job.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15.0) # ограниченная экспоненциальная задержка
raise TimeoutError(f"job {job_id} not terminal after {timeout_s}s")
Важные особенности
- Явные терминальные состояния. Только
succeededиfailedзавершают цикл. Любое другое состояние является временным. Не считайте неизвестное состояние сбоем — новые промежуточные состояния появляются со временем, и ваш цикл должен их допускать. - Ограниченная задержка. Начинайте с малого (несколько секунд), увеличивайте с умеренным коэффициентом, ограничивая примерно десятью-пятнадцатью секундами. Это сохраняет отзывчивость для коротких задач, не перегружая конечную точку во время длительного рендеринга.
- Жёсткий дедлайн. Всегда ограничивайте общее время ожидания. Без него зависшая задача навсегда займёт рабочий процесс. Выбирайте верхнюю границу исходя из максимального реального времени рендеринга плюс запас.
- Разделяйте сбой и тайм-аут. Задача
failed— это ошибка генерации, о которой стоит сообщить пользователю. Тайм-аут — это состояние инфраструктуры, которое стоит повторить или расследовать отдельно. Смешивание их делает постмортем болезненным.
В веб-сервисе
Не запускайте этот цикл в обработчике запроса, где ожидает пользователь. Отправьте задачу, сохраните идентификатор, немедленно верните ответ, а фоновый рабочий процесс пусть опрашивает и доставляет результат — через webhook, очередь или обновляемую строку, за которой следит фронтенд. Приведённый выше цикл — забота рабочего процесса, а не HTTP.
Устранение распространённых сбоев
Большинство сбоев попадают в три категории. Сначала определите категорию, затем конкретную причину.
Категория 1: сбой валидации входных данных
Симптом: 4xx сразу при отправке, до любого рендеринга.
Диагностируйте в следующем порядке:
- Доступен ли URL изображения? Получите его самостоятельно из той же сети. Просроченные подписанные URL и приватные бакеты — главная причина.
- Поддерживается ли формат? Перекодируйте в стандартный формат, а не спорьте.
- Согласованы ли первый и последний кадры? Несовпадающие соотношения сторон или сильно различающиеся сцены часто проявляются как проблемы валидации или качества.
- Не добавили ли вы поле с неправильным именем? Неизвестные ключи обычно отклоняются, а не игнорируются. Сверьтесь со справочником модели.
Категория 2: несоответствие параметров
Симптом: запрос отклонён из-за какой-то настройки, или вывод игнорирует вашу конфигурацию.
- Неподдерживаемое разрешение или длительность. Используйте только значения из документации; произвольные числа — частая причина отказа.
- Опечатка в идентификаторе модели. Это фиксированная строка — копируйте её, не вводите заново.
- Ошибка вложенности. Настройки, принадлежащие верхнему уровню, помещённые внутрь
input, или наоборот, дают запутанные ошибки. Ориентируйтесь на структуру запроса из главы 3.
Категория 3: тайм-аут опроса и сбой задачи
Симптом: задача принята, но так и не достигла терминального успешного состояния.
- Убедитесь, что опрашиваете правильный идентификатор. Ошибки копирования между задачами в пакетных скриптах встречаются на удивление часто.
- Проверьте, действительно ли статус продвигается. Логируйте статус при каждом опросе, чтобы видеть, движется задача или застряла.
- Отличайте сбой API от сбоя генерации. Если сам запрос опроса завершается ошибкой, это проблема транспорта. Если задача сообщает
failed, прочитайте тело ошибки — оно обычно указывает на входные данные, вызвавшие проблему. - Перезапустите минимальный дымовой тест
curl. Если дымовой тест тоже не проходит, проблема в учётных данных или сервисе; если проходит — проблема в вашем теле запроса.
Общая стратегия отладки
Для каждой задачи фиксируйте три вещи: точное тело запроса, возвращённый идентификатор задачи и конечный статус с телом ошибки. С этими тремя почти любой инцидент превращается в пятиминутную диагностику, а не в потерянный день. Если сомневаетесь, сведите запрос к минимальной форме из главы 3 и добавляйте поля по одному, пока не возникнет ошибка — последнее добавленное поле и будет виновником.
Похожие статьи
Все статьи →-
Руководство
Практические сценарии Tripo H3.1: 5 высокоценных применений и ключевые моменты реализации
От text-to-3D до multiview-восстановления: выбирайте правильный режим и параметры под бизнес-сценарий
-
Руководство
Практические сценарии gemini-4-neon: 5 ценных способов применения и ключевые моменты интеграции
-
Руководство
Как вызывать seedance-2.5-flash для генерации видео из текста через HiAPI API (curl и Python)
Пошаговая отработка рабочего запроса для разработчиков: эндпоинт, параметры, обработка асинхронных задач и рабочие примеры на curl и Python