Kling 3.0 Motion Control API
model: kling/3-0-motion-control
Переносит движение с одного ролика на другой. На вход до 1 изображения, описание до 2 500 символов. Модель Kuaishou.
Цена: за секунду, 720P — 22.68 кр. ($0.1134), 1080P — 30.24 кр. ($0.1512).
кр. — кредиты, покупаются за рубли.
Песочница
Ролик собирается после входа: новому счёту начисляют 50 кредитов, и первый ролик идёт на них. Ставка у этой модели 22.68–30.24 кр. за секунду. Войдите, чтобы начать.
{ "model": "kling/3-0-motion-control", "input": { "input_urls": [ "https://gen202.com/assets/sample-nano-banana-2.jpg" ], "video_urls": [ "https://example.com/input.mp4" ], "prompt": "Заменить фон на вечернюю городскую улицу, свет тёплый" } }
Нажмите «Запустить» — готовый ролик появится здесь
Ролик делается минуты. Задача живёт не дольше 60 минут, после чего шлюз закрывает её сам и возвращает удержание целиком.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "cm8r4t0vk0001s60p2xq7f9ab",
"model": "kling/3-0-motion-control",
"state": "success",
"resultJson": "{\"resultUrls\":[\"https://file.example/result.mp4\"]}",
"failCode": "",
"failMsg": "",
"creditsConsumed": 22.68
}
}
Цена Kling 3.0 Motion Control
Цена за секунду. Списывается фактический расход, о котором сообщил поставщик.
| Вариант | Наша цена | Скидка | Официальная |
|---|---|---|---|
| 720P | 22.68 кр. · $0.113411,34 ₽ | −10% | $0.126 |
| 1080P | 30.24 кр. · $0.151215,12 ₽ | −10% | $0.168 |
В среднем на 10% ниже официальной цены поставщика. кр. — кредиты, покупаются за рубли.
На время работы шлюз удерживает ставку выбранного разрешения, умноженную на запрошенную длительность; больше 3629 кредитов по этой модели он не удержит ни при каком запросе (длительность входа у поставщика не ограничена). Разница между удержанием и фактическим расходом возвращается на баланс тем же запросом состояния, который увидел итог.
Вызов через API
Ролик делается минуты, поэтому файл не приходит в ответ на запрос. Первый вызов
ставит задачу и сразу отвечает её номером, второй по этому номеру отдаёт состояние задачи, а когда
она готова — ссылку на результат. Ключ передаётся в обоих запросах заголовком
Authorization: Bearer sk-… и выпускается
в кабинете. На один ключ шлюз пропускает
30 постановок задачи и 300
запросов состояния в минуту.
Поля запроса
Значения проверяются до обращения к поставщику: поле не из списка модели или значение вне
перечисления возвращают 422 и кредитов не тратят.
| Поле | Тип | Обяз. | Допустимые значения |
|---|---|---|---|
| model | текст | обязательное | kling/3-0-motion-control |
| input | объект | обязательное | Параметры генерации — поля из таблицы ниже |
Поля input
| Поле | Тип | Обяз. | Допустимые значения |
|---|---|---|---|
| input_urls | список ссылок | обязательное | от 1 до 1 ссылок на изображение |
| video_urls | список ссылок | обязательное | от 1 до 1 ссылок на видео |
| prompt | текст | опц. | не длиннее 2 500 символов |
| mode | значение из списка | опц. | 720p · 1080p |
| character_orientation | значение из списка | опц. | video · image |
| background_source | значение из списка | опц. | input_video · input_image |
Ссылка на исходный файл принимается только полным адресом на http или https: не длиннее 2048 символов, на общедоступном сайте, без имени и пароля перед адресом и без порта, кроме 80 и 443. Относительный путь, а также адреса внутри сети — localhost, 127.0.0.1, 10.0.0.5, 192.168.1.2 — и имена без точки шлюз отклоняет ответом 422, к поставщику не обращаясь.
Ответ
Оба запроса отвечают одним конвертом: {"code":…,"msg":…,"data":…}, где
code повторяет HTTP-статус, а полезное лежит в
data. Тот же конверт приходит и при отказе — разбирать две формы ответа
не нужно.
/api/v1/jobs/createTask
| Поле | Тип | Что в нём |
|---|---|---|
| data.taskId | строка | Номер задачи. Больше в ответе ничего нет и быть не может — работа только началась. |
/api/v1/jobs/recordInfo
| Поле | Тип | Что в нём |
|---|---|---|
| data.taskId | строка | Номер задачи — тот же, что вернул createTask. |
| data.model | строка | Имя модели в том виде, в каком его прислал клиент. |
| data.state | строка | Состояние задачи: waiting, queuing, generating, success или fail. |
| data.param | строка | Параметры, с которыми задача создана, — строкой JSON внутри JSON. |
| data.resultJson | строка | Результат строкой JSON внутри JSON: {"resultUrls":["https://…"]} — разбирается вторым разбором. До завершения задачи — пустая строка. |
| data.failCode | строка | Код неудачи из таблицы ниже. У остальных задач — пустая строка. |
| data.failMsg | строка | Причина неудачи словами. Иначе пустая строка. |
| data.costTime | число | Сколько задача заняла, миллисекунды. Пока не завершилась — null. |
| data.completeTime | число | Когда завершилась, миллисекунды эпохи Unix. Пока не завершилась — null. |
| data.createTime | число | Когда создана, миллисекунды эпохи Unix. |
| data.updateTime | число | Когда состояние менялось в последний раз, миллисекунды эпохи Unix. |
| data.creditsConsumed | число | Сколько кредитов списано. Ноль, пока задача не завершилась, и ноль у неудачной. |
Состояния задачи
Состояние лежит в поле state ответа
/api/v1/jobs/recordInfo. Первые три означают, что работа идёт: запрос надо
повторить примерно через 3 секунды — чаще спрашивать нечего, столько же
ждёт между опросами сам шлюз. Два последних состояния окончательные: после них задача не меняется.
| state | Что происходит |
|---|---|
| waiting | Задача принята и стоит в очереди шлюза; поставщику она ещё не отправлена. |
| queuing | Поставщик задачу принял и поставил в свою очередь. |
| generating | Генерация идёт. |
| success | Готово: ссылки на результат лежат в resultJson, в creditsConsumed — сколько списано. |
| fail | Задача не удалась: причина в failCode и failMsg, удержанные кредиты возвращены целиком. |
Опрос не бывает бесконечным: задача на видео живёт не дольше 60
минут, после чего шлюз закрывает её сам состоянием fail и возвращает
удержанные кредиты целиком. Причина неудачи приходит двумя полями:
failCode из таблицы ниже и failMsg словами.
| failCode | Что произошло |
|---|---|
| 501 | Поставщик вернул отказ: генерация не удалась. |
| 408 | Результата нет дольше крайнего срока задачи (60 минут для видео). |
| 404 | Поставщик не знает такой задачи. |
| 429 | Поставщик отбил создание задачи по своему лимиту. |
| 500 | Поломка на нашей стороне; подробности остаются в журнале шлюза. |
Ссылка на готовый файл живёт 14 дней — столько его хранит поставщик. Файл,
который нужен дольше, скачивайте к себе сразу после того, как задача пришла в состояние
success.
Отказы
Тело отказа одно на все случаи: {"code":…,"msg":…,"data":null}. Задача, не
дошедшая до результата, не тарифицируется — удержанные кредиты возвращаются целиком.
| Код | Адрес | Когда |
|---|---|---|
| 400 | /api/v1/jobs/createTask | Тело запроса — не разбираемый JSON. |
| 401 | /api/v1/jobs/createTask | Ключа нет в заголовке Authorization, либо он неверный или отключён. |
| 402 | /api/v1/jobs/createTask | Свободных кредитов меньше, чем удерживается под задачу. |
| 413 | /api/v1/jobs/createTask | Тело запроса больше 512 КиБ. |
| 415 | /api/v1/jobs/createTask | Тело отправлено не как application/json или заголовок Content-Type не передан. |
| 422 | /api/v1/jobs/createTask | Поле model пустое или его имени нет в каталоге, input — не объект, поле не из списка модели либо значение вне её перечисления. В сообщении перечислено, что принимается. |
| 429 | /api/v1/jobs/createTask | Больше 30 запросов в минуту на один ключ либо больше 50 незавершённых задач на аккаунте. |
| 500 | /api/v1/jobs/createTask | Поломка на нашей стороне. Подробности остаются в журнале шлюза и наружу не уходят. |
| 401 | /api/v1/jobs/recordInfo | Ключа нет в заголовке Authorization, либо он неверный или отключён. |
| 404 | /api/v1/jobs/recordInfo | Задачи с таким номером нет или она создана другим аккаунтом. |
| 422 | /api/v1/jobs/recordInfo | Параметр taskId не передан. |
| 429 | /api/v1/jobs/recordInfo | Больше 300 запросов в минуту на один ключ. |
| 500 | /api/v1/jobs/recordInfo | Поломка на нашей стороне. Подробности остаются в журнале шлюза и наружу не уходят. |
Пример вызова
# 1. Поставить задачу — в ответе придёт её номер
TASK=$(curl -s https://api.gen202.com/api/v1/jobs/createTask \
-H "Authorization: Bearer sk-ваш-ключ" \
-H "Content-Type: application/json" \
-d '{
"model": "kling/3-0-motion-control",
"input": {
"input_urls": [
"https://gen202.com/assets/sample-nano-banana-2.jpg"
],
"video_urls": [
"https://example.com/input.mp4"
],
"prompt": "Заменить фон на вечернюю городскую улицу, свет тёплый"
}
}' | jq -r '.data.taskId')
# 2. Спрашивать состояние, пока задача не закончится: waiting, queuing и
# generating означают «работа идёт», success и fail — окончательные
while true; do
RECORD=$(curl -s "https://api.gen202.com/api/v1/jobs/recordInfo?taskId=$TASK" \
-H "Authorization: Bearer sk-ваш-ключ")
STATE=$(echo "$RECORD" | jq -r '.data.state')
case "$STATE" in success|fail) break;; esac
sleep 3
done
# 3. Забрать результат. Ссылка на файл лежит в resultJson — это строка JSON
# внутри JSON, поэтому её разбирают вторым разбором (fromjson)
echo "$RECORD" | jq -r '.data |
if .state == "fail"
then "отказ \(.failCode): \(.failMsg)"
else .resultJson | fromjson | .resultUrls[0]
end'import json
import time
import requests
headers = {"Authorization": "Bearer sk-ваш-ключ"}
# 1. Поставить задачу — в ответе придёт её номер
created = requests.post(
"https://api.gen202.com/api/v1/jobs/createTask",
headers=headers,
json={
"model": "kling/3-0-motion-control",
"input": {
"input_urls": [
"https://gen202.com/assets/sample-nano-banana-2.jpg"
],
"video_urls": [
"https://example.com/input.mp4"
],
"prompt": "Заменить фон на вечернюю городскую улицу, свет тёплый"
}
},
).json()
task_id = created["data"]["taskId"]
# 2. Спрашивать состояние, пока задача не закончится: waiting, queuing и
# generating означают «работа идёт», success и fail — окончательные
while True:
task = requests.get(
"https://api.gen202.com/api/v1/jobs/recordInfo",
headers=headers,
params={"taskId": task_id},
).json()["data"]
if task["state"] in ("success", "fail"):
break
time.sleep(3)
# 3. Разобрать итог. У неудачи причина в failCode и failMsg
if task["state"] == "fail":
raise SystemExit("отказ " + task["failCode"] + ": " + task["failMsg"])
# resultJson — строка JSON внутри JSON, поэтому разбор второй
result = json.loads(task["resultJson"])
print(result["resultUrls"][0])
print("списано кредитов:", task["creditsConsumed"])
Пример проходит весь путь: ставит задачу, повторяет запрос состояния раз в
3 секунды, пока задача не закончится, и разбирает ответ до ссылки
на файл. Разборов два, потому что поле resultJson — строка JSON
внутри JSON. В теле первого запроса стоят обязательные поля модели и значения из её
перечислений, поэтому он проходит проверку шлюза как есть.
Заменить в нём нужно два значения: свой ключ и ссылки на исходные файлы — адреса example.com стоят заполнителями, файлов по ним нет.
Пример на оболочке разбирает ответ через jq; на Python своего
ничего не нужно, кроме requests.
Остальные модели этого семейства и их поля — в разделе документации Видео.
Что делает Kling 3.0 Motion Control
Запись повторяет чужое движение на своём герое: как он двигается и что при этом делает лицо, снимается с присланного ролика, а внешность берётся со снимка.
На входе обязательны оба файла: одна ссылка на картинку в поле input_urls и одна на ролик в поле video_urls.
Описание здесь необязательно и вмещает до 2 500 знаков. Полный набор полей стоит таблицей выше и в разделе «Kling».
Как перенести движение из ролика на снимок
Работа собирается из двух файлов и трёх переключателей, а описание словами лишь уточняет обстановку.
- Возьмите снимок героя. Одна ссылка на картинку кладётся в поле input_urls: с неё берут внешность, одежду и лицо.
- Подберите ролик с нужным движением. Ссылка на него уходит в поле video_urls, и этот ролик задаёт, что герой будет делать.
- Обрежьте ролик до нужного куска. Длительность результата приносит присланное видео, поэтому в него кладут ровно тот отрезок, который нужен.
- Укажите, откуда брать разворот и фон. Поле character_orientation выбирает между значениями video и image, поле background_source — между input_video и input_image.
- Поставьте разрешение. Поле mode оставляет выбор из двух значений: 720p и 1080p.
Сколько длится результат Kling 3.0 Motion Control и в каком он разрешении
Поля длительности у этой записи нет вовсе: сколько секунд получится, приносит присланный ролик.
Поэтому на время работы резервируется предел записи, а не цена заказанных секунд. Сколько именно, сказано под таблицей цен выше.
Разрешение выбирается полем mode: 720p и 1080p. Ни 4K, ни каких-либо ещё значений у этой записи нет.
Что Kuaishou обещает от переноса движения
Неподвижный снимок оживает по образцу: движение, выражение лица и мелкие подробности повторяются за присланным роликом, а сам герой при этом не искажается.
В основе названа техника захвата движения.
Где Kuaishou очерчивает границу переноса движения
Границы этой работы Kuaishou называет сам. Речь и совпадение губ со словами он оставляет обычной генерации Kling 3.0, а переносу движения отводит движение тела и выражение лица.
- Герой ведётся один. Когда лиц в ролике несколько, модель возьмёт то, которое заметнее в кадре.
- Чем ближе герой на снимке к тому, кто двигался в ролике, тем точнее перенос: расхождение вроде движения человека на животном разработчик называет прямо.
- Трудное и быстрое движение выходит короче исходного: модель забирает из ролика только тот отрезок, где движение читается непрерывно.
Что переносится хорошо, а что приходится подгонять
Разработчик описывает, что переносится. Ниже — то, что видно только на съёмке: как подбирают снимок и ролик, чтобы перенос вышел с первой попытки.
- Возьмите снимок прямо из первого кадра своего же ролика: поза, ракурс и крупность тогда совпадают сами, а поменять остаётся внешность и обстановку.
- Крупность снимка и ролика должна сойтись. Поясной портрет с ростовым роликом чаще всего заканчивается отказом, а при меньшем расхождении камера обрезает герою голову.
- В кадре снимка нужен запас места под размах движения. Когда его нет, герой упирается в край и в ролик попадает не целиком.
- Чем крупнее лицо на снимке, тем ближе сходство. На ростовом плане модель дорисовывает черты сама, и герой перестаёт быть похожим.
- Руки берутся из ролика. Если кисти в него не попали, модель придумает их сама, а на быстром движении пальцы смазываются.
- Мелкие движения лица — облизать губы, повести глазами — сбивают перенос заметнее крупных.
- Обстановка приходит со снимка и остаётся почти неподвижной: люди на заднем плане не ходят, вспышки не срабатывают. Движение фона просят описанием, и выходит оно не с первой попытки.
- Одежду и обстановку описанием не подменить: и то и другое берётся со снимка, поэтому нужный вид собирают заранее в самой картинке.
- Разворот по ролику переносит движение точнее, а разворот по снимку удерживает исходную позу ценой расхождения с образцом. Первый ставят, когда снимок повторяет начало ролика.
- Звук переезжает из ролика целиком, вместе с голосом того, кто в нём говорил. Свой голос подставляют отдельно, после переноса.
- Годный образец — один человек, понятная поза, простое действие и спокойная камера. Хаотичное движение камеры и перекрытия героя другими предметами перенос расшатывают.
- Взаимодействие с обстановкой переезжает вместе с движением: руки в воде поднимают брызги, а сам герой отбрасывает тень и оставляет следы.
Из этого складывается обычный порядок: сначала снимают ролик с нужным движением, потом берут из него кадр и переделывают в нём внешность, а уже этот кадр подают на вход.