HiAPI
Блог

Руководство

Как использовать kling-4.0-flash для генерации видео из изображения через HiAPI API: curl и Python

Практическое руководство по запросам: ввод изображения первого кадра, опрос асинхронной задачи, синхронное аудио и устранение ошибок

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

Что делает эндпоинт kling-4.0-flash для генерации видео из изображения

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

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

Разделяйте в голове эти три понятия, поскольку они соответствуют трём разным частям клиента:

  • Отправка — отправляемый вами payload: изображение первого кадра, промпт и параметры генерации.
  • Ссылка на задачу — идентификатор, возвращаемый при отправке, используемый для последующего запроса этой задачи.
  • Получение результата — повторяющаяся проверка статуса, которая в итоге возвращает готовое видео (или ошибку).

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

Перед отправкой запроса

Перед первым вызовом нужно подготовить три вещи.

1. Учётные данные API

Вам нужен ключ HiAPI API. Каждый запрос передаёт его как bearer-токен через заголовок Authorization. Не включайте его в систему контроля версий — читайте из переменной окружения, а не вставляйте в скрипт.

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

2. Путь эндпоинта

Все вызовы выполняются через единый интерфейс HiAPI. Идентификатор модели, к которой вы обращаетесь, — kling-4.0-flash/image-to-video. Ваш запрос на отправку и последующие запросы статуса указывают на одно и то же пространство имён модели, поэтому храните этот идентификатор в константе в коде, а не разбрасывайте строковые литералы повсюду.

3. Подготовленное изображение первого кадра

Вам нужно изображение, которое станет начальным кадром. Перед отправкой определите две вещи:

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

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

Также подготовьте короткий, конкретный промпт. Промпты для генерации видео из изображения работают лучше всего, когда описывают движение и изменение (что движется, как движется камера), а не пересказывают то, что уже видно в кадре.

Рабочий curl-запрос

Ниже приведён полный вызов отправки. Замените заполнители своими ключом, изображением и промптом.

curl -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Slow dolly-in on the subject as light shifts across the scene",
    "image": "https://your-host.example/first-frame.jpg"
  }'

Разберём по пунктам:

  • -X POST — отправка является операцией записи, а не запросом.
  • URL — идентификатор модели является частью пути единого эндпоинта. Это единственное место, где вы указываете модель.
  • Authorization: Bearer $HIAPI_API_KEY — заголовок, разворачиваемый оболочкой из вашей переменной окружения. Заключение в двойные кавычки позволяет развернуть переменную, сохраняя её значение одним аргументом.
  • Content-Type: application/json — тело запроса является JSON; без этого заголовка некоторые шлюзы отклонят или неверно разберут payload.
  • -d '{ ... }' — тело JSON. prompt описывает движение; image задаёт первый кадр. Каждое поле явное — ничто не зависит от позиции или невидимых вам значений по умолчанию.

Успешная отправка возвращает JSON-тело, содержащее идентификатор задачи. Захватите его — это значение является вашим дескриптором для работы с задачей. Если вы исследуете в интерактивном режиме, можете прогнать ответ через инструмент форматирования JSON, чтобы скопировать идентификатор:

curl -s -X POST "https://api.hiapi.ai/v1/models/kling-4.0-flash/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Slow dolly-in as light shifts","image":"https://your-host.example/first-frame.jpg"}' | python -m json.tool

Не думайте, что видео находится в этом ответе. Это не так — этот ответ лишь сообщает, что задача принята.

Тот же запрос на Python

Python-клиент полностью соответствует curl-payload. Смена языка не меняет семантику, лишь механизм отправки байтов. Используйте requests и читайте ключ из переменной окружения:

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-4.0-flash/image-to-video"
BASE_URL = "https://api.hiapi.ai/v1/models"

