Skip to content
上新Nano Banana 2.1 已上线：Google 新一代生图模型，单张低至 $0.0336，原生 4K，约上一代半价查看模型
HopBase
← 返回博客

可灵动作控制 API 接入：请求格式、计费与失败原因

HopBase 2026年10月29日 17 分钟阅读

先说答案：可灵「动作控制」（Motion Control）的输入是一张人物图加一段动作视频，输出是图里的人照着视频里的动作动起来的成片。在 HopBase 上可以用两个模型：kling-v3-motion-control，支持 720p / 1080p / 2K / 4K；kling-v2-6-motion-control，支持 720p / 1080p。调用方式和其他可灵模型一样，都是异步任务：先 POST https://api.hop-base.com/v1/video/generate 提交，再轮询 GET /v1/video/tasks/{task_id}。请求里人物图和动作视频各放一个；不要传 duration，成片时长由动作视频决定。唯一的扩展参数是 extra.character_orientation，取值 image 或 video。计费按成片秒数，任务失败不扣费，结果链接 24 小时有效。最容易出问题的是动作视频本身：画面里必须是真人，而且从头到腰的上半身要完整、清楚。

动作控制是什么？和数字人、对口型怎么选

可灵有三条让人物动起来的链路，各自适合不同的需求：

模型输入动的是什么成片时长
kling-v3-motion-control / kling-v2-6-motion-control1 张人物图 + 1 段动作视频全身照着视频里的动作做等于动作视频时长
kling-avatar1-5 张人物图 + 1 段音频脸和口型随音频变化等于音频时长
kling-lip-sync已有视频 + 新音频只改口型，对上新台词等于源视频时长

如果你手上已经有一段动作素材，比如舞蹈、产品展示时的手势、走秀或主播的肢体动作，想换成另一个角色来做（品牌吉祥物、换了服装的模特、AI 生成的人设），就用动作控制。如果角色只需要开口说话，用数字人或对口型更合适，具体可以看《可灵数字人 API 接入实战》。

v3 和 v2.6 怎么选：分辨率与官方牌价

两个模型都按成片秒数计费，单价随分辨率变化。下表是各模型卡上公布的官方牌价；你的实际单价取决于所在分组，以登录后模型目录中显示的为准：

模型720p1080p2K4K
kling-v3-motion-control$0.1324/秒$0.1765/秒$0.2647/秒$0.3971/秒
kling-v2-6-motion-control$0.0735/秒$0.1176/秒——

举个例子：用 kling-v3-motion-control 生成 10 秒 1080p 成片，按牌价是 10 × $0.1765，约 $1.77。价格页上同一档位的人民币牌价是 ¥1.20/秒。打样或大批量出 720p 用 v2.6，需要 2K / 4K 时再上 v3。各档位价格见模型卡 kling-v3-motion-control 和 kling-v2-6-motion-control。

第一步：提交任务

请求发到可灵视频的统一入口。动作控制场景里每个素材的角色是固定的，所以人物图不用写 usage，动作视频也不用写 reference_type：

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-motion-control",
    "prompt": "照着视频里的舞蹈动作跳",
    "resolution": "1080p",
    "images": [{ "url": "https://cdn.example.com/character.png" }],
    "videos": [{ "url": "https://cdn.example.com/dance.mp4", "keep_original_sound": true }],
    "extra": { "character_orientation": "video" }
  }'

各字段说明：

  • images：只放一项，就是要做动作的那个人物。
  • videos：只放一项，作为动作来源。keep_original_sound: true 会保留原视频的音轨。动作控制本身不生成声音。
  • extra.character_orientation：可选，取值 image 或 video。两个取值的区别主要在镜头和时长上限。我们用同一张人物图和同一段带 180° 转身的动作视频实测，两种模式下角色都会跟着视频转身、背对镜头；image 保持人物图的构图和机位，背景基本不动，动作视频最长 10 秒；video 让镜头跟着动作视频重新取景、推拉，动作视频最长 30 秒。不传时 HopBase 默认按 video 处理。这是动作控制唯一接受的 extra 键，传其他键会返回 400。
  • resolution：v3 支持 720p / 1080p / 2k / 4k，v2.6 支持 720p / 1080p，同时决定计费档位。
  • duration：不要传。时长由输入视频决定，传了会报 duration of model ... is determined by the input media; do not pass duration。

