HiAPI
Блог

Руководство

Как вызывать API преобразования изображения в видео seedance-2.5: готовые примеры на curl и Python

Nov 12, 2026
Абстрактная обложка: перекрывающиеся полупрозрачные стеклянные панели, отбрасывающие холодные синие полосы на бледно-сером поле, плоская и архитектурная композиция.
На этой странице

Что даёт эндпоинт преобразования изображения в видео seedance-2.5

seedance-2.5 преобразование изображения в видео — это асинхронный эндпоинт модели на HiAPI, который превращает одно или два статичных изображения в короткий видеоклип. Вы отправляете ему изображение (или пару изображений, служащих начальной и конечной точками движения), описываете желаемые изменения, и платформа возвращает задачу, которая по завершении генерации разрешается в URL видеофайла.

В типичном стеке генерации видео этот эндпоинт занимает уровень «оживления статичного изображения». У вас уже есть исходные изображения — изображения продуктов, рендеры персонажей, кадры раскадровки — и вам нужно движение, а не новое изображение. Поскольку вызов асинхронный, ваша работа — отправить задачу, сохранить её идентификатор и продолжать опрос до готовности результата. Эта схема «отправить, затем опрашивать» универсальна для долго выполняющихся эндпоинтов генерации HiAPI, поэтому клиент, который вы напишете здесь, можно перенести на другие модели.

Эндпоинт также предоставляет опции встроенного аудио, что важно, если вашему процессу нужен видеоклип со звуком, а не немой материал, который позже озвучивают. Если вам нужны точное до кадра движение камеры или зацикливаемое движение, то преобразование изображения в видео с явными первым и последним кадрами обычно является наиболее контролируемым выбором без построения 3D-сцены.

Предварительные требования и аутентификация

Перед первым вызовом подготовьте три вещи.

1. Ключ API HiAPI

Каждый запрос аутентифицируется вашим ключом, который отправляется как bearer token в заголовке Authorization. Не коммитьте его в систему контроля версий — читайте его из переменной окружения, чтобы один и тот же скрипт работал и локально, и в CI.

export HIAPI_API_KEY="your_key_here"

2. Исходное изображение, доступное API

Входные изображения передаются как URL. Разместите изображения там, где сервис сможет их получить — объектное хранилище с подписанными URL, CDN или любой публичный HTTPS-адрес. Если вы не хотите публично раскрывать изображения, создайте подписанный URL с коротким сроком действия, а не делайте бакет публичным.

Для рабочего процесса с первым/последним кадром вам нужно одно изображение (только первый кадр) или два изображения (первый и последний кадры).

3. HTTP-клиент

Подойдёт любой инструмент, умеющий отправлять JSON: curl для быстрой проверки, requests или httpx в Python, fetch в Node. Специальный SDK не нужен.

Конкретный базовый URL, путь и имена полей модели находятся на странице модели в консоли HiAPI; используйте эти значения дословно в примерах ниже. Как только у вас есть ключ и URL изображения, можно отправлять.

Вход по первому кадру и вход по последнему кадру

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

Только первый кадр. Вы передаёте одно изображение, и модель генерирует движение вперёд от него. Это правильный выбор, когда вы хотите, чтобы модель сама придумывала движение: портрет, медленно поворачивающийся, вращающийся продукт, пейзаж с движущимися облаками. Вы отказываетесь от определённости того, где закончится клип, но получаете больше творческой свободы и вам нужен только один материал.

Первый и последний кадры. Вы передаёте два изображения, и модель генерирует путь между ними. Это правильный выбор, когда важны конечные точки: логотип, собирающийся в итоговый комбинированный знак, персонаж, перемещающийся из позы A в позу B, объект, скользящий слева направо по кадру. Передача последнего кадра ограничивает движение, что обычно означает меньше неожиданностей и лучшую зацикливаемость, если вы планируете повторять клип.

Практическое правило: если вы можете описать клип как «с этим изображением происходит что-то», используйте только первый кадр. Если вы можете описать его как «это изображение превращается в то изображение», передавайте два. При передаче двух изображений сохраняйте в них согласованность композиции, соотношения сторон и освещения — несовпадающая пара изображений заставляет модель обрабатывать скачок, который выглядит как глюк.

Ваш промпт должен дополнять изображения, а не противоречить им. Описывайте движение, а не статичное содержимое, которое модель и так видит.

Отправка первого запроса с помощью curl

Следующий запрос отправляет задачу преобразования изображения в видео. Замените путь эндпоинта, идентификатор модели и имена полей значениями, показанными на странице модели seedance-2.5 преобразование изображения в видео в консоли HiAPI, и подставьте свои URL изображений.

curl -X POST "$HIAPI_BASE_URL/<image-to-video-path>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5/image-to-video",
    "prompt": "The camera slowly pushes in as the subject turns toward the light",
    "first_frame_image": "https://your-cdn.example.com/frame-01.jpg",
    "last_frame_image": "https://your-cdn.example.com/frame-02.jpg"
  }'

О структуре запроса стоит отметить несколько моментов:

  • prompt описывает движение. Делайте его коротким и конкретным; длинные списки прилагательных часто размывают инструкцию.
  • first_frame_image обязателен для преобразования изображения в видео. last_frame_image необязателен — при генерации только по первому кадру полностью уберите это поле.
  • Если нужны опции аудио, это дополнительные поля в том же JSON-теле (о них ниже).

Ответ — это объект задачи, содержащий идентификатор и статус. Сохраните идентификатор; он понадобится при каждом опросе. Если вызов возвращает ошибку аутентификации или валидации, сначала проверьте заголовки и URL изображения, затем повторите попытку.

Тот же запрос на Python

