Управление первым и последним кадром в AI-видео: руководство по точному движению между моделями на hiapi

Большинство API генерации видео из изображения принимают только одно статичное изображение, а затем импровизируют движение. Лишь少数 моделей позволяют зафиксировать конечную точку кадра, а не только начальную — вы передаёте первый и последний кадр, и модель интерполирует движение между ними. Именно в этом разница между «оживить эту фотографию» и «точно реализовать этот переход».

Проблема в том, что поддержка управления последним кадром у моделей неоднородна, и даже в рамках продуктовой линейки одного производителя флагманский уровень и быстрый/турбо-уровень могут различаться. В этом руководстве мы чётко укажем, какие видео-модели hiapi поддерживают только управление первым кадром, а какие — первый + последний кадр, и приведём их реальные (и неодинаковые) поля ввода, чтобы вы не обнаружили после долгих мучений, что выбранная модель молча проигнорировала ваш последний кадр.

1. Что вам понадобится

API-ключ hiapi из консоли (sk-...), а также два URL-адреса изображений, доступных целевой модели (публичные HTTPS-URL — эндпоинт задач не поддерживает загрузку локальных файлов). Каждая из перечисленных ниже моделей вызывается через единый task API, поэтому если ваш ключ работает с одной моделью, он работает со всеми.

2. Минимальный рабочий пример

