Kling V3.0 Motion Control API: Быстрый старт

Kling V3.0 Motion Control позволяет анимировать статичное изображение персонажа, извлекая движения из референсного видео и применяя их покадрово. Результат сохраняет внешность персонажа из вашего изображения, воспроизводя движения из видео — этот метод называется переносом движения. В этом руководстве рассматриваются эндпоинт Novita AI, необходимые входные данные, ключевые параметры и рабочие примеры на Python и curl, которые можно запустить с реальным API-ключом.

Когда Motion Control — правильный инструмент

Motion Control подходит, если у вас есть две вещи: статичное изображение персонажа, которое вы хотите анимировать, и референсное видео, движения из которого нужно воспроизвести. Это отличается от функции «Изображение в видео» (I2V), которая генерирует движение на основе промпта. В случае Motion Control движение копируется из референсного видео точно — у выходного персонажа будет такая же траектория движений, как у человека в референсном видео.

Используйте Motion Control, когда:

• Вы хотите применить конкретный танец, походку или жест к иллюстрации или фото персонажа
• Вам нужны согласованные, повторяемые движения для разных персонажей (одно и то же референсное видео, разные изображения)
• Вы создаёте контент, где качество движений имеет значение, а результаты I2V с открытым промптом слишком непредсказуемы

Не используйте Motion Control, если само движение ещё не определено — в этом случае I2V с описательным промптом даёт больше гибкости при меньшей стоимости.

Шаг 1: Получите API-ключ Novita

Зарегистрируйтесь на novita.ai и создайте API-ключ в панели управления. Новые аккаунты получают бесплатные кредиты, которые можно использовать для тестирования Motion Control перед переходом на промышленные объёмы.

Шаг 2: Подтвердите эндпоинт и ID модели

Kling V3.0 Motion Control на Novita AI использует стандартный асинхронный шаблон для видео:

Отправка задачи:

POST https://api.novita.ai/v3/async/kling-v3.0-motion-control

Опрос результата:

GET https://api.novita.ai/v3/async/task-result?task_id={task_id}

Все запросы требуют:

Authorization: Bearer YOUR_NOVITA_API_KEY
Content-Type: application/json

Полная документация: novita.ai/docs/api-reference/model-apis-kling-v3.0-motion-control

Шаг 3: Подготовьте входные данные

Motion Control требует два входных данных: референсное изображение и референсное видео. Их правильная подготовка — самый важный фактор качества результата.

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

Это персонаж, внешность которого будет сохранена в выходном видео. Требования:

• Форматы: JPEG, PNG, JPG
• Максимальный размер: 10 МБ
• Минимальное разрешение: 340 пикселей по каждой стороне
• Соотношение сторон: от 2:5 до 5:2
• Персонаж должен быть чётко виден, занимать более 5% площади изображения и не иметь сильных перекрытий (не обрезайте голову или тело)

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

Референсное видео

Это источник движений. Персонаж в выходном видео будет повторять движения из этого видео:

• Форматы: MP4, MOV
• Максимальный размер: 10 МБ
• Длительность: 3–30 секунд
• Минимальное разрешение: 340 пикселей по каждой стороне
• Соотношение сторон: от 2:5 до 5:2
• Человек в референсном видео должен быть виден полностью или хотя бы верхняя часть тела, включая голову, без преград

Чёткий, хорошо освещённый материал с минимальным фоном передаёт движения точнее, чем шумные или перегруженные кадры.

Шаг 4: Отправьте первый запрос

Минимальный запрос curl:

curl --request POST \
  --url https://api.novita.ai/v3/async/kling-v3.0-motion-control \
  --header 'Authorization: Bearer $NOVITA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "image": "https://example.com/character.jpg",
    "video": "https://example.com/reference_motion.mp4",
    "prompt": "A person performing a smooth dance routine, cinematic lighting",
    "model_name": "kling-v3.0-motion-control",
    "character_orientation": "video"
  }'

Ответ возвращает task_id немедленно:

{
  "task_id": "abc123xyz"
}

Шаг 5: Опрашивайте результат

Kling V3.0 Motion Control — асинхронный. Отправьте задачу, затем опрашивайте, пока статус не станет succeed:

curl --request GET \
  --url 'https://api.novita.ai/v3/async/task-result?task_id=abc123xyz' \
  --header 'Authorization: Bearer $NOVITA_API_KEY'

Когда задача завершена, ответ содержит массив videos с URL выходного видео:

{
  "task": {
    "status": "succeed"
  },
  "videos": [
    {
      "video_url": "https://cdn.novita.ai/output/abc123xyz.mp4",
      "video_url_ttl": "3600"
    }
  ]
}

Типичное время генерации — 30–120 секунд в зависимости от длительности видео и режима. Опрашивайте каждые 5–10 секунд, не нагружайте эндпоинт частыми запросами.

Полный пример интеграции на Python

Этот скрипт отправляет задачу Motion Control и опрашивает до завершения:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"

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

def submit_motion_control(image: str, video: str, prompt: str = "") -> str:
    payload = {
        "image": image,
        "video": video,
        "prompt": prompt,
        "model_name": "kling-v3.0-motion-control",
        "character_orientation": "video",
    }
    resp = requests.post(f"{BASE_URL}/v3/async/kling-v3.0-motion-control", json=payload, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()["task_id"]


def poll_result(task_id: str, timeout: int = 300) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            params={"task_id": task_id},
            headers=HEADERS,
        )
        resp.raise_for_status()
        data = resp.json()
        status = data.get("task", {}).get("status")
        if status == "succeed":
            return data["videos"][0]["video_url"]
        if status == "failed":
            raise RuntimeError(f"Task failed: {data}")
        time.sleep(8)
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


