HiAPI
Блог

Руководство

Как вызывать kling-4.0-flash Reference-to-Video через HiAPI API: практика с curl и Python

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

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

Когда использовать генерацию видео по референсным изображениям вместо генерации по тексту

Генерация видео по тексту — инструмент сценариста: вы описываете сцену, и модель создаёт всё с нуля. Генерация по референсным изображениям — инструмент режиссёра: вы даёте модели одно или несколько изображений и требуете создать движение, в котором эти субъекты, стиль или композиция остаются узнаваемыми. На HiAPI это различие проявляется на уровне эндпоинта — kling-4.0-flash/reference-to-video это отдельный маршрут, отличный от обычного вызова генерации видео по тексту; заблаговременный выбор правильного эндпоинта избавляет от промпт-инжиниринга, который так и не сможет полностью воспроизвести конкретный внешний вид.

Выбирайте генерацию по референсным изображениям, если выполняется любое из следующих условий:

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

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

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

Структура запроса: референсные изображения и ключевые параметры

Эндпоинт принимает JSON-тело запроса. Части, с которыми вы реально будете работать, делятся на три категории: референсные изображения, промпт и параметры формирования вывода.

Референсные изображения

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

  • Используйте публично доступные HTTPS URL или URL, к которым имеет доступ ваш аккаунт. Локальные пути к файлам и URI file:// не могут быть загружены удалённым сервисом.
  • Предпочитайте стабильный хостинг, а не подписанные ссылки, истекающие через несколько минут — длительные задачи могут загружать их в момент, который вы не ожидали.
  • Каждое изображение должно быть сфокусированным. Чистое изображение субъекта полезнее, чем загромождённый коллаж, поскольку модели нужно разобраться в том, что она видит.
  • Порядок может влиять на то, как интерпретируются референсные изображения, поэтому в коде порядок массива должен быть детерминированным, а не зависеть от порядка итерации словаря.

Промпт

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

Параметры формирования вывода

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

Ментальная модель проста: референсные изображения определяют что, промпт определяет как движется, параметры определяют что вы получите в ответ.

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

Прежде чем писать клиентский код, самый надёжный способ проверить тело запроса — один вызов curl. Сохраните учётные данные и входные данные в shell-переменных, чтобы JSON оставался читаемым, и отправьте запрос.

API_KEY="$HIAPI_API_KEY"
BASE_URL="https://api.hiapi.ai"   # используйте базовый URL, отображаемый в вашей консоли

curl -sS -X POST "$BASE_URL/v1/kling-4.0-flash/reference-to-video" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Персонаж поворачивается к окну, камера медленно наезжает; мягкий утренний свет, спокойный темп.",
    "reference_images": [
      "https://your-cdn.example.com/refs/character-front.png",
      "https://your-cdn.example.com/refs/location-window.jpg"
    ]
  }'

Проверьте три вещи перед запуском:

  1. Путь и префикс версии. Сверьте точный маршрут с документацией эндпоинта для вашего аккаунта; путь содержит номер версии, и устаревший префикс вернёт «не найдено», а не ошибку валидации.
  2. Заголовок аутентификации. Ключ передаётся как bearer-токен в заголовке Authorization. Никогда не помещайте его в тело запроса или строку запроса, иначе он утечёт в логи.
  3. Заполнители. Каждое значение, требующее замены, очевидно является заполнителем — комментарий к базовому URL, два URL CDN, промпт. Прежде чем объявить готовым к продакшену, поищите example.com в запросе.

Успешная отправка возвращает идентификатор задачи, а не готовое видео. Захватите этот идентификатор из тела ответа; он понадобится на следующем шаге при опросе. Прогон ответа через JSON-форматтер (| jq .) делает ID задачи легко заметным — стоит выработать эту привычку.

Та же самая вызов на Python

Основное различие в Python-версии — способ построения тела запроса: создайте dict, сериализуйте один раз и разделите функцию отправки запроса и логику опроса, чтобы каждую можно было тестировать отдельно.

import os
import requests

BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
API_KEY = os.environ["HIAPI_API_KEY"]

REFERENCE_IMAGES = [
    "https://your-cdn.example.com/refs/character-front.png",
    "https://your-cdn.example.com/refs/location-window.jpg",
]

