HiAPI
Блог

Руководство

Как использовать kling-3.0/motion-control через HiAPI API: примеры на curl и Python

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

Назначение kling-3.0/motion-control и когда его выбирать

Управление движением — это класс возможностей в генерации видео: вы передаёте модели опорное видео, и оно задаёт движение, ритм и композицию в результате, а не только текстовый промпт с описанием действия. При использовании kling-3.0/motion-control в HiAPI API опорное видео является основным входом: оно задаёт, как движется объект, а остальные параметры формируют контент, генерируемый вокруг этого движения.

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

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

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

Предварительные условия и настройка эндпоинта

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

1. API-ключ

Создайте ключ в консоли аккаунта HiAPI.ai и сохраните его в переменной окружения, а не в исходном коде:

export HIAPI_API_KEY="your_api_key_here"

Отправляйте его с каждым запросом как bearer token: Authorization: Bearer $HIAPI_API_KEY.

2. Соглашение о базовом URL

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

export HIAPI_BASE_URL="https://api.hiapi.ai"

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

Модель выбирается для каждого запроса через поле model в запросе, используя точный идентификатор kling-3.0/motion-control. Не хардкодьте его во многих местах — передавайте его как константу, чтобы будущая смена модели требовала изменения одной строки.

Вам также понадобится размещённое место, откуда API сможет получить опорное видео. Обычно это подписанный URL с ограниченным сроком действия; убедитесь, что к нему можно получить доступ без пользовательских заголовков или cookie.

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

Передача опорного видео и параметров движения

Запрос управления движением концептуально делится на две половины: источник движения (ваше опорное видео) и параметры генерации (что модель должна создать).

Опорное видео

Опорное видео передаётся в теле запроса в виде URL, а не как необработанные байты в JSON-полезной нагрузке. Два практических правила:

  • Используйте URL, который остаётся действительным всё время, пока задача стоит в очереди и обрабатывается. Подписанные URL, истекающие раньше времени, — частая причина сбоя задачи через несколько минут после отправки.
  • Держите видео коротким и со стабильным изображением. Слишком длинные, сильно дрожащие или часто монтируемые опорные материалы дают модели неоднозначный сигнал движения.

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

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

Параметры, обычно задаваемые вместе с опорным видео:

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

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

Наконец, проверьте перед отправкой: URL опорного видео возвращает тип содержимого media, промпт не пуст, все числовые настройки в пределах документации. Локальная проверка занимает миллисекунды; отклонённая асинхронная задача стоит одного круга обмена и путаницы.

Асинхронные задачи: отправка, опрос и чтение результата

Управление движением не возвращает видео в ответе на отправку, а возвращает задачу, за которой вам нужно следить. Стройте клиент вокруг этого жизненного цикла с самого начала.

Шаг 1 — отправка

Отправьте POST-запрос к эндпоинту модели. Успешная отправка возвращает идентификатор задачи. Немедленно сохраните этот ID — это единственный дескриптор для работы с задачей, он используется при опросе и в запросах поддержки.

Шаг 2 — опрос

Получите статус задачи GET-запросом по этому ID. Поле статуса скажет, в какой из трёх ситуаций вы находитесь:

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

Цикл опроса должен явно проверять терминальные состояния, а не только наличие поля вывода. У неудачной задачи нет результата, и трактовка «пока нет результата» как «всё ещё выполняется» приведёт к бесконечному циклу.

Шаг 3 — чтение результата

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

Правила опроса

Два правила обеспечивают надёжность в продакшене:

  1. Делайте задержку между опросами (начиная с одной-двух секунд, затем увеличивая), а не бомбите эндпоинт.
  2. Ограничьте общее время ожидания и выставляйте тайм-аут как ошибку, допускающую повтор, а не блокируйте рабочий поток навсегда.

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

Готовый к запуску запрос curl

Ниже полный процесс в shell. Он отправляет задачу, извлекает ID задачи и затем опрашивает до перехода задачи в терминальное состояние.

#!/usr/bin/env bash
set -euo pipefail

BASE="$HIAPI_BASE_URL"
MODEL="kling-3.0/motion-control"

