小由和小迪
加入会员

功能简介 ​

用于提交图生视频生成任务。上传参考图片并填写画面描述后，系统会把任务发送到可灵；提交成功后会返回一个 task_id，后续可通过查询接口查看进度和获取视频地址。

使用场景 ​

  • 已经有一张图片，想把它做成短视频
  • 想控制视频从什么画面开始、到什么画面结束
  • 想做更复杂的多镜头图生视频
  • 想在高级场景里加主体、声音或运镜控制

参数说明 ​

输入参数 ​

参数名类型必填用户视角说明
access_keyString是接口账号。
secret_keyString是接口密码。
promptString否用一句话描述你希望视频怎么动，比如“镜头缓慢拉远，两个人向镜头挥手”。如果还想写“不希望出现什么”，也写在这个字段里，用 正向提示词：... 负向提示词：... 分开即可，工具会自动拆给官方接口。最多 2,500 个字符；单镜头或智能分镜时必须填。
model_nameString否选用的模型，可填 kling-v1、kling-v1-5、kling-v1-6、kling-v2-master、kling-v2-1、kling-v2-1-master、kling-v2-5-turbo、kling-v2-6、kling-v3。
modeString否生成质量模式，默认值 std，可填 std 或 pro。std 是标准/基础模式，性价比高，适合先测试效果；pro 是专家/高品质模式，视频质量通常更好，但一般成本或耗时也会更高。
durationString否视频时长，单位秒，默认值 5，可填 3 到 15。短视频或先测试建议用 5；脚本较复杂、多镜头内容较多时再加长。
imageString否主参考图，也可以理解为首帧图。支持图片链接或 Base64；图片格式支持 .jpg、.jpeg、.png，大小不超过 10MB，宽高都不小于 300px，宽高比在 1:2.5 到 2.5:1 之间。
image_tailString否尾帧图。只有想控制“最后一帧长什么样”时才填。支持图片链接或 Base64，格式和大小要求同 image；image 和 image_tail 至少填一个。
soundString否要不要同时生成声音，默认值 off。on 表示生成声音，off 表示不生成声音。只有视频确实需要人声、环境声或音效时再开；如果用了音色占位符 <<<voice_1>>>，这里必须填 on。
multi_shot_jsonString否多镜头高级配置。普通场景不要填；需要多镜头时填一个 JSON 对象，里面用 enabled 开关多镜头，用 shot_type 选择 intelligence 智能分镜或 customize 自定义分镜，自定义分镜再写 multi_prompt。
element_list_jsonString否主体库配置。只有你已经在可灵主体库里建好主体 ID 时才需要。可直接填一个主体 ID，比如 123456789；多个主体 ID 用英文逗号分隔，比如 123456789,987654321。
voice_list_jsonString否音色配置。只有视频里要指定说话音色时才需要。可直接填一个音色 ID，比如 voice_id_1；多个音色 ID 用英文逗号分隔，比如 voice_id_1,voice_id_2。
cfg_scaleNumber否控制视频和提示词的贴合程度，官方默认值 0.5，取值范围 0~1。值越大，模型自由发挥越少，画面越努力贴近 prompt；值越小，模型自由发挥越多，画面可能更有变化但也更容易偏离提示词。普通场景建议不填或用 0.5；如果生成结果经常不按提示词来，可以适当调高。kling-v2.x 模型不支持。
camera_control_jsonString否运镜配置，比如推进、拉远、平移。里面的 type 可填 simple、down_back、forward_up、right_turn_forward、left_turn_forward。simple 表示简单运镜；down_back 表示下移拉远；forward_up 表示推进上移；right_turn_forward 表示右旋推进；left_turn_forward 表示左旋推进。不会配时可以先不填。
watermark_info_jsonString否要不要顺便生成带水印版本。推荐直接填 true 或 false；true 表示生成带水印版本，false 表示不生成。也兼容 {"enabled": false} 这种官方对象格式。

输出参数 ​

参数名类型用户视角说明
task_idString任务编号。后面查结果就靠它。
task_statusString当前状态。可返回 submitted、processing、succeed、failed；分别表示已提交、生成中、生成成功、生成失败。创建成功时一般是 submitted。
raw_jsonString官方原始返回内容。创建时间、更新时间等不常看的信息都在这里，一般只有排查问题时才会用。
最简单的填写方式

