Как создавать короткие видео с помощью kling-3.0/motion-control в API hiapi

Если вы когда-нибудь пытались заставить персонажа в сгенерированном видео выполнить конкретное движение — не «танец», а именно этот танец из именно этого фрагмента — вы знаете, что обычные варианты плохи: ручная ротоскопия кадр за кадром, переобучение модели движения или просто сдаться и принять то, что даст текстовый промпт. kling-3.0/motion-control обходит всё это. Вы даёте ему изображение персонажа и референсное видео, и он переносит движения и мимику из референса на вашего персонажа — без скелетной привязки, без ключевых кадров, без костюма захвата движения.

Эта статья проходит через реальный рабочий процесс короткого видео: сначала превращаем фотографию курьера в короткий референсный фрагмент, а затем используем этот фрагмент, чтобы через motion-control управлять совершенно другим изображением персонажа. Каждый запрос ниже — реальный вызов API /v1/tasks hiapi, каждый материал сгенерирован в процессе написания этой статьи (ничего не взято из демо-галереи вендора), и каждая цена получена в реальном времени из эндпоинта цен hiapi.

Что на самом деле делает kling-3.0/motion-control

Модель принимает два входных данных:

• image_url — один портрет персонажа («цель»). Он определяет, кто появится в выходном видео.
• video_url — референсный фрагмент движения, 3–30 секунд. Он определяет, что они делают.

На выходе получается видео, где целевой персонаж выполняет движения и мимику из референсного видео, отрендеренное в разрешении 720p или 1080p. Он не принимает текстовый промпт, длительность или соотношение сторон — композиция выхода напрямую следует за референсным фрагментом, а длина выхода соответствует длине входного фрагмента (наш 3-секундный референс вернул 3,03-секундный выход).

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

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

• API-ключ hiapi (Authorization: Bearer <key>)
• Публично доступное по HTTPS изображение персонажа (не ваша цель — ваш драйвер-персонаж)
• Второе изображение персонажа в качестве фактической цели, которую нужно анимировать
• ffmpeg/ffprobe, если вы хотите извлечь кадр обложки или проверить длительность фрагмента локально, как это сделано в этой статье

Реальная демонстрация: один фрагмент движения, два разных персонажа

Суть motion-control в том, что референсное видео и итоговый персонаж не обязаны совпадать. Чтобы это доказать, в этой демонстрации использованы три шага генерации:

1. Портрет курьера, анимированный в короткий референсный фрагмент:

Этот портрет превратился в 3-секундный фрагмент движения 480p через grok-imagine-1.5/image-to-video — это быстрый и дешёвый способ создать референсный фрагмент из статичного изображения вместо поиска готового фрагмента:

2. Совершенно другой целевой персонаж — то же движение, полностью другой вид:

3. Передайте оба в motion-control. Владелец закусочной выполняет точно такое же движение разворота и оглядывания, что и курьер:

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

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

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0/motion-control",
    "input": {
      "image_url": "https://static.hiapi.ai/blog/kling-3-0-motion-control-short-form-video/target-character.png",
      "video_url": "https://static.hiapi.ai/blog/kling-3-0-motion-control-short-form-video/motion-reference.mp4",
      "resolution": "720p"
    }
  }'

Ответ (задача создана, всё ещё обрабатывается):

{
  "code": 0,
  "data": {
    "taskId": "tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS",
    "status": "pending"
  },
  "success": true
}

Опрашивайте, пока не завершится:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS \
  -H "Authorization: Bearer $HIAPI_API_KEY"

В нашем запуске 3-секундный фрагмент 720p занял от начала до конца около 2,3 минуты (статус примерно десяток раз проходил цикл handling, прежде чем переключиться на success) — при проектировании цикла опроса reserve несколько минут, а не секунд. Финальный ответ:

{
  "code": 0,
  "data": {
    "taskId": "tk-hiapi-01M4CWNSYA7RB637YJ2QZMHMMS",
    "status": "success",
    "output": [
      {
        "type": "video",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M4CWNSYA7RB637YJ2QZMHMMS-0.mp4",
        "storage": "temp",
        "expireAt": 1792039027
      }
    ]
  },
  "success": true
}

Этот output[0].url — временная ссылка; expireAt — это Unix-временная метка, в наших тестах срок действия около 24 часов. Скачайте и перехостите немедленно; не ссылайтесь на неё напрямую из чего-либо, что вы публикуете.

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

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}


def create_motion_control_task(image_url: str, video_url: str, resolution: str = "720p") -> str:
    resp = requests.post(
        API_BASE,
        headers=HEADERS,
        json={
            "model": "kling-3.0/motion-control",
            "input": {
                "image_url": image_url,
                "video_url": video_url,
                "resolution": resolution,
            },
        },
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id: str, timeout_s: int = 600, poll_every: int = 10) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


