Как использовать API преобразования изображения в видео hailuo 2.3 Fast: curl, Python и рабочий запрос

У вас есть статичное изображение, и вы хотите превратить его в короткое видео. Это руководство покажет, как подключиться к hailuo-2.3-fast/image-to-video через API задач hiapi: точная входная схема (проверена по онлайн-валидатору), curl-запрос, готовый к копированию, полный Python-скрипт, который опрашивает задачу до завершения, а также детали для продакшена — колбэки, идемпотентные повторы и ответы с ошибками, с которыми вы реально столкнётесь.

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

• API-ключ hiapi — получите его в вашей консоли. Ключ имеет вид sk-... и передаётся в заголовке Authorization: Bearer.
• Исходное изображение, размещённое на публично доступном HTTPS URL. API принимает URL, а не загруженный файл.
• Любой HTTP-клиент. В примерах ниже используются curl и Python-библиотека requests.

Цена с оплатой по секундам для этой модели указана на странице тарифов.

Входная схема (проверена)

hailuo-2.3-fast/image-to-video использует унифицированную конечную точку асинхронных задач: POST /v1/tasks создаёт задачу, GET /v1/tasks/<taskId> опрашивает задачу. Входная схема строгая — неизвестные поля отклоняются с кодом 400, а не игнорируются молча.

Поле	Тип	Обязательность	Описание
prompt	string	✅	Опишите желаемое движение
image_url	string	✅	В единственном числе — строка с URL, не массив image_urls
duration	string	Необязательно	"6" или "10" — это строка, а не число
prompt_optimizer	boolean	Необязательно	Позволяет бэкенду переписать ваш промпт для движения

Валидатор ловит три типичные ловушки:

1. duration должен быть строкой. Отправка "duration": 6 вернёт 400 с сообщением duration: got number, want string. Отправляйте "duration": "6".
2. Поле называется в единственном числе — image_url. Многие другие видеомодели на платформе (Grok Imagine, Kling) принимают массив image_urls. Эта модель принимает одну строку.
3. Нет resolution, aspect_ratio, seed, watermark или end_image_url. Все они вернут additional properties ... not allowed. Формат кадра соответствует вашему исходному изображению; управление движением возможно только через промпт.

Минимальный рабочий запрос: curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3-fast/image-to-video",
    "input": {
      "prompt": "镜头缓慢推进，咖啡杯上蒸汽升腾，柔和的晨光",
      "image_url": "https://your-cdn.example.com/coffee.jpg",
      "duration": "6"
    }
  }'

Успешный ответ:

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

Затем опрашивайте:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01KX4W3SVW8S8EHD5VX45JH95V \
  -H "Authorization: Bearer sk-YOUR_KEY"

Пока видео рендерится, data.status равен "handling":

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01KX4W3SVW8S8EHD5VX45JH95V",
    "model": "hailuo-2.3-fast/image-to-video",
    "status": "handling",
    "storage": "temp",
    "completed": 0,
    "created": 1783648872
  },
  "message": "success"
}

Конечные состояния — "success" (URL видео в data.output[0].url) и "fail" (детали в data.error).

Полный Python-скрипт

import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]  # sk-...
HEADERS = {"Authorization": f"Bearer {TOKEN}"}


def create_task(prompt: str, image_url: str, duration: str = "6") -> str:
    resp = requests.post(
        API_BASE,
        headers={**HEADERS, "Content-Type": "application/json"},
        json={
            "model": "hailuo-2.3-fast/image-to-video",
            "input": {
                "prompt": prompt,
                "image_url": image_url,
                "duration": duration,  # 字符串："6" 或 "10"
            },
        },
        timeout=60,
    )
    body = resp.json()
    if resp.status_code != 200 or not body.get("data", {}).get("taskId"):
        raise RuntimeError(f"create failed: {resp.status_code} {body}")
    return body["data"]["taskId"]


def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task(
        prompt="猫眨了眨眼，把头转向窗户，微风拂过它的毛",
        image_url="https://your-cdn.example.com/cat.jpg",
        duration="6",
    )
    print("task:", task_id)

    task = wait_task(task_id)
    video_url = task["output"][0]["url"]
    print("video:", video_url)

    # URL 位于带有效期的临时存储上——立即下载，不要直接外链它。
    mp4 = requests.get(video_url, timeout=120).content
    with open("output.mp4", "wb") as f:
        f.write(mp4)
    print(f"saved output.mp4 ({len(mp4)} bytes)")

