可灵 3.0 多镜头分镜 API：shots 与主体一致性

先说答案：可灵 3.0 可以在一条视频里生成多个镜头，接口上通过请求里结构化的 shots 对象来控制。在 HopBase 上，kling-v3 和 kling-v3-omni 两个模型支持多镜头分镜，成片时长 3-15 秒，分辨率可选 720p / 1080p / 2K / 4K。分镜有两种模式："mode": "intelligence" 是智能分镜，由模型自己切镜头；"mode": "customize" 是自定义分镜，最多写 6 段，每段有自己的提示词（不超过 512 字符），每段至少 1 秒，各段时长加起来必须正好等于请求里的 duration。如果想让同一个角色出现在每个镜头里，先用 POST /v1/kling/subjects 创建自定义主体（目前免费），再把主体 ID 填进 subjects，在提示词里用 <<<element_1>>> 指代它。分镜和主体都不影响每秒单价，影响价格的只有分辨率、是否有声和是否带参考视频。

哪些可灵模型支持分镜和主体

模型	时长	分镜（多镜头）	主体	参考图
kling-v3-omni	3-15 秒	支持	支持	参考图 + 主体合计 ≤ 7（带参考视频时 ≤ 4）
kling-v3	3-15 秒	支持	支持，但至少要带 1 张参考图	最多 6 张
kling-v3-turbo	3-15 秒	不支持	支持	不支持

可灵的旧版本（o1、2.6、2.5 Turbo、2.1、1.6）两项都不支持，给它们传 shots 会报 model ... does not support shots (multi-shot storyboard)。正式调用前，先用 GET /v1/models 确认你的 Key 能用哪些模型 ID。

shots 对象的规则

所有请求都发到 POST https://api.hop-base.com/v1/video/generate。做多镜头只需要多加一个 shots 字段，规则如下：

• mode 取 intelligence 或 customize。
• 智能分镜模式下不要传 segments，在哪里切镜头由模型决定。
• 自定义分镜模式下必须传 segments：最多 6 段，index 从 1 开始连续编号，不能跳号。
• 每段的 prompt 不能为空，最长 512 字符。
• 每段的 duration 至少 1 秒，并且各段之和必须正好等于顶层的 duration。写分段时一定要显式设置 duration。
• 请使用结构化的 shots。直接透传可灵原生的 extra.multi_shot、extra.shot_type、extra.multi_prompt 会被拒绝。

智能分镜：交给模型来切

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "prompt": "咖啡师磨豆、拉花，然后把咖啡推到吧台对面，顾客露出笑容",
    "duration": 10,
    "resolution": "1080p",
    "audio": true,
    "shots": { "mode": "intelligence" }
  }'

自定义分镜：自己写分镜脚本

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "一双越野跑鞋的 10 秒产品短片",
    "duration": 10,
    "resolution": "1080p",
    "audio": true,
    "shots": {
      "mode": "customize",
      "segments": [
        { "index": 1, "prompt": "远景：清晨薄雾中的山道起点，跑者正在系鞋带", "duration": 3 },
        { "index": 2, "prompt": "低机位跟拍：跑鞋踩过湿漉漉的岩石，水花慢动作溅起", "duration": 3 },
        { "index": 3, "prompt": "特写：跑者停在山脊上，阳光照在鞋身 logo 上", "duration": 4 }
      ]
    }
  }'

3 + 3 + 4 = 10，和 duration 一致。如果加起来对不上，请求会在创建任务之前被拒绝，报错为 sum of shot durations (9 s) must equal the total duration (10 s)，不会扣费。

用自定义主体让角色在各镜头里保持一致

镜头一切换，最难的是让角色在每个镜头里看起来还是同一个人。可灵的办法是主体（subject）：用参考素材建一次，之后按 ID 反复调用。

第一步：创建主体（免费，异步）

curl https://api.hop-base.com/v1/kling/subjects \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "露娜吉祥物",
    "description": "穿蓝色卫衣的橙色狐狸吉祥物",
    "reference_type": "image_refer",
    "frontal_image_url": "https://cdn.example.com/luna-front.png",
    "reference_image_urls": [
      "https://cdn.example.com/luna-side.png",
      "https://cdn.example.com/luna-back.png"
    ]
  }'

• image_refer 需要 1 张正面图，再加 1-3 张参考图。参考图不能和正面图重复，彼此之间也不能重复。
• video_refer 改用一段 video_url 来建主体，可以选择绑定一个 voice_id。两种方式的字段不能混用。
• name 最长 20 字符，description 最长 100 字符。所有 URL 都必须是公网 http(s) 地址。

接口返回 202 和一个 id（object 为 kling.subject.task），和视频任务一样用 GET /v1/video/tasks/{task_id} 轮询。完成后，结果里的 element_ids 就是主体 ID。GET /v1/kling/subjects 可以列出你建过的所有主体。创建主体目前免费。

第二步：在多镜头请求里使用主体

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "中景：<<<element_1>>> 坐在沙发上，抱着一个红色礼盒；接着特写：<<<element_1>>> 掀开盒盖，眼睛一下亮了起来",
    "duration": 8,
    "resolution": "1080p",
    "subjects": [{ "id": "subject-92951593344", "name": "luna" }],
    "shots": { "mode": "intelligence" }
  }'

主体的引用规则：

