HiAPI
Блог

Руководство

Как вызывать hailuo-2.3/image-to-video через API HiAPI: curl и Python

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

Что умеет hailuo-2.3/image-to-video и когда его использовать

hailuo-2.3/image-to-video — это модель генерации видео из изображения, доступная через единый API HiAPI. Вы передаёте ей статичное изображение в качестве первого кадра, а также промпт с описанием того, как должно двигаться изображение, и модель генерирует короткое видео, которое начинается с этого изображения и продолжает его анимацию.

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

Сценарии, для которых подходит этот эндпоинт:

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

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

Предварительные требования и получение API-ключа

Перед первым запросом вам понадобятся три вещи: учётная запись HiAPI, API-ключ и общедоступный URL изображения первого кадра.

Учётная запись и API-ключ

Войдите в HiAPI и создайте API-ключ в консоли. Относитесь к ключу как к секрету: храните его в переменной окружения, а не вставляйте в исходный файл. Примеры в этом руководстве читают ключ из HIAPI_API_KEY.

export HIAPI_API_KEY="your-api-key-here"

Доступный URL изображения

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

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

Структура запроса: входное изображение и параметры

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

Идентификатор модели

Каждый вызов ссылается на hailuo-2.3/image-to-video. Держите его в одном месте кода, чтобы в будущем смена модели требовала изменения одной строки.

Изображение первого кадра

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

Промпт

Текстовое поле для описания движения — рассматривается в следующем разделе.

Длительность и разрешение

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

Тело запроса — JSON; ответ возвращает идентификатор задачи, а не готовое видео, что обсуждается в разделе об опросе ниже.

Написание промптов, дающих правдоподобное движение

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

Описывайте движение, а не содержание

Плохой пример: «Женщина в красном пальто стоит на мосту».

Хороший пример: «Женщина медленно поворачивает голову к камере, пальто развевается на ветру; камера мягко наезжает».

Разделяйте движение субъекта и движение камеры

Будьте явны в отношении обоих. «Медленный наезд», «ручная дрожащая камера», «статичный кадр» и «облёт справа» говорят модели, как меняется само изображение; а «волосы развеваются», «поднимается пар» и «переворачиваются страницы» описывают то, что происходит внутри кадра. Сочетание обоих даёт цельный кадр, а не плавающую картинку.

Соблюдайте физику

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

Будьте кратки и конкретны

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

Отправка задачи и опрос результата

Генерация видео требует времени, поэтому API асинхронный. Жизненный цикл состоит из трёх шагов:

1. Создание задачи

Отправьте POST-запрос на эндпоинт с URL изображения, промптом и параметрами. Успешный ответ возвращает идентификатор задачи и начальный статус, обычно что-то вроде queued или processing. Видео в этом ответе ещё нет.

2. Опрос задачи

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

3. Получение видео

Когда статус сообщает об успехе, ответ содержит местоположение видео (обычно URL), а часто и метаданные, такие как длительность. Скачайте или сохраните его согласно вашим правилам хранения.

Рекомендации для продакшена

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

Рабочий пример на curl

Следующий пример отправляет задачу. Замените URL изображения и промпт на свои; ключ берётся из переменной окружения, заданной ранее.

curl -sS -X POST \
  "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://your-cdn.example.com/first-frame.jpg",
    "prompt": "Субъект в кадре слегка поворачивается к камере и улыбается; камера медленно наезжает, мягкий свет скользит по лицу."
  }'

Ответ содержит идентификатор задачи. Опрашивайте его GET-запросом:

curl -sS \
  "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video/TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Повторяйте, пока статус не станет терминальным успехом, затем прочитайте URL видео из ответа. Точные пути эндпоинтов и имена полей, показанные здесь, приводятся только для иллюстрации схемы — перед вставкой чего-либо в продакшен-код сверьтесь с последней справочной документацией API, поскольку интерфейсы моделей действительно меняются.

Рабочий пример на Python

Этот скрипт отправляет задачу, затем опрашивает её до завершения, включая тайм-аут и базовую обработку ошибок.

import os
import time

import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def create_task(image_url: str, prompt: str) -> str:
    resp = requests.post(
        BASE,
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image_url": image_url, "prompt": prompt},
        timeout=60,
    )
    resp.raise_for_status()
    data = resp.json()
    task_id = data.get("task_id") or data.get("id")
    if not task_id:
        raise RuntimeError(f"No task id in response: {data}")
    return task_id


def poll_task(task_id: str, timeout_s: int = 600, interval_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = str(data.get("status", "")).lower()
        if status in {"succeeded", "success", "completed"}:
            return data
        if status in {"failed", "error", "cancelled"}:
            raise RuntimeError(f"Task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"Task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task = create_task(
        image_url="https://your-cdn.example.com/first-frame.jpg",
        prompt="Пар поднимается из чашки; камера медленно уходит вправо.",
    )
    result = poll_task(task)
    print(result)

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

Типичные сбои и способы отладки

Большинство проблем с этим эндпоинтом попадают в несколько категорий.

Изображение отклонено или недоступно

Сервис должен иметь возможность скачать ваше изображение. При ошибке загрузки или проверки проверьте, является ли URL публичным HTTPS, не истёк ли он (подписанные URL истекают), а также соответствуют ли формат и размер ограничениям документации. Быстрая проверка — открыть URL в приватном окне браузера: если он требует входа, сервер тоже не сможет его прочитать.

Неверные параметры

Отклонённая длительность, разрешение или неизвестное поле обычно возвращают ошибку валидации с указанием этого поля. Сравнивайте свою нагрузку с последней справочной документацией API, а не с руководством, и записывайте полное тело ошибки — сообщение об ошибке конкретнее, чем один HTTP-код статуса.

Ошибки аутентификации

401 или 403 почти всегда означают, что ключ отсутствует, имеет неверный формат или недостаточно прав доступа. Убедитесь, что заголовок Authorization присутствует, и что переменная окружения действительно экспортирована в оболочке или процессе, выполняющем запрос.

Тайм-аут опроса

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

Задача падает после отправки

Неудачные задачи обычно указывают на комбинацию промпта и изображения — противоречивые инструкции движения или первый кадр, конфликтующий с запрошенным движением. Упростите промпт, попробуйте более чистый первый кадр и запустите снова.

Результат выглядит неправильно

Если движение слабое или странное, исправление почти всегда в промпте: явно укажите основное движение, отделите поведение камеры от поведения субъекта и сохраняйте физическую правдоподобность движения. Записывайте ID запроса и ID задачи в журналы, чтобы связать неудачный видеоролик с точными входными данными, которые его породили. Перед публикацией сверьте имена параметров и актуальные цены в справочной документации API и на панели цен.

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

Все статьи →

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

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

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