def submit_job(prompt: str, image: str) -> dict:
    response = requests.post(
        f"{BASE_URL}/{MODEL}",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "prompt": prompt,
            "image": image,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

job = submit_job(
    prompt="Slow dolly-in on the subject as light shifts across the scene",
    image="https://your-host.example/first-frame.jpg",
)
print(job)

Ключевые моменты переноса:

  • json= вместо -d — передача dict позволяет requests сериализовать тело и установить тип содержимого. Вы получаете тот же формат на проводе, что и в примере с curl, без ручного написания JSON.
  • raise_for_status() — преобразует не-2xx ответы в исключения, чтобы вы не приняли тело ошибки за ссылку на задачу.
  • timeout=30 — отправка должна быть быстрой. Достаточно щедрый тайм-аут предотвращает зависание соединения, не скрывая действительно медленных вызовов.
  • Одна константа для модели — если позже смените модель, измените только одну строку.

Возвращаемый dict содержит идентификатор задачи, который используется в следующем разделе.

Жизненный цикл асинхронной задачи

Схема интеграции — сначала отправить, затем опрашивать. Две фазы, чётко разделённые.

Фаза 1: отправить и захватить ссылку

Вызов submit_job из предыдущего раздела возвращает JSON-тело, содержащее идентификатор задачи. Сохраните его. Он нужен для каждой последующей проверки статуса, и его потеря означает потерю задачи.

Фаза 2: опрос до терминального состояния

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

import time

def wait_for_job(task_id: str, attempts: int = 60, interval: float = 5.0) -> dict:
    for _ in range(attempts):
        response = requests.get(
            f"{BASE_URL}/{MODEL}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"task_id": task_id},
            timeout=30,
        )
        response.raise_for_status()
        status = response.json()

        state = status.get("status")
        if state in ("succeeded", "failed"):
            return status
        time.sleep(interval)

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

Проектные решения, которые стоит принять осознанно:

  • Ограничьте число итераций. Никогда не опрашивайте бесконечно. Максимальное число попыток плюс фиксированный интервал дают предсказуемое худшее время ожидания.
  • Спите между проверками, а не внутри запроса. Слишком частый опрос тратит квоту и может вызвать ограничение скорости.
  • Считайте ошибку терминальным состоянием. Проваленная задача не станет успешной при следующем опросе — остановитесь и выявите ошибку.
  • Различайте ожидание и завершение. Только терминальное состояние завершает цикл; любое другое состояние означает продолжать ждать.
  • Сохраняйте ID задачи. Если процесс упадёт посреди опроса, вы захотите восстановиться, а не генерировать заново.

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

Использование опции синхронного аудио

Эндпоинт предоставляет опцию синхронного аудио. На практике для клиента это означает одно: если её включить, вызов будет блокироваться до завершения генерации, а не возвращать ссылку на задачу для опроса.

Это конкретным образом меняет ваш дизайн:

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

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

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

Диагностика типичных сбоев

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

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

401 или 403 означают, что учётные данные отсутствуют, имеют неверный формат или отклонены. Проверьте, что HIAPI_API_KEY действительно установлен в окружении, которое видит ваш процесс — переменная, экспортированная в одной оболочке, не передаётся в другую оболочку или контейнер. Убедитесь, что заголовок Authorization имеет вид Bearer <key>, с одним пробелом и без лишних кавычек, принесённых копированием.

Ошибки формата payload

400 обычно означает, что тело запроса не разбирается или отсутствуют обязательные поля. Перепроверьте, отправляете ли вы Content-Type: application/json, валиден ли JSON (висячие запятые приводят к сбою), и присутствуют ли prompt и image как непустые строки. При отладке выводите тело, которое вы фактически отправляете, а не dict, который вы собирались отправить.

Проблемы с входным изображением

Эти проблемы обычно проявляются как ошибки валидации, а не как явные ошибки изображения. Проверяйте по порядку:

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

Сбои на уровне задачи

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

Тайм-аут цикла опроса

TimeoutError, выбрасываемый wait_for_job, означает, что ваши ограничения слишком жёсткие, а не что задача мертва. Увеличьте число попыток или интервал и проверьте, не опрашиваете ли вы ID задачи от более раннего, уже завершённого запуска.

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

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

Все статьи →

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

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

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