每个素材项只能在 url 和 file_id 中选一个。url 必须是公网可以直接访问的绝对 http(s) 地址；相对路径、file://、内网或回环地址、带账号密码的链接，在提交时就会被拒绝。提交成功返回 202，任务 ID 形如 kt57x…。

第二步：轮询到任务结束

curl https://api.hop-base.com/v1/video/tasks/kt57xYOUR_TASK_ID \
  -H "Authorization: Bearer sk-你的密钥"

状态依次是 queued → processing，最后是 completed 或 failed。只有后两个是终态，其他值都当作还在运行。任务完成时的返回如下：

{
  "id": "kt57xYOUR_TASK_ID",
  "status": "completed",
  "outputs": ["https://api.hop-base.com/..."],
  "usage": { "bucket": "...", "billed_seconds": 10, "cost": 12.0, "cost_usd": 1.765, "currency": "CNY" }
}

outputs 是 api.hop-base.com 上的签名链接，从任务完成起 24 小时有效，重复查询不会续期，请尽快转存到自己的存储。usage.cost_usd 是这个任务实际扣的金额。Python 最小轮询示例：

import time, requests

API = "https://api.hop-base.com/v1"
H = {"Authorization": "Bearer sk-你的密钥"}

task = requests.post(f"{API}/video/generate", headers=H, json={
    "model": "kling-v3-motion-control",
    "prompt": "照着视频里的舞蹈动作跳",
    "resolution": "1080p",
    "images": [{"url": "https://cdn.example.com/character.png"}],
    "videos": [{"url": "https://cdn.example.com/dance.mp4"}],
    "extra": {"character_orientation": "video"},
}).json()

while True:
    t = requests.get(f"{API}/video/tasks/{task['id']}", headers=H).json()
    if t["status"] == "completed":
        print(t["outputs"][0]); break
    if t["status"] == "failed":
        raise RuntimeError(f"{t['error'].get('code')}: {t['error']['message']}")
    time.sleep(5)

可灵的请求里没有回调（webhook）字段，只能靠轮询跟踪进度。任务创建 2 小时后还没完成，会被标记为失败（error.code 为 timeout），不计费。任务提交后不能取消。

动作视频：最容易踩坑的一步

提交时，HopBase 只检查请求结构：素材数量、字段名、URL 格式和分辨率。素材本身的格式、大小、分辨率、时长和内容，是可灵在任务运行过程中检查的。所以不合规的视频会先被受理，几分钟后再失败。动作控制最常见的失败是这条：

error.code: reference_input_invalid
the motion reference video was rejected: no complete human upper body was detected in it;
use a video in which a real person's upper body (head to waist) is clearly visible, then submit again

准备动作视频时注意几点：

  • 必须是真人出镜。动物、怪物等非真人角色会被拒绝。
  • 整段视频里，从头到腰都要在画面内，而且不能被遮挡。特写裁切、桌子或道具挡住躯干、严重的运动模糊，都容易失败。
  • 素材放在服务器能稳定下载的地方。自己的对象存储或 CDN 比免费图床可靠，不少免费图床会屏蔽机房 IP。
  • 动作视频有多长，成片就有多长，费用也随之变化。提交前先剪掉不需要的部分。
  • 注意时长上限：character_orientation 为 image 时动作视频不能超过 10 秒，为 video（默认）时不能超过 30 秒。超限的任务会在提交后约半分钟失败，error.code 为 invalid_request，不计费。实测 12 秒的视频在 image 模式下被拒，在 video 模式下正常出了 12 秒成片；31 秒的视频在 video 模式下也被拒。
  • 成片画幅跟随人物图的比例，不跟随动作视频。实测 9:16 竖屏动作视频配一张约 5:6 的人物图，成片是 864×1040。想要竖屏成片，就准备竖构图的人物图。image 模式的成片可能比素材略短，实测 5 秒素材出 4.8 秒，按 4 秒计费。