Ниже приведён эквивалентный код отправки на Python, переработанный так, чтобы было удобно захватывать идентификатор задачи.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<image-to-video-path>"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_video(first_frame, last_frame=None, prompt="", audio=False):
    payload = {
        "model": "seedance-2.5/image-to-video",
        "prompt": prompt,
        "first_frame_image": first_frame,
    }
    if last_frame:
        payload["last_frame_image"] = last_frame
    if audio:
        payload["audio"] = True

    resp = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    data = resp.json()
    return data["task_id"], data

task_id, raw = submit_video(
    first_frame="https://your-cdn.example.com/frame-01.jpg",
    last_frame="https://your-cdn.example.com/frame-02.jpg",
    prompt="The camera slowly pushes in as the subject turns toward the light",
)
print(task_id)

Две привычки стоит выработать пораньше. Во-первых, задавайте явный timeout для запроса отправки — зависший запрос должен быстро завершаться с ошибкой, а не блокировать ваш worker. Во-вторых, сохраняйте исходный ответ во время разработки. Поле, содержащее идентификатор задачи, может отличаться от task_id в зависимости от версии эндпоинта, и однократная печать исходного JSON избавит от лишнего цикла отладки.

Опрос асинхронной задачи до готовности видео

Генерация видео по изображению занимает больше времени, чем должен оставаться открытым один HTTP-запрос, поэтому платформа использует жизненный цикл «отправить, затем опрашивать». Отправка возвращает идентификатор задачи; затем вы периодически запрашиваете эндпоинт задачи, пока её статус не достигнет терминального состояния.

import time
import requests

def wait_for_video(task_id, interval=5, max_wait=600):
    url = f"{BASE_URL}/<task-path>/{task_id}"
    deadline = time.time() + max_wait
    while time.time() < deadline:
        resp = requests.get(url, headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()
        status = task.get("status")
        if status == "succeeded":
            return task["video_url"]
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"Task {task_id} ended as {status}: {task.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} not ready after {max_wait}s")

Проектируйте опрос вокруг четырёх правил:

  • Опрашивайте с разумным интервалом. Пять секунд — разумное значение по умолчанию. Частые удары по эндпоинту не заставят видео отрендериться быстрее.
  • Всегда задавайте крайний срок. Задачи могут завершаться ошибкой или стоять в очереди дольше ожидаемого; неограниченный цикл превратит временную проблему в зависший worker.
  • Считайте failed и cancelled терминальными состояниями. Выводите поле ошибки, а не повторяйте одну и ту же задачу бесконечно.
  • Используйте экспоненциальную задержку при постоянном опросе. Если вы одновременно опрашиваете много задач, постепенно увеличивайте интервал, чтобы избежать всплесков трафика.

В производственной среде опрашивайте из фонового worker или очереди, а не внутри обработчика веб-запроса. Результат — URL видео; скачайте его своевременно и скопируйте в собственное хранилище, поскольку URL сгенерированных ресурсов обычно не являются постоянными.

Работа с флагом встроенного аудио

seedance-2.5 может генерировать клипы со встроенным аудио; этот переключатель является полем запроса наряду с входными изображениями и промптом — а не отдельным эндпоинтом. Точное имя поля и допустимые значения перечислены на странице модели; приведённая выше Python-функция демонстрирует это через передачу логического значения audio.

Включать ли его, зависит от того, как будет использоваться клип.

Запрашивайте аудио, если: вывод сразу предназначен для аудитории — пост в соцсети, превью, демонстрация — и вы хотите, чтобы клип ощущался завершённым без вторичного монтажа. Встроенное аудио также помогает рецензентам оценивать темп, поскольку звук делает тайминг движения более читаемым.

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

Практическое замечание по ограничению области: рассматривайте аудио как решение для каждого запроса, а не как глобальную настройку. Как показано выше, одна функция, принимающая флаг audio, позволяет одному и тому же пути кода обслуживать и немую фоновую пакетную обработку, и отточенный финальный рендер.

Если флаг присутствует, но результат беззвучен, сначала убедитесь, что значение сериализуется как задумано — строка "true" и логическое значение true — распространённое несоответствие — прежде чем предполагать, что модель его проигнорировала.

Частые точки отказа и дальнейшие шаги

Большинство проблем при первой интеграции сводятся к четырём категориям.

Входные данные, недоступные сервису

URL, работающий в вашем браузере, может не работать на стороне сервиса: приватные бакеты, истёкшие ссылки или хосты, блокирующие user-agent, отличный от браузерного. Используйте подписанный URL с жизненным циклом, достаточным для всей генерации, и убедитесь, что изображение загружается с машины вне вашей сети.

Несовпадающие кадры

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

Неверные имена полей или идентификатор модели

Примеры здесь используют структуру запроса со страницы модели; копируйте имена полей и строку модели из консоли дословно, а не по памяти или из старого фрагмента. Опечатки в именах полей часто молча игнорируются, а не отклоняются.

Опрос, который никогда не завершается

Если ваш цикл снова и снова истекает по тайм-ауту, логируйте каждое значение статуса, которое вы наблюдаете. Неожиданная строка статуса обычно объясняет застой — возможно, ваша проверка терминального состояния просто не совпадает с тем, что возвращает API.

Как только один клип пройден от начала до конца, естественные следующие шаги — пакетная обработка нескольких изображений через ту же функцию отправки и опроса, добавление повторных попыток с задержкой вокруг отправки и запись результатов в постоянное хранилище. Подробности об эндпоинте, полях запроса и справочник параметров вы найдёте на странице модели seedance-2.5 преобразование изображения в видео, и на их основе адаптируйте приведённый выше код к своим изображениям.

Похожие статьи

Все статьи →

Начните работать с постоянными артефактами ИИ

Получите API-ключ и вызывайте модели изображений, видео и аудио через один API на основе tasks.

Читать документацию API