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

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

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

Motion Control — правильный инструмент, когда у вас есть две вещи: статичное изображение персонажа, которое вы хотите анимировать, и эталонное видео, движение которого вы хотите воспроизвести. Он отличается от Image-to-Video (I2V), который генерирует движение на основе текстового запроса. С Motion Control движение копируется из эталонного видео точно — выходной персонаж будет повторять ту же траекторию движения, что и человек в эталонном видео.

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

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

Не используйте его, когда само движение еще не определено — в этом случае 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

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

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

character_orientation на практике

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

Standard vs. 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) являются общедоступными (не за аутентификацией и не с истекшим короткоживущим presigned URL). Бэкенд Novita должен иметь возможность загрузить оба файла во время выполнения задачи.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Kling 3.0 Now on Novita AI: Cinematic AI Video Generation at Scale
• Kling V3.0 4K API Quick Start
• Kling V2.5 Turbo API on Novita AI