# 1) Отправить задачу
SUBMIT=$(curl -sS -X POST "$BASE/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/motion-control",
    "prompt": "Бумажный кораблик плывёт по городской улице под дождём, кинематографично",
    "reference_video_url": "https://your-bucket.example.com/refs/pan-left.mp4",
    "duration": 5,
    "aspect_ratio": "16:9"
  }')

echo "$SUBMIT"

TASK_ID=$(echo "$SUBMIT" | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')
echo "task: $TASK_ID"

# 2) Опрашивать до терминального состояния
while true; do
  STATUS_JSON=$(curl -sS "$BASE/v1/videos/generations/$TASK_ID" \
    -H "Authorization: Bearer $HIAPI_API_KEY")
  STATUS=$(echo "$STATUS_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin)["status"])')
  echo "status: $STATUS"

  case "$STATUS" in
    succeeded) echo "$STATUS_JSON"; break ;;
    failed|cancelled) echo "$STATUS_JSON" >&2; exit 1 ;;
  esac

  sleep 3
done

Два замечания по адаптации этого скрипта. Во-первых, храните идентификатор модели и путь эндпоинта в переменных, чтобы скрипт оставался читаемым. Во-вторых, разбор выше не использует jq, только Python, потому что Python доступен почти везде; если предпочитаете jq, можете заменить. В любом случае ключевое поведение одинаково: извлечь ID задачи из ответа на отправку, затем опрашивать её статус, пока не увидите терминальное значение.

Тот же запрос (версия для Python)

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

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kling-3.0/motion-control"

HEADERS = {
    "Authorization": f"Bearer {KEY}",
    "Content-Type": "application/json",
}

TERMINAL = {"succeeded", "failed", "cancelled"}


def submit_job(prompt: str, reference_video_url: str, duration: int = 5) -> str:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "reference_video_url": reference_video_url,
        "duration": duration,
        "aspect_ratio": "16:9",
    }
    r = requests.post(
        f"{BASE}/v1/videos/generations",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    r.raise_for_status()
    return r.json()["id"]


def wait_for_job(task_id: str, timeout_s: int = 600) -> dict:
    deadline = time.time() + timeout_s
    delay = 2.0
    while time.time() < deadline:
        r = requests.get(
            f"{BASE}/v1/videos/generations/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status in TERMINAL:
            return data
        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task_id = submit_job(
        prompt="Бумажный кораблик плывёт по городской улице под дождём, кинематографично",
        reference_video_url="https://your-bucket.example.com/refs/pan-left.mp4",
    )
    print("submitted:", task_id)
    result = wait_for_job(task_id)

    if result["status"] == "succeeded":
        print("output:", result.get("output"))
    else:
        print("job did not succeed:", result)

Что стоит сохранить при адаптации: набор терминальных состояний, задержку с верхним пределом и отдельные функции отправки и ожидания. В реальном сервисе вы разделите их на два процесса — отправка из обработчика запросов, сохранение ID задачи, опрос в worker — чтобы медленная задача никогда не блокировала HTTP-ответ.

Частые точки отказа и способы их отладки

Большинство проблем интеграции с kling-3.0/motion-control попадает в несколько категорий. Проверяйте по порядку.

Ошибки аутентификации и модели

401 почти всегда означает, что bearer token отсутствует, обрезан или взят из неверного окружения. Ошибка «модель не найдена» означает, что строка model не совпадает полностью — это идентификатор, разделённый слэшем, поэтому неправильный порядок символов или лишний пробел молча провалятся в конфигурации и громко ошибутся в API.

Опорное видео недоступно

Задача принята, но через несколько минут завершается с ошибкой из-за невозможности получить опорный URL. Причины по частоте: подписанный URL истёк до обработки; URL требует заголовка аутентификации, который сервис не отправляет; URL возвращает HTML (страницу входа или ошибки), а не видео. Проверьте URL обычным curl извне вашей сети и подтвердите тип содержимого.

Неверный формат параметров или выход за пределы

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

Дефекты опроса

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

Истечение URL результата

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

Каждый сеанс отладки начинайте с записи точного тела запроса и сырого JSON ответа. Почти все вышеописанные проблемы видны в этих двух материалах. Когда будете готовы углубиться, обратитесь к другим видеомоделям и справочнику эндпоинтов в документации HiAPI.ai и сохраняйте ту же форму клиента «сначала отправка, затем опрос».

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

Все статьи →

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

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

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