Kling V3 Motion Control

kling-v3-motion-control Kling V3 Motion Control создает видео с управлением движением на основе изображений и референсных видео.

Эндпоинты

POST /v1/queue/kling-v3-motion-control # Создать задачу

GET /v1/queue/kling-v3-motion-control/requests/{request_id}/status # Проверить статус

GET /v1/queue/kling-v3-motion-control/requests/{request_id}/response # Получить результат

PUT /v1/queue/kling-v3-motion-control/requests/{request_id}/cancel # Отменить задачу

Параметры запроса

curl --request 'POST' 'https://api.odirouter.ai/model/v1/queue/kling-v3-motion-control' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --location \
  --data-raw '{
  "image_url": "https://www.gstatic.com/webp/gallery/3.jpg",
  "video_url": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "character_orientation": "image",
  "mode": "std",
  "prompt": "A person dancing gracefully",
  "keep_original_sound": "yes"
}'

prompt string

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

Примечание: длина не должна превышать 2500 символов

image_url string required

Референсное изображение. Персонажи, фон и другие элементы в сгенерированном видео будут основываться на этом изображении.

Требования к изображению:

Поддерживается передача изображения в формате Base64 или по URL (URL должен быть публично доступен)

Примечание: при использовании Base64 не добавляйте перед строкой префиксы, например data:image/png;base64,; передавайте только саму Base64-строку

Поддерживаемые форматы: .jpg / .jpeg / .png

Размер файла не должен превышать 10MB; ширина и высота изображения должны быть в диапазоне от 300px до 65536px; соотношение сторон должно быть от 1:2.5 до 2.5:1

Требования к содержимому:

Пропорции персонажа должны по возможности соответствовать пропорциям в референсном видео с движением; не рекомендуется использовать движения всего тела для персонажа, показанного только по пояс

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

Избегайте экстремальной ориентации персонажа, например вверх ногами или лежа; персонаж должен занимать достаточную часть кадра

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

video_url string required

URL референсного видео. Движения персонажа в сгенерированном видео будут следовать этому референсу.

Требования к видео:

Поддерживаемые форматы: .mp4 / .mov; размер файла не должен превышать 100MB; ширина и высота должны быть в диапазоне от 340px до 3850px

Минимальная длительность: 3 секунды

Если character_orientation имеет значение image, максимальная длительность видео составляет 10 секунд

Если character_orientation имеет значение video, максимальная длительность видео составляет 30 секунд

Требования к содержимому:

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

Рекомендуется загружать видео с движением одного человека; если в кадре 2 или более человека, будет использовано движение персонажа, занимающего наибольшую часть кадра

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

Видео с действием должно быть снято одним непрерывным дублем, персонаж должен всегда оставаться в кадре; избегайте склеек и движений камеры, иначе видео может быть обрезано

Если действие сложное или быстрое, результат может быть короче загруженного видео

Генерация может начаться, когда модель извлечет минимум 3 секунды пригодного непрерывного действия; списанные кредиты не возвращаются

Избегайте слишком быстрых действий; более плавные движения обычно дают лучший результат

element_list array

Список референсных субъектов на основе ID из библиотеки субъектов. Сейчас поддерживается не более 1 субъекта.

Создание субъектов описано здесь: kling_custom_elements

"element_list": [
  {
    "element_id": 829836802793406551
  }
]

Примечание: при использовании субъектов сгенерированное видео пока может следовать только ориентации персонажа из референсного видео.

element_id long required

ID субъекта из библиотеки субъектов

keep_original_sound string

Сохранять ли исходный звук из референсного видео

По умолчанию: yes

Варианты: yes, no

character_orientation string required

Ориентация персонажа в сгенерированном видео

Варианты:

image: соответствует ориентации персонажа на референсном изображении; длительность референсного видео не должна превышать 10 секунд

video: соответствует ориентации персонажа в референсном видео; длительность референсного видео не должна превышать 30 секунд

mode string required

Режим генерации

Варианты:

std: стандартный режим, базовый режим с более выгодным соотношением цены и качества

pro: профессиональный режим (высокое качество), режим повышенного качества с лучшим результатом видео

watermark_info object

Генерировать ли версию результата с водяным знаком. Пользовательские водяные знаки не поддерживаются.

enabled boolean

true: сгенерировать версию с водяным знаком

false: не генерировать версию с водяным знаком

callback_url string

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

external_task_id string

Пользовательский ID задачи

Пользовательский ID задачи. Он не заменяет системный ID задачи, но может использоваться для поиска задачи.

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

Параметры ответа

{
  "request_id": "task_01hxyz...",
  "response_url": "https://api.odirouter.ai/model/v1/queue/kling-v3-motion-control/requests/task_01hxyz.../response",
  "status_url": "https://api.odirouter.ai/model/v1/queue/kling-v3-motion-control/requests/task_01hxyz.../status",
  "cancel_url": "https://api.odirouter.ai/model/v1/queue/kling-v3-motion-control/requests/task_01hxyz.../cancel",
  "queue_position": 0
}

Поле	Тип	Описание
`request_id`	string	ID задачи, используемый во всех последующих операциях.
`response_url`	string	URL для получения итогового результата.
`status_url`	string	URL для проверки статуса задачи.
`cancel_url`	string	URL для отмены задачи.
`queue_position`	int	Текущая позиция в очереди.

Следующие операции