@Element1 walks the runway and turns, following the motion of the reference video, elegant fashion show pace.
Kling 3.0 pro Motion Control API
kwaivgi/kling-v3.0-pro/motion-controlKling 3.0 pro Motion Control将一张角色图片与一段参考视频转化为身份锁定的 1080p 动作迁移视频,支持角色身份锁定、动作轨迹精确迁移与时空连贯性。它能够保留角色的面部细节、服饰特征与身体比例,同时迁移参考视频中的动作幅度、运动节奏与场景交互。
拖拽文件、粘贴剪贴板素材,或输入 URL。
1/1 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。
1/1 个素材
示例
REST API
快速开始
完成鉴权后提交合法 input,再用 task_id 取回视频。
连接 Vidgo API
创建 API Key,仅保存在服务端,并以 Authorization: Bearer VIDGO_API_KEY 发送。
- 接口
- POST
https://api.vidgo.ai/api/generate/submit - 鉴权
- Authorization: Bearer VIDGO_API_KEY
提交一次生成任务
使用最小合法载荷提交。model 必须为 kwaivgi/kling-v3.0-pro/motion-control。成功提交会立即返回 task_id。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "kwaivgi/kling-v3.0-pro/motion-control",
"input": {
"prompt": "@Element1 walks the runway and turns, following the motion of the reference video, elegant fashion show pace.",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/input-image.png"
],
"video_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/input-video.mp4"
],
"character_orientation": "video",
"resolution": "1080p",
"kling_elements": [
{
"frontal_image_url": "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/element-frontal.png",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/element-angle-1.png"
]
}
]
}
}
JSON
)
RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
printf 'API error: %s
' "$RESPONSE" >&2
exit 1
fi
printf '%s
' "$RESPONSE"等待结果
用 task_id 查询;not_started/running 继续轮询,finished/failed 停止。成功时读取 data.files[].file_url。
查询状态
GET https://api.vidgo.ai/api/generate/status/{task_id}约每 2 秒查询一次,长时间运行时逐步延长间隔。仅在 not_started 或 running 时继续查询,finished 或 failed 时停止。也可在请求顶层提供 callback_url 接收任务完成通知。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "running",
"created_time": "2026-03-11T04:23:18Z"
}
}{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/video.mp4",
"file_type": "video"
}
],
"created_time": "2026-08-22T10:00:00Z",
"progress": 100,
"error_message": null
}
}完整可运行示例
展开查看含 HTTP 与业务码校验、task_id 验证、轮询、终态处理与超时边界的完整脚本。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "kwaivgi/kling-v3.0-pro/motion-control",
"input": {
"prompt": "@Element1 walks the runway and turns, following the motion of the reference video, elegant fashion show pace.",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/input-image.png"
],
"video_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/input-video.mp4"
],
"character_orientation": "video",
"resolution": "1080p",
"kling_elements": [
{
"frontal_image_url": "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/element-frontal.png",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/element-angle-1.png"
]
}
]
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
printf 'Timed out after 600 seconds
' >&2
exit 1
fi
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
exit 1
fi
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep "$POLL_DELAY"
if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
done输入参数
以下为 input 内接受的字段。请求示例包含必填的顶层 model 字段。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| prompt | string | 否 | — | 可省略;null、空字符串和空白按未提供处理。非空文本去除首尾空白后最多 2,500 个字符。 |
| image_urls | array | 是 | — | 恰好 1 个可公网访问的图片 URL,支持 JPG、JPEG、PNG,最大 10MB。 |
| video_urls | array | 是 | — | 恰好 1 个可公网访问的视频 URL,支持 MP4、MOV,最大 100MB。 |
| character_orientation | string | 是 | — | 角色朝向模式:image 以图片为朝向参考,video 以视频为朝向参考。 |
| resolution | string | 否 | 1080p | 可选,默认 1080p,显式传入时也须为 1080p。 |
| kling_elements | array | 否 | — | 可选的面部一致性参考,仅在 character_orientation 为 video 时可用,最多 1 个元素。可在提示词中用 @Element1 指代;提供元素时须包含 frontal_image_url 与 reference_image_urls。 |
响应字段
提交后立即返回任务标识;状态查询响应会附带进度、全部输出文件或失败信息。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 应用层结果码,成功响应为 0 或 200。 |
| message | string | 可读信息或错误详情(如有)。 |
| data.task_id | string | 用于状态查询路径中的任务 ID。 |
| data.status | string | not_started、running、finished 或 failed。 |
| data.created_time | string | 任务创建时间,date-time 格式。 |
| data.progress | integer | 服务商上报的 0–100 进度。 |
| data.files[] | array | 成功任务的全部输出文件,按响应顺序排列。 |
| data.files[].file_url | string | 生成视频的公开 URL。 |
| data.files[].file_type | string | 文件类型,例如 video。 |
| data.error_message | string | null | status 为 failed 时的失败详情。 |
任务生命周期
not_started 与 running 为非终态;finished 与 failed 为终态,轮询到任一即应停止。
not_started任务已受理,排队等待开始。
running生成进行中,请继续使用同一 task_id 轮询。
finished生成成功。从 data.files[].file_url 读取全部视频 URL。
failed生成因错误终止。读取 data.error_message 并停止轮询。
轮询与错误处理
- 鉴权401 表示 Bearer API Key 缺失或无效,请修正后再重试。
- 参数校验400 表示存在非法字段、不支持的媒体键或积分余额不足,请修正请求后再提交。
- 网络与超时传输失败不同于任务失败。判定任务失败前,请在有限超时时间内重试状态查询。
- 轮询间隔建议从约 2 秒一次开始,长任务逐步加大间隔。
- 终态仅在 not_started 或 running 时继续轮询;遇到 finished 或 failed 立即停止。
- 回调选项在请求顶层提供 callback_url 可接收最终的扁平任务对象;若回调投递失败,仍可使用轮询。
端点规格
| 规格项 | 取值 | 说明 |
|---|---|---|
| 输入方式 | 1 张图片 + 1 段视频 | image_urls 与 video_urls 各需恰好 1 个 URL,prompt 可省略。 |
| 输出 | 视频任务 | 提交后返回异步任务 ID。 |
| 分辨率 | 1080p | 当前模型 ID 固定输出 1080p。 |
| 参考视频时长 | 3–10s / 3–30s | image 朝向支持 3–10 秒,video 朝向支持 3–30 秒。使用参考视频时长,无需传入 duration。 |
| 计费依据 | 15 credits/sec | 积分 = ceil(实际探测秒数 × 15);先乘每秒积分,再对总积分向上取整。 |
相关模型
Kling 3.0 pro Motion Control常见问题
Kling 3.0 pro Motion Control API 是什么?
Kling 3.0 pro Motion Control是快手(Kwai VGI)用于参考驱动视频动作迁移的模型。它根据一张角色图片与一段参考视频生成身份锁定的 1080p 动作迁移视频,支持动作轨迹精确迁移与时空连贯性。面向视觉动作迁移,它保留面部细节、服饰特征与身体比例,同时迁移参考视频中的动作幅度、运动节奏与场景交互。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Kling 3.0 pro Motion Control如何选择 character_orientation?
选择 image 时,输出角色朝向与构图更贴近参考图,适合固定主体姿态与镜头跟随,参考视频时长为 3–10 秒。选择 video 时,角色朝向跟随参考视频镜头与动作路径,更适合复杂全身动作,并可选用 kling_elements 增强多角度面部细节,参考视频时长为 3–30 秒。
Kling 3.0 pro Motion Control的参考视频时长如何限制?
参考视频最短 3 秒。character_orientation 为 image 时最长 10 秒,为 video 时最长 30 秒。生成时长跟随探测到的参考视频时长,提交前请把素材控制在对应窗口内。
什么时候该用 Kling 3.0 pro Motion Control的 1080p?
需要更清晰的 1080p 交付、客户审片与商业成片时,选择 Kling 3.0 pro Motion Control,并沿用同一套「一张角色图 + 一段参考视频」契约。若要先做低成本 720p 迭代,可先用 Kling 3.0 std Motion Control,再把定稿镜头转到本端点。
Kling 3.0 pro Motion Control如何按秒计费?
积分 = ceil(实际探测秒数 × 15);先乘每秒积分,再对总积分向上取整。例如 5.2 秒为 78 积分。
如何让 Kling 3.0 pro Motion Control保持人物一致性?
请使用主体清晰、无遮挡的单角色图片,并保证参考视频中全身或上半身含头部动作全程可见。每次请求只传一张图与一段视频,需要更明确的场景调度时,可在可选提示词中补充环境与走位说明。
kling_elements 如何增强 Kling 3.0 pro Motion Control的面部一致性?
当 character_orientation 为 video 时,可通过 kling_elements 添加一个面部一致性元素,并在提示词中以 @Element1 引用。该元素需同时提供 frontal_image_url 与 reference_image_urls,以便在跟随参考动作时锚定多角度面部细节。
Kling 3.0 pro Motion Control可以用于商业项目吗?
商业使用需符合适用的模型许可与 Vidgo 服务条款。生成的视频可用于客户交付、营销素材、培训内容以及需要身份锁定 1080p 动作迁移的专业制作流程。















