Kling V3.0 Motion Control 可以让你通过从参考视频中提取运动并逐帧应用到静态角色图像上，使其动起来。输出结果会保留你图像中角色的外观，同时再现视频中的动作——这种技术称为动作迁移。本指南涵盖了 Novita AI 的接口、必要的输入、关键参数以及可运行的 Python 和 curl 示例，你只需提供一个真实的 API 密钥即可。
何时使用 Motion Control
当你同时拥有两样东西时，Motion Control 是最合适的工具：一张你想要动画化的静态角色图像，以及一段你想要复现其动作的参考视频。它与 Image-to-Video (I2V) 不同，后者通过提示词生成动作。使用 Motion Control 时，动作会精确地从参考视频中复制——输出角色将遵循与参考视频中人物相同的运动轨迹。
在以下场景使用：
- 你想将特定的舞蹈、行走循环或手势应用到角色插画或照片上
- 你需要在不同角色之间获得一致、可重复的动作（同一段参考视频，不同的图像）
- 你在制作对动作质量有要求的内容，而开放式 I2V 提示词的结果过于不可预测
当动作本身尚未确定时，不要使用它——此时，使用带有描述性提示词的 I2V 能以更低的成本提供更大的灵活性。
第一步：获取你的 Novita API 密钥
在 novita.ai 注册，并从控制台生成一个 API 密钥。新账户会获得免费积分，你可以用这些积分在投入生产环境之前测试 Motion Control。
第二步：确认接口和模型 ID
Novita AI 上的 Kling V3.0 Motion Control 使用标准的异步视频模式：
提交任务：
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
第三步：准备输入数据
Motion Control 需要两个输入：一张参考图像和一段参考视频。正确准备这两项是输出质量最重要的因素。
参考图像
这是输出结果会保留其外观的角色。要求：
- 格式：JPEG、PNG、JPG
- 最大大小：10 MB
- 最小分辨率：每边 340 像素
- 宽高比：介于 2:5 和 5:2 之间
- 角色应清晰可见，占据图像面积超过 5%，且没有严重遮挡（不要裁剪头部或身体）
为了获得最佳效果，请使用角色身体比例与参考视频中显示的内容大致匹配的图像。如果参考视频显示的是全身舞者，请使用全身角色图像，而不是肖像裁剪。
参考视频
这是运动源。输出中的角色将复现此视频中的动作：
- 格式：MP4、MOV
- 最大大小：10 MB
- 时长：3–30 秒
- 最小分辨率：每边 340 像素
- 宽高比：介于 2:5 和 5:2 之间
- 参考视频中的人物应全身或上半身可见且无遮挡，包括头部
清晰、光线良好、背景杂乱较少的素材比噪点多或拥挤的镜头能更准确地传递动作。
第四步：发送你的第一个请求
最简 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"
}
第五步：轮询结果
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'
完成后，响应中包含一个包含输出 URL 的 videos 数组：
{
"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 |
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 秒片段。
标准版与专业版：选择哪个质量等级
Kling V3.0 Motion Control 提供两个质量等级：
标准版 输出为 720p。它适合迭代、测试动作兼容性或生成草稿，然后再投入最终版本。
专业版 输出为 1080p，具有更好的动作保真度和主体一致性。在以下情况使用专业版：
- 输出将用于最终成品（社交帖子、短片、产品演示）
- 角色面部或服装的细节很重要
- 你正在生成长片段（10 秒以上），此时随时间推移的质量下降更容易被察觉
对于大多数开发工作流程，先从标准版开始以确认输入兼容性和动作质量，然后在最终版本切换到专业版。
定价、时长与成本估算
Novita AI 按生成的视频每秒计费 Motion Control。标准版和专业版有各自的每秒费率。有关当前定价，请查看 Novita AI 模型页面。
时长限制：
character_orientation: "video"— 最长 30 秒character_orientation: "image"— 固定 5 秒
对于 "video" 模式，成本随时长增加。"image" 模式始终生成 5 秒片段。
常见错误排障
任务立即失败，返回 422 或验证错误
检查 image 和 video 是否都是公开可访问的 URL（没有身份验证或已过期的短时预签名 URL）。Novita 后端必须在任务执行时能够获取这两个文件。
输出动作看起来不对或角色变形
最常见的原因是图像中的角色方向与参考视频不匹配。尝试将 character_orientation 在 "video" 和 "image" 之间切换，看看哪个能产生更好的对齐效果。
角色面部身份在片段中途丢失 确保参考图像中的角色有清晰、无遮挡的脸部和身体。对于较长片段，专业版比标准版更能保持主体一致性。
参考视频动作无法干净地转移 噪点多或拥挤的参考素材会降低动作提取质量。使用表演者是主要主体且背景相对干净的素材。如果目标是平滑的动作转移，请避免手持抖动的镜头。
状态卡在 processing 超过 3 分钟
偶尔会有队列延迟。等待最多 5 分钟再视为卡住。如果仍然卡住，提交一个新任务——不要重用旧的 task_id。
开发者用 Kling Motion Control 构建的内容
游戏资产的角色动画：获取角色插画并应用参考动作片段（行走、奔跑、攻击），无需绑定或动画软件。
具有一致动作的社交内容：将同一段舞蹈参考视频应用于多个角色图像，生成一系列具有相同编舞但不同外观的片段。
预可视化：在投入全制作动画之前，测试特定动作序列在角色设计上的效果。
电子商务产品展示：使用精心挑选的展示衣物动作的参考视频，对产品图像应用微妙的姿势变化或衣物运动。
常见问题
Novita AI 上的 Motion Control 和 Image-to-Video 有什么区别？
Image-to-Video (I2V) 基于文本提示让图像动起来——动作由模型根据你的描述生成。Motion Control 则是将参考视频中的特定动作转移到你的图像中的角色上。Motion Control 提供精确、可复现的动作；I2V 则不需要参考片段即可提供创作灵活性。
参考视频中的角色需要与图像角色的外观匹配吗？
不需要。参考视频仅用于动作提取——输出角色来自图像，而不是来自视频。这是核心能力：动作来自一个来源，外观来自另一个来源。为了获得最佳转移质量，身体比例应大致匹配（全身图像对应全身视频，肖像对应上半身视频）。
我可以使用任何公开视频作为参考吗？
你可以使用任何满足格式和大小要求的视频。动作转移效果最好的素材是主体清晰可见且遮挡较少的视频。复杂的多人场景或经过大量编辑的素材（剪辑、缩放）会降低准确性。
生成需要多长时间？
通常为 30–120 秒，具体取决于输出时长以及你选择的是标准版还是专业版。每 8–10 秒轮询一次，而不是在紧密循环中轮询。