if __name__ == "__main__":
    task_id = create_motion_control_task(
        image_url="https://your-cdn.example.com/target-character.png",
        video_url="https://your-cdn.example.com/motion-reference.mp4",
        resolution="720p",
    )
    output_url = wait_for_result(task_id)

    video_bytes = requests.get(output_url, timeout=120).content
    with open("motion-control-output.mp4", "wb") as f:
        f.write(video_bytes)
    print(f"saved {len(video_bytes)} bytes")

Ничего сложного — создайте задачу, опрашивайте GET /v1/tasks/{taskId} с интервалом, скачайте output[0].url в момент перехода в success и перехостите у себя, пока временная ссылка не истекла.

Параметры, которые motion-control действительно проверяет

Схема строгая — всё, что выходит за пределы этих трёх полей, будет отклонено; полезно знать это заранее, а не обнаруживать методом проб и ошибок:

Поле	Обязательно	Описание
image_url	Да	Публичный HTTPS URL, целевой персонаж
video_url	Да	Публичный HTTPS URL, референс движения 3–30 секунд
resolution	Нет (есть значение по умолчанию, но лучше указать)	"720p" или "1080p" — это также определяет ценовой уровень

Поля, которые вы, возможно, ожидаете от других видеомоделей — duration, aspect_ratio, prompt — будут отклонены с ошибкой схемы:

{
  "code": 1,
  "message": "input: Object { input } has unexpected additional properties: duration, aspect_ratio",
  "success": false
}

Это сделано намеренно: длина и композиция выхода полностью наследуются от референсного видео, поэтому duration/aspect_ratio нечем управлять. Если вам нужен более длинный выход или другая композиция, обрежьте или перекомпонуйте референсный фрагмент перед отправкой, а не изменяйте запрос.

Ценообразование: оплата за секунду выхода, а не за запрос

Напрямую из эндпоинта цен hiapi:

Разрешение	Цена
720p	$0.10 / секунда выхода
1080p	$0.172 / секунда выхода

Биллинг определяется фактической длительностью выхода (estimated_seconds), которая отражает длину вашего референсного фрагмента — а не фиксированной платой за запрос. Наш 3-секундный референс дал 3,03-секундный выход в 720p и стоил около $0.30. 10-секундный референс в 1080p обойдётся примерно в $1.72. Если вы используете это массово в контент-календаре, реальный рычаг — длина референсного фрагмента: более короткие референсы дешевле и при этом всё ещё несут полноценное движение для коротких форматов (Reels, TikTok, Shorts), где 3–8 секунд часто и есть весь фрагмент.

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

• Осознанно выбирайте композицию драйвер-фрагмента. Выход наследует соотношение сторон, дистанцию камеры и ритм референсного видео — крупный план в референсе останется крупным планом в выходе, независимо от кадрирования вашего целевого изображения.
• Чёткая мимика переносится лучше, чем тонкая. Явный разворот, взмах рукой или наклон головы в референсе надёжно воспроизводятся на целевом персонаже; очень тонкие, естественные микровыражения сложнее для распознавания и переноса моделью.
• Используйте один референсный фрагмент для многих персонажей. Поскольку video_url и image_url полностью независимы, самая эффективная схема в контент-конвейере: сначала создать небольшую библиотеку референсных движений, а затем прогонять через один и тот же фрагмент множество разных изображений персонажей.
• Временные URL выхода живут недолго. expireAt обычно около суток — скачивайте и перехостите немедленно, а не откладывайте загрузку на потом.
• Обработка не мгновенная. В этом тесте 3-секундный фрагмент 720p занял от начала до конца более двух минут; планируйте цикл опроса и любую последующую автоматизацию в масштабе минут (а не секунд, как обычно при вызовах текст-в-изображение).

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

• Страница модели kling-3.0/motion-control
• Цены hiapi
• Документация API hiapi

Есть референсный фрагмент и персонаж, которого хотите с ним спарить? Получите ключ на странице цен и направьте curl-запрос выше на свои image_url/video_url — весь цикл выше можно скопировать и вставить как есть.

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

Могу ли я использовать любое видео в качестве референса движения? Подойдёт любое видео с чётким человеческим (или человекоподобным) исполнителем, если оно публично доступно по HTTPS и имеет длину 3–30 секунд. Оно не обязано содержать вашего целевого персонажа — в этом и смысл модели.

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

Почему мой запрос отклонён с «unexpected additional properties»? Схема принимает только image_url, video_url и resolution. Такие поля, как duration, aspect_ratio или prompt, не являются входными данными этой модели и немедленно возвращают 400 — удалите их из payload.

Сколько времени занимает задача motion-control? Заложите несколько минут на фрагмент. Наш 3-секундный пример 720p занял около 2,3 минуты от создания задачи до скачиваемого выхода success.

Могу ли я управлять разрешением выхода независимо от цены? Нет — resolution одновременно является настройкой качества выхода и селектором ценового уровня: "720p" тарифицируется по $0.10/секунда выхода, "1080p" — по $0.172/секунда выхода.