Как вызывать kling-4.0/image-to-video на HiAPI: curl, Python и опрос

Что делает эндпоинт kling-4.0/image-to-video

kling-4.0/image-to-video превращает одно статичное изображение в короткий сгенерированный видеоролик. На HiAPI он работает как задачный эндпоинт: вы отправляете изображение и текстовое описание того, как должно двигаться изображение, а API сразу возвращает идентификатор задачи, а не готовое видео.

На уровне запроса вызывающая сторона должна предоставить:

• идентификатор модели (kling-4.0/image-to-video),
• исходное изображение (обычно это общедоступный URL изображения),
• текстовое описание, направляющее движение изображения или происходящее в сцене,
• все дополнительные параметры генерации, задокументированные для этого эндпоинта и этой модели.

Возвращается не само видео. Ответ на отправку содержит идентификатор задачи и начальный статус. Настоящий видеоролик станет доступен только после завершения задачи генерации, и тогда вы сможете получить его, сославшись на этот идентификатор.

Это разделение и есть полная ментальная модель эндпоинта: отправить → получить id задачи → опрашивать статус → скачать результат. Каждый раздел ниже — вариация этого цикла.

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

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

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

Аутентификация выполняется для каждого запроса. Каждый вызов API включает ваш ключ в HTTP-заголовке — стандартная схема — заголовок авторизации в стиле bearer:

Authorization: Bearer <YOUR_HIAPI_API_KEY>

Не допускайте попадания ключа в систему контроля версий. Обычная практика:

• храните его в переменной окружения (например, HIAPI_API_KEY) и читайте во время выполнения.
• никогда не вставляйте его в клиентский код и в curl-команды, которые позже закоммитите в репозиторий.
• если ключ утёк, смените его в консоли.

Экспортируйте его в оболочке, чтобы примеры на curl и Python ниже могли его прочитать:

export HIAPI_API_KEY="your-key-here"

Вам также понадобится доступный URL изображения. Эндпоинт использует изображения по ссылке, поэтому локальный путь к файлу на вашем ноутбуке не подойдёт — разместите изображение там, где есть стабильный HTTPS-URL, или, если платформа предоставляет механизм ресурсов, загрузите изображение и используйте возвращённую ссылку.

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

Разбор curl-запроса шаг за шагом

Полный запрос на создание задачи выглядит так:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0/image-to-video",
    "input": {
      "image": "https://example.com/your-image.jpg",
      "prompt": "A slow camera push-in as the subject turns toward the light; soft afternoon shadows"
    }
  }'

Разберём по частям:

• -X POST — создание задачи выполняется через POST, а не GET. Запрос несёт тело, описывающее задание.
• URL — единый эндпоинт задач HiAPI. Для задач-моделей это один и тот же маршрут; модель выбирается в теле, а не в пути.
• Authorization — ваш ключ, как описано в предыдущем разделе.
• Content-Type: application/json — тело имеет формат JSON; если опустить или перепутать этот заголовок, сервер обычно отклонит запрос ещё до того, как он дойдёт до модели.
• model — буквальная строка kling-4.0/image-to-video. Считайте её точной и регистрозависимой; опечатка приведёт к ошибке «модель не найдена», а не к полезной подсказке.
• input.image — исходное статичное изображение, переданное в виде URL. Это кадр, который модель будет оживлять, поэтому выбирайте чёткое изображение с ясной композицией.
• input.prompt — указания на естественном языке. Опишите движение и поведение камеры (наезд, панорама, движение субъекта), а также общее настроение. Расплывчатый промпт даст расплывчатое движение.

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

На этом этапе видеоролика ещё не существует. Это ожидаемое поведение, и следующий раздел показывает, как с ним работать.

Тот же вызов на Python

Версия на Python делает ровно то же самое — тот же эндпоинт, те же заголовки, то же тело — поэтому выбранный инструмент не меняет протокол.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "kling-4.0/image-to-video",
    "input": {
        "image": "https://example.com/your-image.jpg",
        "prompt": "A slow camera push-in as the subject turns toward the light; "
                  "soft afternoon shadows",
    },
}

resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)

resp.raise_for_status()
task = resp.json()
task_id = task["id"]
print("submitted:", task_id, task.get("status"))

Несколько моментов, важных на практике:

• Используйте json=payload, а не сериализацию строки вручную. Это установит тип содержимого за вас и избавит от ошибок с кавычками.
• Держите отправку и последующие операции в одной функции или классе, чтобы идентификатор задачи не терялся между шагами.
• Задайте явный таймаут. Вызов отправки должен возвращаться быстро; он только создаёт задание, а не ждёт видео.
• Не вызывайте raise_for_status() и после этого не предполагайте, что задача существует — ответ не из 2xx означает, что задача не создана, а тело ошибки обычно сообщает, какое поле неверно.

Если вы строите сервис, оберните этот вызов в небольшой клиент: один метод для отправки, один для проверки статуса. Так повторные попытки, логирование и обработка ключей будут сосредоточены в одном месте, а не разбросаны по точкам вызова.

Опрос асинхронной задачи до завершения

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

Как проверять статус

Опрашивайте задачу по идентификатору с помощью GET-запроса:

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

Ответ описывает задание: его статус и, после завершения, вывод. Статус обычно проходит от состояния в очереди через состояние выполнения к терминальному — например, успех или ошибка с сообщением.

Простой цикл опроса на Python

import time

def wait_for_task(session, base_url, task_id, timeout=900):
    deadline = time.time() + timeout
    delay = 2.0
    while time.time() < deadline:
        r = session.get(f"{base_url}/tasks/{task_id}", timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")

        if status in ("succeeded", "failed"):
            return data

        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)  # gentle backoff, capped

    raise TimeoutError(f"task {task_id} did not finish in time")

Рекомендации по задержкам

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

Получение и сохранение возвращённого видеоролика

Когда опрос возвращает терминальный статус успеха, объект задачи содержит ссылку на вывод сгенерированного видео — URL ресурса или эквивалентную ссылку на готовый ролик.

result = wait_for_task(session, "https://api.hiapi.ai/v1", task_id)
if result["status"] != "succeeded":
    raise RuntimeError(result.get("error") or "generation failed")

video_url = result["output"]["video_url"]

with session.get(video_url, stream=True, timeout=120) as r:
    r.raise_for_status()
    with open(f"{task_id}.mp4", "wb") as f:
        for chunk in r.iter_content(chunk_size=1 << 16):
            f.write(chunk)

Здесь обычно возникают два проектных решения.

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

Храните метаданные вместе с файлом. Сохраняйте вместе с видео id задачи, промпт, ссылку на исходное изображение и время создания. Когда позже кто-то спросит, почему ролик выглядит именно так, эта запись и будет ответом.

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

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

Диагностика неудачных запросов

Когда что-то идёт не так, идите от структуры запроса наружу. Большинство сбоев сводится к нескольким причинам.

Вызов отправки возвращает ошибку

• Неверная строка модели. kling-4.0/image-to-video должна совпадать точно, включая регистр и слэш. Выведите строку, которую вы фактически отправляете, а не доверяйте исходному файлу.
• Аутентификация отклонена. Убедитесь, что заголовок — Authorization: Bearer <key>, а не голый ключ и не параметр запроса, — и что переменная окружения задана в той же оболочке или процессе, который выполняет запрос.
• Изображение недоступно. Изображение должно быть доступно платформе по HTTPS. URL localhost, приватные бакеты или хосты с защитой от хотлинкинга не подойдут. Откройте URL в окне инкогнито и убедитесь, что он разрешается без аутентификации.
• Поле отсутствует или названо неверно. Тело вкладывает входные данные модели в input. Помещение prompt или image на верхний уровень, а не внутрь input, — частая ошибка; ошибка валидации обычно указывает имя поля.
• Тип содержимого. Отправка JSON-тела без Content-Type: application/json будет отклонена ещё до обращения к модели.

Задача создана, но так и не завершилась успешно

• Слишком мало опроса или его отсутствие. Проверьте, что ваш цикл действительно выполняется и что он сравнивает значения статуса с теми, что возвращает API. Опечатка в проверке терминального статуса приведёт к бесконечному циклу.
• Задача перешла в failed. Прочитайте сообщение об ошибке в объекте задачи; оно обычно указывает на входные данные — например, на изображение, которое не удалось декодировать.
• Вы достигли дедлайна. Если задание всё ещё выполняется около таймаута, увеличьте верхний предел, а не отправляйте повторно снова и снова — это лишь увеличит нагрузку и затраты.
• Срок ссылки на вывод истёк. Если задача успешна, но загрузка возвращает 404, значит между завершением и получением прошло слишком много времени. Скачивайте сразу после успеха.

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