Этот скрипт делает правильно две вещи, которые часто упускают быстрые прототипы:

• Он сразу скачивает видео. storage: "temp" означает, что выходной URL имеет срок действия (expireAt). Сохраняйте байты в собственное хранилище; никогда не сохраняйте возвращённый URL в вашу базу данных.
• Он считает fail конечным состоянием. Повторный опрос проваленной задачи не оживит её — создайте новую задачу.

Замечания для продакшена

Используйте колбэки вместо опроса

Для сценариев за пределами скриптов зарегистрируйте webhook при создании задачи и полностью пропустите цикл опроса:

{
  "model": "hailuo-2.3-fast/image-to-video",
  "input": { "prompt": "...", "image_url": "https://...", "duration": "6" },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

С "when": "final" ваш эндпоинт вызывается один раз, когда задача достигает success или fail. Эмпирическое правило: опрос подходит для CLI, пакетных задач и любых разовых сценариев; как только у вас есть сервер, который уже слушает, колбэки лучше — видеозадачи выполняются несколько минут, и цикл опроса в эти минуты — это занятый слот соединения и потраченный воркер.

Идемпотентность

Сам вызов создания не идемпотентен — каждый прошедший валидацию POST /v1/tasks создаёт новую (платную) задачу. Если ваш обработчик задач повторяет попытку по таймауту, сохраните полученный taskId под ключом вашего собственного request id до обработки результата. При повторе, если для этого ключа уже есть taskId, опрашивайте его, а не создавайте дубликат задачи.

Ошибки, с которыми вы реально столкнётесь

Симптом	Значение	Исправление
401 — {"error":{"code":"permission_denied","type":"hiapi_error"}}	Неверный ключ или ключ не имеет доступа к этой модели	Проверьте ключ в консоли; в ответе есть request_id для поддержки
400 INVALID_REQUEST — duration: got number, want string	Использовано JSON-число вместо строки	"duration": "6"
400 INVALID_REQUEST — additional properties '...' not allowed	Вы отправили поле вне схемы	Уберите его — сообщение укажет каждое нарушающее поле
400 INVALID_REQUEST — missing required field "prompt" / "image_url"	Ввод пуст или имя поля неверно	Оба поля обязательны
Задача достигает fail после создания	Ошибка времени выполнения — частая причина: URL изображения, недоступный бэкенду	Валидатор не загружает ваше изображение при создании; убедитесь, что URL публично доступен

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

Связанные материалы

• Страница модели hailuo-2.3-fast/image-to-video — песочница и цена по секундам
• Рабочий процесс API преобразования изображения в видео: руководство для продакшена — архитектура пакетной обработки, хранения и повторов вокруг эндпоинта i2v
• API текст-в-видео vs изображение-в-видео — когда стоит привязывать генерацию к исходному изображению
• Руководство по API Kling изображение-в-видео — тот же API задач, другая входная схема, полезное сравнение

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

Могу ли я задать разрешение или соотношение сторон? Нет. Схема hailuo-2.3-fast/image-to-video отклоняет resolution и aspect_ratio как неизвестные поля. Формат кадра соответствует вашему исходному изображению; если вам нужно конкретное соотношение сторон, сначала обрежьте входное изображение.

Какие длительности поддерживаются? Ровно две: "6" и "10" секунд, передаются как строки. Любое другое значение вернёт 400 с сообщением value must be one of '6', '10'.

Могу ли я передать несколько референсных изображений? Нет — это поле представляет собой одну строку image_url. Модели, принимающие массивы изображений (например, image_urls у Grok Imagine), используют другую схему; не копируйте тело запроса между моделями без проверки.

Как управлять движением? Только через prompt — нет параметров интенсивности движения или камеры. Явно описывайте движение («камера медленно приближается», «волосы развеваются на ветру»). Опционально установите "prompt_optimizer": true, чтобы бэкенд расширил ваш промпт.

Есть ли более медленный, более качественный вариант? Да — hailuo-2.3/image-to-video (без -fast) также доступен на платформе, а hailuo-2.3/text-to-video покрывает сценарии без исходного изображения. Перед переключением проверяйте схему каждого варианта; входные поля не гарантированно совпадают.

Сколько это стоит? Оплата рассчитывается по секундам сгенерированного видео и зависит от модели; актуальные тарифы смотрите на странице тарифов.

Нужен ли API-ключ для пробного использования? Да — все вызовы API задач требуют ключа Bearer sk-.... Вы можете создать его в консоли и сначала протестировать в песочнице на странице модели.