Вся генерация видео hiapi идёт через один эндпоинт: создайте задачу, затем опрашивайте её (или используйте callback — см. Производственные паттерны) до достижения терминального состояния.

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0-omni/image-to-video",
    "input": {
      "prompt": "the subject turns toward the camera and smiles",
      "image_urls": [
        "https://your-cdn.example.com/first-frame.jpg",
        "https://your-cdn.example.com/last-frame.jpg"
      ],
      "resolution": "720p",
      "duration": 5,
      "sound": false
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Poll until terminal
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

kling-3.0-omni/image-to-video — наиболее типичный пример этого паттерна: input.image_urls принимает один или два URL-адреса изображений. Передайте один — модель зафиксирует только первый кадр, а остальное импровизирует; передайте два — второй URL становится принудительным последним кадром, и модель получит указание, где должен закончиться кадр. Длительность — целое число от 3 до 15 (секунд), resolution — 720p / 1080p / 4k, необязательное логическое значение sound добавляет сгенерированный атмосферный звук. Здесь нет поля aspect_ratio — формат вывода следует за предоставленными кадрами.

Не все модели устроены так же. seedance-2.5/image-to-video достигает того же эффекта через два отдельно именованных поля, а не через массив:

{
  "model": "seedance-2.5/image-to-video",
  "input": {
    "prompt": "smooth camera push toward the subject",
    "first_frame_url": "https://your-cdn.example.com/first-frame.jpg",
    "last_frame_url": "https://your-cdn.example.com/last-frame.jpg",
    "resolution": "720p",
    "duration": 6,
    "aspect_ratio": "adaptive",
    "generate_audio": false
  }
}

last_frame_url имеет смысл только в паре с first_frame_url — вы можете отправить только first_frame_url для кадра с управлением лишь первым кадром, но не наоборот. Диапазон длительности этой модели — 4–30 с, разрешение максимум 720p/1080p (без уровня 4K), а aspect_ratio по умолчанию равен adaptive, то есть следует за первым кадром, а не принимает явные значения 16:9/9:16.

Имена полей у моделей действительно различаются — image_urls против first_frame_url/last_frame_url — поэтому каждую смену модели следует рассматривать как изменение схемы, а не как простую замену.

Поддерживается не всеми моделями

veo-3.1/image-to-video принимает одну строку image_url и вообще не имеет параметра последнего кадра — вы можете задать aspect_ratio (auto/16:9/9:16), resolution и фиксированное перечисление duration (4, 6 или 8 секунд), но не можете зафиксировать конечный кадр. Аналогичная ситуация с моделью на ступень ниже в линейке Kling: kling-3.0-turbo/image-to-video (быстрая/дешёвая версия kling-3.0-omni) принимает максимум один элемент в image_urls — ни последнего кадра, ни разрешения 4K. Если вам нужно управление последним кадром, выбирайте флагманский уровень или модель, специально созданную для этого (например, seedance-2.5), а не полагайтесь на название семейства моделей.

3. Производственные паттерны

При масштабировании используйте callback вместо опроса. Передайте объект callback в том же теле запроса, а не опрашивайте в цикле:

{
  "model": "kling-3.0-omni/image-to-video",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" срабатывает один раз, при достижении задачей любого терминального состояния — succeeded или failed оба являются терминальными, поэтому ваш обработчик вебхука должен дедуплицировать по taskId, а не предполагать, что callback означает только успех. Опрос GET /v1/tasks/:id лучше подходит для локальной отладки, редких разовых вызовов или как запасной механизм сверки, когда callback так и не пришёл (сетевые сбои, кратковременная недоступность вашего эндпоинта).

Идемпотентность. Повторные попытки после тайм-аута или обрыва соединения могут при неаккуратном подходе создать дублирующие задачи — записывайте id задачи, возвращённый при создании, и перед повторной отправкой выполните GET по этому id в качестве проверки.

URL-адреса вывода истекают. Поле expireAt в каждой записи вывода — не украшение: независимо от того, узнали ли вы об успехе через callback или опрос, скачайте видео и сохраните его (в собственное хранилище) как можно скорее.

Ошибки аутентификации. Неверный или отсутствующий ключ возвращает HTTP 401 и {"error": {"code": "permission_denied", ...}}. Проверяйте этот статус/код ошибки явно, а не предполагайте, что любой не-2xx означает сбой самой генерации — в обработке ошибок полезно различать «мой ключ неверен» и «модель отклонила мой ввод», поскольку способы исправления совершенно разные.

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

• Страница модели Kling 3.0 Omni image-to-video — цены, онлайн-демо и полный справочник параметров модели, использованной в примере выше.
• Страница модели Seedance 2.5 image-to-video — вариант с first_frame_url/last_frame_url.
• Документация по аутентификации — как работают заголовок Authorization: Bearer sk-... и области действия ключа.
• Документация по созданию задач — полный справочник запросов/ответов /v1/tasks, включая параметры callback.
• Цены hiapi — текущие цены по секундам и разрешению (тарификация зависит от модели и разрешения, смотрите актуальную страницу, а не жёстко прописанные цифры).

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

Какие видео-модели hiapi поддерживают управление последним кадром? kling-3.0-omni/image-to-video (через массив image_urls из 2 элементов) и seedance-2.5/image-to-video (через first_frame_url + last_frame_url) в настоящее время поддерживают. veo-3.1/image-to-video и kling-3.0-turbo/image-to-video не поддерживают — они принимают только один начальный кадр.

Можно ли указать только последний кадр без prompt? Обе модели по-прежнему принимают (и обычно ожидают) prompt помимо кадров — он управляет движением между двумя кадрами, а не только содержимым. Не каждая модель явно отклонит пустой или отсутствующий prompt, но явное описание перехода делает движение более предсказуемым.

Должны ли оба кадра иметь одинаковое соотношение сторон? Ни kling-3.0-omni/image-to-video, ни seedance-2.5/image-to-video не предоставляют явный aspect_ratio, независимый от настройки изображения — формат вывода следует за входными кадрами, поэтому несогласованные соотношения сторон первого и последнего кадров дадут заметно неудобный результат, а не ошибку. Перед отправкой обрежьте или дополните оба кадра до одинакового соотношения.

Что будет, если отправить только последний кадр без первого? Обе модели не поддерживают это — в seedance-2.5 last_frame_url можно использовать только вместе с first_frame_url; в kling-3.0-omni массив читается по позиции (первый элемент = первый кадр). «Обратного» режима с указанием только конечного кадра не существует.

Эквивалентно ли управление последним кадром переносу движения видео-в-видео? Нет — это другая возможность (seedance-2.5/reference-to-video на hiapi, принимает референсное видео для управления движением или движением камеры, а не два статичных изображения). Управление первым/последним кадром интерполирует между двумя изображениями; референсное видео-в-видео имитирует паттерн движения существующего фрагмента.

Добавление последнего кадра дороже, чем генерация только по первому кадру? Обе модели тарифицируются по секундам/разрешению, а не по входным изображениям, поэтому добавление последнего кадра само по себе не увеличивает стоимость — смотрите страницу цен для текущих тарифов.