Seedance 2.5 API для генерации видео из изображения: как передать первый кадр, первый и последний кадры и референсные изображения

TL;DR

• seedance-2.5/image-to-video оживляет изображение, а также позволяет одновременно передать первый и последний кадры, чтобы модель дорисовала промежуточный процесс. Длительность одного видео — 4–30 секунд, со звуком. Откройте страницу модели — и можно генерировать онлайн; новым пользователям при регистрации начисляется 200 кредитов.
• Цена такая же, как у генерации видео из текста: 720p — $0.204 за секунду, 1080p — $0.516 за секунду. 4 секунды 720p — $0.816.
• Два режима на выбор: первый кадр / первый и последний кадры либо референсные изображения + референсное аудио; смешивать их нельзя.

Сначала посмотрим на реальный результат: первый и последний кадры

Передайте «пустой цветочный горшок» как первый кадр, «горшок, заросший базиликом» как последний, а в промпте опишите только то, как происходит изменение:

Time-lapse growth of a basil seedling sprouting and unfurling leaves inside the terracotta pot, smooth continuous motion, soft morning light staying consistent, camera locked off, no cuts

Сгенерировать с этим промптом → (загрузите свой первый и последний кадры, 4 секунды, 720p)

seedance-2.5/image-to-video, первый кадр + последний кадр, 720p, 4 секунды, со звуком, $0.816.

Композиция, освещение и расположение предметов на двух изображениях должны совпадать, меняться должно только то, что вы хотите показать в видео (здесь — растение); тогда переход получится плавным. Фраза в промпте "soft morning light staying consistent" нужна, чтобы модель не сделала таймлапс и для освещения.

curl: только первый кадр

Самый распространённый вариант: изображение продукта или иллюстрация плюс фраза «что происходит дальше»:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5/image-to-video",
    "input": {
      "prompt": "камера медленно приближается к чашке кофе с поднимающимся паром, пар закручивается и поднимается в утреннем свете, лёгкое дрожание камеры в руках",
      "first_frame_url": "https://your-cdn.example.com/coffee-cup.jpg",
      "duration": 5,
      "resolution": "720p"
    }
  }'

Возвращается taskId:

{"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

Проверка результата:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

После того как status станет success, скачайте видео из output[0].url.

Первый и последний кадры: добавьте last_frame_url

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "таймлапс одного и того же письменного стола от дня к ночи: дневной свет постепенно тускнеет, настольная лампа зажигается тёплым светом, за окном один за другим загораются городские огни, камера неподвижна",
    "first_frame_url": "https://your-cdn.example.com/desk-day.jpg",
    "last_frame_url": "https://your-cdn.example.com/desk-night.jpg",
    "duration": 4,
    "resolution": "720p"
  }
}

• last_frame_url используется вместе с first_frame_url.
• Если пропорции последнего и первого кадров не совпадают, последний кадр обрезается по центру; лучше создавать оба изображения в одном соотношении сторон.
• Соотношение сторон берётся с первого кадра; у aspect_ratio есть только значение adaptive, передавать его не нужно.

Python: отправка, опрос, скачивание

# pip install requests; сначала export HIAPI_KEY=ваш Key
import os, time, uuid, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}

def generate(prompt, model="seedance-2.5/image-to-video", timeout_s=900, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    # При повторной отправке той же задачи передавайте тот же Idempotency-Key, чтобы избежать двойного списания
    headers = {**H, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post("https://api.hiapi.ai/v1/tasks", json=body, headers=headers, timeout=30)
    r.raise_for_status()
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate(
    "Time-lapse growth of a basil seedling sprouting and unfurling leaves, camera locked off, no cuts",
    first_frame_url="https://your-cdn.example.com/seedling-start.jpg",
    last_frame_url="https://your-cdn.example.com/seedling-grown.jpg",
    duration=4, resolution="720p",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Другой режим: референсные изображения + референсное аудио

Если вы не хотите жёстко закреплять изображение как первый кадр, а хотите, чтобы модель «ориентировалась» на внешность персонажа, внешний вид продукта или стиль рисунка, используйте reference_image_urls (до 30 изображений) и дополнительно reference_audio_urls (до 10 фрагментов) для стиля звука:

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "девушка с референсного изображения с таким же синим рюкзаком идёт по углу улицы под дождём, камера следует за ней",
    "reference_image_urls": [
      "https://your-cdn.example.com/girl.jpg",
      "https://your-cdn.example.com/backpack.jpg"
    ],
    "duration": 5,
    "resolution": "720p"
  }
}

Обратите внимание: референсные изображения и референсное аудио нельзя передавать одновременно с first_frame_url / last_frame_url — только что-то одно.

Обзор параметров

Параметр	Значение	Описание
prompt	строка, обязательный	Опишите действие, камеру и звук; заново описывать всё изображение не нужно
first_frame_url	URL изображения	Первый кадр
last_frame_url	URL изображения	Последний кадр, используется вместе с первым
reference_image_urls	до 30 изображений	Нельзя использовать одновременно с первым и последним кадрами
reference_audio_urls	до 10 фрагментов	Нельзя использовать одновременно с первым и последним кадрами
duration	целое число 4–30, по умолчанию 5	в секундах
resolution	720p / 1080p, по умолчанию 720p
generate_audio	по умолчанию true	Звук генерируется вместе с изображением
output_format	mp4 / mov

Посчитаем стоимость

Длительность	720p ($0.204/сек)	1080p ($0.516/сек)
4 секунды	$0.816	$2.064
5 секунд	$1.02	$2.58
10 секунд	$2.04	$5.16
15 секунд	$3.06	$7.74

Первый и последний кадры стоят столько же, сколько только первый кадр; цена зависит только от разрешения и количества секунд. Подробнее — в статье Цены Seedance 2.5 API.

Что учесть перед запуском

• Адрес изображения должен быть публично доступен: подойдёт HTTP(S)-адрес или data URL; по внутреннему адресу модель изображение не получит.
• Используйте callback вместо опроса: добавьте на верхний уровень запроса "callback": {"url": "https://ваш-домен/hiapi/callback"} и дедуплицируйте по taskId.
• Своевременно сохраняйте файлы: output[0].url — временная ссылка, сразу после получения сохраните файл в своё хранилище.
• Повторяйте с ключом идемпотентности: добавьте в заголовки Idempotency-Key; при повторе с тем же ключом задача создаётся только один раз.
• Автоматический возврат при ошибке: оплата взимается только за успешно сгенерированное видео.

Частые вопросы

Что делать, если между первым и последним кадрами появляется «наплыв»?

Если изображения слишком сильно различаются, в течение одной-двух секунд посередине возникает эффект наложения двух картинок. Сделайте композицию и предметы на обоих изображениях согласованными, меняйте только основной объект и добавьте в промпт "camera locked off, no cuts".

Можно передать только последний кадр?

Нет, последний кадр используется вместе с первым.

Можно задать вертикальное видео?

Соотношение сторон берётся с первого кадра; для вертикального видео загрузите вертикальный первый кадр.

Чем отличается первый кадр от референсного изображения?

Первый кадр буквально становится первым кадром видео; референсное изображение лишь задаёт модели внешний вид и стиль, а композиция может быть перестроена.

Есть только промпт, без изображения? Смотрите Seedance 2.5 API для генерации видео из текста. Больше вариантов первого кадра — в руководстве пользователя Seedance 2.5, или сразу перейдите на страницу модели и попробуйте загрузить изображение.