基础必填项 ​

先跑通基础版本时，通常填这几个就够了：

  • access_key
  • secret_key
  • prompt
  • model_name
  • mode
  • duration
  • image
  • sound
参数组合规则

图片与尾帧 ​

  • image 和 image_tail 至少填一个；最常见的是只填 image。
  • 只要启用了多镜头，就不要再填 image_tail。
  • 如果填写了 image_tail，就不要同时填写 camera_control_json。

多镜头 ​

  • 不做多镜头时，不填 multi_shot_json；这时必须填写 prompt。
  • 做智能多镜头时，multi_shot_json 里填 {"enabled": true, "shot_type": "intelligence"}，并且必须填写 prompt。
  • 做自定义多镜头时，multi_shot_json 里填 {"enabled": true, "shot_type": "customize", "multi_prompt": [...]}，并且所有分镜时长加起来要等于外层 duration。

主体与音色 ​

  • 如果 prompt 里用了 <<<voice_1>>> 这类音色占位符，就要填写 voice_list_json，并且把 sound 填成 on。
  • voice_list_json 和 element_list_json 不要同时填。
提示词怎么写

只有正向描述 ​

直接描述你希望画面怎么动：

text
镜头缓慢拉远，女孩微笑，阳光自然，画面真实。

同时包含正向和负向 ​

如果既有正向描述，也有不希望出现的内容，建议这样写：

text
正向提示词：镜头缓慢拉远，女孩微笑，阳光自然，画面真实。
负向提示词：不要字幕、水印、畸形手指、画面模糊。

工具会怎么处理 ​

工具会把“正向提示词”后面的内容传给官方 prompt，把“负向提示词”后面的内容传给官方 negative_prompt。如果没有写这些标签，整段都会当作正向提示词。

复杂参数怎么填

multi_shot_json：多镜头配置 ​

普通生成不要填。只想让模型自动分镜时，可以这样写：

json
{
  "enabled": true,
  "shot_type": "intelligence"
}

如果要自己写每个镜头，就用 customize。每个镜头都要有 index、prompt、duration。duration 表示这个镜头几秒，所有镜头时长加起来要等于外层 duration。

json
{
  "enabled": true,
  "shot_type": "customize",
  "multi_prompt": [
    {
      "index": 1,
      "prompt": "女孩看向镜头，微笑",
      "duration": "2"
    },
    {
      "index": 2,
      "prompt": "镜头缓慢拉远",
      "duration": "3"
    }
  ]
}

element_list_json：主体库 ID ​

只有已经在可灵主体库里创建过主体时才填。推荐直接填主体 ID；多个主体 ID 用英文逗号分隔，最多支持 3 个参考主体。

text
123456789,987654321

如果需要按官方对象数组填写，也可以写成 [{"element_id":123456789}]。

voice_list_json：音色 ID ​

推荐直接填音色 ID；多个音色 ID 用英文逗号分隔，最多 2 个。如果 prompt 里写了 <<<voice_1>>>，这里第 1 个音色 ID 就是它对应的音色，同时 sound 要填 on。

text
voice_id_1,voice_id_2

如果需要按官方对象数组填写，也可以写成 [{"voice_id":"voice_id_1"}]。

camera_control_json：运镜控制 ​

用来控制运镜。type 可填 simple、down_back、forward_up、right_turn_forward、left_turn_forward。如果 type=simple，还要填 config，并且 horizontal、vertical、pan、tilt、roll、zoom 这 6 个字段只能有一个不是 0，取值范围都是 -10 到 10。

json
{
  "type": "simple",
  "config": {
    "zoom": 3
  }
}

watermark_info_json：带水印版本 ​

用来控制是否生成带水印结果。推荐直接填 true 或 false；true 表示生成，false 表示不生成。

json
false

如果需要按官方对象格式填写，也可以写成 {"enabled": false}。

注意事项 ​

  • 这个接口不会直接返回视频地址。
  • 想拿视频地址，要再调用查询接口。
  • image 和 image_tail 至少要填一个。
  • 不熟悉高级参数时，先不要一上来就同时使用分镜、主体、音色和运镜。
浏览1