def submit_reference_video(prompt: str) -> str:
    payload = {
        "prompt": prompt,
        "reference_images": REFERENCE_IMAGES,
    }
    response = requests.post(
        f"{BASE_URL}/v1/kling-4.0-flash/reference-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["task_id"]

if __name__ == "__main__":
    task_id = submit_reference_video(
        "Персонаж поворачивается к окну, камера медленно наезжает."
    )
    print("submitted:", task_id)

Следующие меры предосторожности избавят от ненужных страданий:

  • Читайте ключ из переменных окружения. Жёстко закодированные ключи в конечном итоге попадают в историю git и скриншоты.
  • Используйте json=, а не data=, чтобы клиент правильно задал тип содержимого и экранировал тело запроса.
  • Задайте явный timeout. Бесконечное ожидание по умолчанию превращает зависшее соединение в висящий рабочий процесс.
  • Вызывайте raise_for_status() перед разбором ответа, чтобы тела ответов 4xx сообщались как ошибки HTTP, а не вызывали загадочный KeyError при работе с JSON ответа.
  • Сверьте с документацией имя поля ответа, содержащего идентификатор задачи, вместо того чтобы предполагать task_id; соответствующим образом скорректируйте строку извлечения.

Пусть submit_reference_video возвращает только ID. Опрос — отдельная задача, и он должен находиться в собственной функции.

Обработка жизненного цикла асинхронной задачи

Генерация видео требует времени, поэтому эндпоинт по своему устройству асинхронный. Вызов отправки быстро возвращает идентификатор задачи; фактическая работа происходит после этого. Ваша интеграция должна это моделировать, и простейшая корректная модель имеет три состояния: pending или processing (продолжайте ждать), succeeded (получите вывод), failed (прочитайте ошибку и остановитесь).

Опрашивайте эндпоинт задачи с интервалом и задавайте верхнюю границу общего времени ожидания:

import time

def wait_for_task(task_id: str, interval: float = 5.0, max_wait: float = 600.0) -> dict:
    deadline = time.monotonic() + max_wait
    url = f"{BASE_URL}/v1/tasks/{task_id}"
    while time.monotonic() < deadline:
        r = requests.get(url, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")

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

Правила опроса, которые стоит принять как можно раньше:

  • Постепенное увеличение задержки. Фиксированный короткий интервал без пользы бомбардирует API. Начните с умеренного значения и увеличивайте паузу между попытками.
  • Всегда ограничивайте цикл. while True вокруг удалённой задачи — это ожидание сбоя. Приведённый дедлайн выдаёт исключение вместо зависания.
  • Сохраняйте ID задачи. Если ваш процесс упадёт после отправки, этот ID — единственный способ восстановить результат, не заплатив за вторую генерацию.
  • Считайте failed конечным состоянием. Не повторяйте попытку через повторный опрос неудачной задачи; прочитайте ошибку и при необходимости повторно отправьте исправленное тело запроса.
  • Явно обрабатывайте истечение срока. Результаты задач могут быть недоступны навсегда, поэтому сразу после успеха задачи скачивайте и сохраняйте вывод.

Частые ошибки и способы их исправления

Большинство сбоев первых интеграций сводится к нескольким категориям. Прежде чем менять код, сопоставьте симптом с причиной.

Ошибки аутентификации и авторизации

401 или 403 почти всегда означают неверные, отсутствующие или неправильно ограниченные учётные данные. Проверьте, что заголовок в точности Authorization: Bearer <key>, что переменная окружения действительно заполнена в процессе, выполняющем вызов (экспорт в shell не передаётся в systemd-юнит), и что ключ не был ротирован или отозван.

Проблемы с референсными изображениями

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

Недействительное тело запроса

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

Ошибки маршрута или метода

404 обычно означает неверный путь, а не недоступность модели. Перепроверьте префикс версии и имя эндпоинта по документации и убедитесь, что отправка использует POST, а запрос состояния задачи — GET.

Тайм-ауты и ошибки опроса

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

Ограничения скорости

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

Производственный чек-лист перед запуском

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

  • Конфигурация. Храните базовый URL и API-ключ в переменных окружения или менеджере секретов, никогда в исходном коде. Задайте путь эндпоинта константой, чтобы обновление версии требовало изменения одной строки.
  • Повторы с задержкой. Для временных сбоев — сбросов соединения, 429, 5xx — используйте экспоненциальную задержку с джиттером. Не повторяйте ошибки валидации 4xx; они провалятся так же.
  • Идемпотентная дисциплина. Записывайте каждый отправленный ID задачи и его входные данные. При перезапуске восстанавливайте опрос существующих задач, а не отправляйте новые.
  • Ограниченное ожидание. Задайте явные тайм-ауты как для HTTP-клиента, так и для цикла опроса, и направляйте тайм-ауты в путь мёртвых писем для ручной проверки, а не отбрасывайте молча.
  • Структурированное логирование. Записывайте ID задачи, переходы состояний с временными метками, время отправки и завершения, а также тело ошибки при сбое. Маскируйте ключи и усекайте промпты, когда они содержат пользовательские данные.
  • Обработка вывода. Сразу после успеха задачи скачивайте сгенерированные медиа в собственное хранилище и проверяйте результат перед показом пользователю.
  • Видимость затрат. Биллинг зависит от использования, поэтому отслеживайте, сколько задач отправлено на каждую функцию и каждого пользователя. Циклы повторов, повторно отправляющие запросы в условиях неопределённости, — самая частая причина непредвиденных расходов.
  • Гигиена входных данных. Проверяйте у себя референсные URL и длину промпта. Локальный перехват плохого URL быстрее и дешевле одного сетевого обмена.

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

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

Все статьи →

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

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

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