任务失败不计费，素材不合格只会浪费一点时间。

提交阶段的报错

提交阶段报错不会创建任务，也不扣费。下面是动作控制特有的报错和原文：

你发了什么error.message
图片 0 张或 2 张，或者没给视频motion control requires exactly 1 motion video and 1 character image
人物图带了 usagemotion control images[0] does not accept usage; the character image role is fixed by the scene
视频带了 reference_typemotion control videos[0] does not accept reference_type; the motion video role is fixed by the scene
朝向不是 image / videoextra.character_orientation must be image or video
传了 durationduration of model kling-v3-motion-control is determined by the input media; do not pass duration
照着 OpenAI 的习惯传了 size 等字段request body does not match the JSON contract: json: unknown field "size"

如果返回 402，且 code 为 insufficient_balance，说明可用余额扣掉正在运行任务的预估费用后，不够支付这一单。任务结束后，预占的额度会自动释放。完整报错表见 可灵视频接入文档。

放进生产流水线

常见做法是：每个动作只拍一段干净的素材，比如开箱展示、打招呼或一个舞蹈节拍，然后用这段素材批量配不同的人物图，换模特、换服装、换品牌形象。每次的成本就是素材秒数乘以单价，容易算清楚。同一个 Key 只要包含相应分组，还可以调用可灵文生视频、用 MiniMax 语音合成做配音，以及用对话模型写提示词。Key 能用哪些模型，以 GET /v1/models 的返回为准。

常见问题

动作控制可以指定时长吗？

不可以。必须省略 duration，传了会返回 400。成片时长等于动作视频时长，想控制时长和成本，就先把素材剪短。

动作视频最长可以多长？

取决于 extra.character_orientation：image 最长 10 秒，video（默认）最长 30 秒。超出上限的任务会在运行约半分钟后以 invalid_request 失败，不计费。需要更长的成片，就把动作拆成几段分别生成再拼接。

character_orientation 选 image 还是 video？

两种模式下角色都会照着视频转身。想保留人物图的机位和构图，比如固定机位的产品展示，用 image，动作视频控制在 10 秒内；想连镜头运动一起复刻，或者素材超过 10 秒，用 video。

动作控制会生成声音吗？

不会生成新的声音。想保留动作视频的原声，把 videos[0].keep_original_sound 设为 true。不要把它写进 extra，extra.keep_original_sound 会被拒绝。

任务提交成功了，为什么几分钟后又失败了？

可灵是在任务运行中才检查素材的。最常见的原因是动作视频里没有清楚完整的真人上半身（reference_input_invalid），其次是链接无法下载，或者内容审核没通过（input_sensitive）。失败的任务不计费。

kling-v3-motion-control 和 kling-v2-6-motion-control 有什么区别？

v3 支持 720p、1080p、2K 和 4K；v2.6 只支持 720p 和 1080p，但单价更低：720p 为 $0.0735/秒，1080p 为 $0.1176/秒，v3 对应是 $0.1324/秒和 $0.1765/秒。两者的请求格式完全一样。

成片能下载多久？

从任务完成起 24 小时内。重复查询返回的是同一个链接，不会续期；链接过期后访问会返回 410。

怎么开通？

在 HopBase 控制台创建 Key，并选一个包含可灵模型的分组，然后调用 GET /v1/models，确认列表里有 kling-v3-motion-control。牌价见价格页。

教程可灵