if __name__ == "__main__":
    image = "https://example.com/character.jpg"
    video = "https://example.com/reference_motion.mp4"

    print("Submitting task...")
    task_id = submit_motion_control(image, video, prompt="smooth dance routine, warm lighting")
    print(f"Task ID: {task_id}")

    print("Polling for result...")
    output_url = poll_result(task_id)
    print(f"Output video: {output_url}")

Справочник параметров API

Параметр	Тип	Обязательный	Описание
image	string	Да	URL изображения персонажа для анимации. См. требования к входным данным выше.
video	string	Да	URL референсного видео, движения из которого будут перенесены.
model_name	string	Да	Установите kling-v3.0-motion-control.
prompt	string	Нет	Текстовое описание желаемого стиля движения или контекста сцены. Необязательно, но может улучшить качество результата.
character_orientation	string	Нет	Управляет выравниванием позы и длительностью выходного видео. "video" соответствует ориентации референсного видео — лучше для сложных движений всего тела, поддерживает до 30 секунд. "image" соответствует ориентации изображения персонажа — лучше для движений относительно камеры, фиксированные 5 секунд.

character_orientation на практике

Если ваше референсное видео показывает танцора фронтально и ваше изображение персонажа тоже фронтально, "video" даст лучший перенос движений и поддерживает до 30 секунд. Если в референсном видео камера движется вокруг объекта, а ваше изображение — это портрет с фиксированного ракурса, "image" часто уменьшает нежелательные искажения перспективы — но учтите, что выходной ролик будет длиться ровно 5 секунд.

Стандартный и Pro: какой уровень качества выбрать

Kling V3.0 Motion Control доступен в двух уровнях качества:

Standard выводит видео в разрешении 720p. Это хороший выбор для итераций, проверки совместимости движений или создания черновиков перед финальной версией.

Pro выводит видео в разрешении 1080p с улучшенной точностью движений и согласованностью объекта. Используйте Pro, когда:

• Результат идёт в готовый продукт (пост в соцсетях, короткометражка, демо продукта)
• Важны мелкие детали лица или одежды персонажа
• Вы генерируете длинные клипы (10+ секунд), где ухудшение качества со временем более заметно

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

Ценообразование, длительность и оценка стоимости

Novita AI тарифицирует Motion Control за секунду сгенерированного видео. Уровни Standard и Pro имеют разные тарифы за секунду. Актуальные цены смотрите на странице модели Novita AI.

Ограничения по длительности:

• character_orientation: "video" — до 30 секунд
• character_orientation: "image" — фиксированные 5 секунд

Стоимость масштабируется с длительностью в режиме "video". Режим "image" всегда генерирует 5-секундный клип.

Устранение распространённых ошибок

Задача сразу завершается с ошибкой 422 или ошибкой валидации Проверьте, что оба URL (image и video) являются общедоступными (не защищены аутентификацией или временными предварительно подписанными ссылками, срок действия которых истёк). Бэкенд Novita должен иметь возможность загрузить оба файла во время выполнения задачи.

Выходное движение выглядит странно или персонаж искажается Наиболее частая причина — несоответствие ориентации персонажа в изображении и референсном видео. Попробуйте переключить character_orientation между "video" и "image", чтобы увидеть, какой вариант даёт лучшее совпадение.

Персонаж теряет идентичность лица в середине клипа Убедитесь, что у персонажа на референсном изображении чёткое, не перекрытое лицо и тело. Для длинных клипов уровень Pro лучше сохраняет согласованность объекта, чем Standard.

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

Статус зависает на processing более 3 минут Иногда возникают задержки в очереди. Подождите до 5 минут, прежде чем считать задачу зависшей. Если она остаётся в таком состоянии, отправьте новую задачу — не используйте старый task_id.

Что разработчики создают с помощью Kling Motion Control

Анимация персонажей для игровых ассетов: Возьмите иллюстрацию персонажа и примените референсный клип движений (ходьба, бег, атака) без риггинга или анимационного ПО.

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

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

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

FAQ

В чём разница между Motion Control и Image-to-Video на Novita AI?

Image-to-Video (I2V) анимирует изображение на основе текстового промпта — движение генерируется моделью из вашего описания. Motion Control переносит конкретные движения из референсного видео на персонажа в вашем изображении. Motion Control даёт точные, воспроизводимые движения; I2V — творческую гибкость без необходимости референсного клипа.

Должен ли персонаж референсного видео соответствовать внешности персонажа на изображении?

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

Могу ли я использовать любое общедоступное видео в качестве референсного?

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

Сколько времени занимает генерация?

Обычно 30–120 секунд в зависимости от длительности выходного видео и выбранного режима (Standard или Pro). Опрашивайте каждые 8–10 секунд, а не в плотном цикле.

Рекомендуемые статьи

• Kling O1 на Novita AI: T2V, I2V, Ref2V и режимы редактирования видео
• Kling 3.0 уже на Novita AI: кинематографическая генерация AI-видео в масштабе
• Kling V2.5 Turbo API на Novita AI