• 按顺序对应：subjects[0] 是 <<<element_1>>>，subjects[1] 是 <<<element_2>>>，依此类推。
• 传进来的每个主体都必须在顶层 prompt 里引用到，否则会报 subjects[0] is not referenced in prompt as <<<element_1>>>。
• 反过来也一样：引用了没有传的主体（比如只传了两个，却写了 <<<element_3>>>），同样会被拒绝。
• kling-v3 使用主体时，还必须至少带 1 个 "usage": "reference" 的 images[]。缺了这一项，请求在提交时就会被拒绝，不会发到可灵。
• 示例用的是智能分镜：这时顶层 prompt 就是所有镜头的脚本，主体引用正好写在模型读取的位置。主体也可以和自定义分镜一起用。我们用 kling-v3-omni 实测：顶层 prompt 写一次 <<<element_1>>>，各段提示词里只写“那个男人”，两个镜头里都是同一个主体，长相、眼镜、白大褂和红领带都对得上。引用必须写在顶层 prompt 里，只写在 segments 里会在提交时报 subjects[0] is not referenced in prompt as <<<element_1>>>。另外，在一次对比中，每段都再写一遍 <<<element_1>>> 时，第一个镜头里同时出现了两个这个角色（一个在走路，一个已经坐在长椅上）；各段用代称时没有出现这种情况。建议在顶层引用一次、各段用代称描述，并先用 720p 短片试一条再放量。

轮询与结果

上面这些都是异步任务。提交后返回 202，带任务 ID（形如 kt57x…）和 billing_bucket。之后轮询 GET /v1/video/tasks/{task_id}，直到 status 变成 completed 或 failed：

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

任务完成后，outputs 是 api.hop-base.com 上的签名链接，从完成起 24 小时有效；usage 里有 billed_seconds 和 cost_usd（实际扣费金额）。任务失败时会返回稳定的 error.code，比如 input_sensitive、invalid_request、generation_failed、timeout，失败一律不计费。任务超过 2 小时未完成会自动判为失败。完整字段说明见 可灵视频接入文档。

多镜头怎么计费

可灵按成片秒数计费，单价由模型、分辨率以及「无声 / 有声 / 带参考视频」决定。分镜、主体和参考图都不额外加价。以下是模型卡上的部分官方牌价：

模型 · 档位	720p	1080p	2K
kling-v3 · 无声	$0.0882/秒	$0.1176/秒	$0.1471/秒
kling-v3 · 有声	$0.1324/秒	$0.1765/秒	$0.2206/秒
kling-v3-omni · 无声、无参考视频	$0.0882/秒	$0.1176/秒	$0.1471/秒
kling-v3-omni · 有声、无参考视频	$0.1176/秒	$0.1471/秒	$0.1765/秒

按这个表，上面那条 10 秒的自定义分镜示例（kling-v3-omni、1080p、有声）按牌价是 10 × $0.1471，约 $1.47。4K 档和带参考视频的档位见模型卡 kling-v3、kling-v3-omni。价格页上是同样档位的人民币牌价，例如 kling-v3 1080p 有声为 ¥1.20/秒。你的实际单价取决于所在分组。

写好分镜的几个建议

• 每段按分镜表的写法来写。先写景别（远景、特写、低机位跟拍），再写动作，一段只写一个动作。
• 短镜头至少给 2 秒。下限虽然是 1 秒，但太短的镜头里人物动不了多少。
• 先用智能分镜加 720p 打样。故事顺了，再换成自定义分镜和高分辨率。成本等于秒数乘以分辨率档位的单价。
• 需要声音时再开 audio。以 kling-v3 1080p 为例，开声音后单价从 $0.1176/秒升到 $0.1765/秒。

常见问题

可灵 3.0 一条视频最多几个镜头？

自定义分镜最多 6 段，总时长在 3-15 秒之间。智能分镜由模型自己决定切几个镜头。

kling-v3-turbo 支持多镜头吗？

不支持。kling-v3-turbo 支持主体，但不支持 shots。做分镜请用 kling-v3 或 kling-v3-omni。

分镜和主体要额外收费吗？

不收。每秒单价只由模型、分辨率、是否有声和是否带参考视频决定。创建自定义主体目前免费。

主体和自定义分镜能一起用吗？

可以。把主体放进 subjects，在顶层 prompt 里用 <<<element_1>>> 引用一次，各段 segments 里用“他”“那个男人”这类代称描述动作，角色会在每个镜头里保持一致。kling-v3 使用主体时还要带 1 张 "usage": "reference" 的参考图。

为什么报「sum of shot durations must equal the total duration」？

各段时长之和必须正好等于顶层 duration。写分段时请显式设置 duration，不要依赖默认值。

可以直接传可灵原生的 multi_shot 或 element_list 吗？

不可以。HopBase 只接受结构化的 shots 和 subjects。透传 extra.multi_shot、extra.multi_prompt、extra.shot_type、extra.element_list 会被拒绝，报错信息会告诉你改用哪个结构化字段。

怎么开始？

在 HopBase 控制台创建 Key，选一个包含可灵模型的分组，用 GET /v1/models 确认列表里有 kling-v3 或 kling-v3-omni，然后先跑上面的智能分镜示例。如果你要的是另一种控制方式，让人物照着视频动作动起来，可以看《可灵动作控制 API 接入指南》。