可灵（Kling）AI 视频生成 API 文档（旧版归档）

本文件为 docs/API/VideoAPI/Kling/ 目录下多份旧版 md 的整合归档，路径统一以 /v1/videos/kling/...（旧）为准。新版参见 docs/API/VideoAPI/Kling/overview.md。

1. 总览

官方文档入口（仅参考）：

https://klingai.com/document-api/

统一请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

核心说明

当前统一采用 /v1/videos/kling/... 接口路径承载可灵视频能力。

视频能力接口

1) 文生视频（Text2Video）

功能	方法	路径
创建	POST	`/v1/videos/kling/text2video`
单任务查询	GET	`/v1/videos/kling/text2video/{task_id}`
列表查询	GET	`/v1/videos/kling/text2video?pageNum=1&pageSize=30`

2) 图生视频（Image2Video）

功能	方法	路径
创建	POST	`/v1/videos/kling/image2video`
单任务查询	GET	`/v1/videos/kling/image2video/{task_id}`
列表查询	GET	`/v1/videos/kling/image2video?pageNum=1&pageSize=30`

3) 动作控制（Motion Control）

功能	方法	路径
创建	POST	`/v1/videos/kling/motion-control`
单任务查询	GET	`/v1/videos/kling/motion-control/{task_id}`
列表查询	GET	`/v1/videos/kling/motion-control?pageNum=1&pageSize=30`

说明：

动作控制创建接口允许不传模型，默认使用 Kling-V2.6。

4) Omni / 多镜头（Omni Video）

功能	方法	路径
创建	POST	`/v1/videos/kling/omni-video`
单任务查询	GET	`/v1/videos/kling/omni-video/{task_id}`
列表查询	GET	`/v1/videos/kling/omni-video?pageNum=1&pageSize=30`

5) 多图参考生视频（Multi-Image2Video）

功能	方法	路径
创建	POST	`/v1/videos/kling/multi-image2video`
单任务查询	GET	`/v1/videos/kling/multi-image2video/{task_id}`
列表查询	GET	`/v1/videos/kling/multi-image2video?pageNum=1&pageSize=30`

6) 多模态视频编辑（Multi-Elements）

功能	方法	路径
初始化选区	POST	`/v1/videos/kling/multi-elements/init-selection`
增加选区	POST	`/v1/videos/kling/multi-elements/add-selection`
删除选区	POST	`/v1/videos/kling/multi-elements/delete-selection`
清除选区	POST	`/v1/videos/kling/multi-elements/clear-selection`
预览选区	POST	`/v1/videos/kling/multi-elements/preview-selection`
创建任务	POST	`/v1/videos/kling/multi-elements`
单任务查询	GET	`/v1/videos/kling/multi-elements/{task_id}`
列表查询	GET	`/v1/videos/kling/multi-elements?pageNum=1&pageSize=30`

主体能力接口

能力	方法	路径
创建自定义主体	POST	`/v1/elements/custom`
查询自定义主体列表	GET	`/v1/elements/custom`
查询自定义主体单个	GET	`/v1/elements/{id}`
查询官方主体列表	GET	`/v1/elements/presets`
删除自定义主体	POST	`/v1/elements/delete`

查询参数

列表查询通用参数：

参数名	类型	必填	默认值	说明
pageNum	int	否	1	页码，范围 `[1, 1000]`
pageSize	int	否	30	每页条数，范围 `[1, 500]`
provider	string	否	-	可选服务商

参数兼容

model 兼容：支持 model，会在对应接口归一化到 model_name 或内部标准模型。
seconds 兼容：支持 seconds，会归一化为 duration。
多图字段兼容：image_list 中兼容 image / image_url / url / base64 等形式（以各子接口实现为准）。
历史字段兼容：动作控制中会清理 action_control 等内部/历史字段，不作为上游主参数。

关键约束

Kling-Video-O1、Kling-V3-Omni 请优先使用 /v1/videos/kling/omni-video。
若将 Omni 模型发到 text2video 或 image2video 路径，当前实现会按规则拒绝或返回上游校验错误（常见 422）。

返回结构（总览）

创建任务返回（示例）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "submitted",
    "task_info": {
      "external_task_id": "string"
    },
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

单任务查询返回（示例）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_status_msg": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_result": {
      "videos": [
        {
          "id": "string",
          "url": "string",
          "watermark_url": "string",
          "duration": "string"
        }
      ]
    },
    "watermark_info": {
      "enabled": true
    },
    "final_unit_deduction": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

列表查询返回（示例）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": [
    {
      "task_id": "string",
      "task_status": "succeed",
      "task_status_msg": "string",
      "task_info": {
        "external_task_id": "string"
      },
      "task_result": {
        "videos": [
          {
            "id": "string",
            "url": "string",
            "watermark_url": "string",
            "duration": "string"
          }
        ]
      },
      "watermark_info": {
        "enabled": true
      },
      "final_unit_deduction": "string",
      "created_at": 1722769557708,
      "updated_at": 1722769557708
    }
  ],
  "aiping_id": "string"
}

2. 文生视频（Text2Video）

文生视频用于根据文本提示词生成视频。本文档以当前实现为准。

官方文档入口（仅参考）：https://klingai.com/document-api/

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

参数名	类型	必填	默认值	说明
`model_name`	string	否	`Kling-V3`	推荐使用的模型字段，目前支持`Kling-V3`，`Kling-V2.6`，`Kling-V1.6`
`model`	string	否	无	兼容字段，会映射到 `model_name`
`prompt`	string	否	无	文本提示词
`negative_prompt`	string	否	空	负向提示词
`multi_shot`	boolean	否	`false`	多镜头开关
`shot_type`	string	条件必填	无	`multi_shot=true` 时按上游规则生效
`multi_prompt`	array	条件必填	无	多镜头分镜信息
`sound`	string	否	`off`	是否生成声音
`cfg_scale`	float	否	`0.5`	提示词参考强度，取值范围 `[0,1]`
`mode`	string	否	`std`	视频模式
`aspect_ratio`	string	否	`16:9`	画面比例
`seconds`	string	否	无	兼容时长字段
`duration`	string	否	无	时长字段
`camera_control`	object	否	空	运镜控制
`watermark_info`	object	否	空	是否同时生成含水印的结果
`callback_url`	string	否	空	回调地址
`external_task_id`	string	否	空	自定义任务 ID

multi_shot

multi_shot 为多镜头视频开关，默认值为 false。

multi_shot=true 时生成多镜头视频，此时 prompt 参数无效，且不支持设定首尾帧生视频。
multi_shot=false 时，shot_type 和 multi_prompt 参数无效。

shot_type

shot_type 用于指定分镜方式，类型为 string。

枚举值：

值	说明
`customize`	自定义分镜
`intelligence`	智能分镜

当 multi_shot=true 时，当前参数必填。

prompt

prompt 为正向文本提示词，类型为 string，不能超过 2500 个字符。

当 multi_shot=false 或 multi_shot=true 且 shot_type=intelligence 时，当前参数不得为空。

Omni 模型可通过 Prompt 与主体、图片、视频等内容实现多种能力，可通过 <<<>>> 的格式指定主体、图片或视频，例如：

text

<<<element_1>>>、<<<image_1>>>、<<<video_1>>>

也可以用 <<<voice_1>>> 指定音色，序号与 voice_list 一致。至多引用 2 个音色；指定音色时 sound 必须为 on；建议语法结构尽量简单，例如：

text

男人<<<voice_1>>>说：“你好”

当 voice_list 不为空且 prompt 引用音色 ID 时，按「有指定音色」计费。不同模型版本、视频模式支持范围不同，以能力地图为准。

multi_prompt

multi_prompt 为各分镜提示词数组，可包含正向描述和负向描述。

通过 index、prompt、duration 定义分镜序号、分镜提示词和分镜时长：

json

{
  "multi_prompt": [
    { "index": 1, "prompt": "string", "duration": "5" },
    { "index": 2, "prompt": "string", "duration": "5" }
  ]
}

规则：

最多支持 6 个分镜，最少支持 1 个分镜。
每个分镜相关内容的最大长度不超过 512。
每个分镜的时长不大于当前任务总时长，且不小于 1 秒。
所有分镜的时长之和必须等于当前任务总时长。
当 multi_shot=true 且 shot_type=customize 时，当前参数必填。

negative_prompt

negative_prompt 为负向文本提示词，类型为 string，不能超过 2500 个字符。

官方建议也可通过正向提示词中的负向句子补充负向提示信息。

sound

sound 用于控制生成视频时是否同时生成声音，类型为 string，默认值为 off。

枚举值：

值	说明
`on`	生成声音
`off`	不生成声音

不同模型版本、视频模式支持范围不同，以能力地图为准。

cfg_scale

cfg_scale 用于控制生成视频的自由度，类型为 float，默认值为 0.5。

取值范围为 [0,1]。值越大，模型自由度越小；值越小，模型自由度越大。kling-v2.x 模型不支持此参数。

mode

mode 为视频生成模式，类型为 string，默认值为 std。

枚举值：

值	说明
`std`	标准模式，基础模式，性价比高，输出视频分辨率为 720P
`pro`	专家模式，高品质模式，生成质量更佳，输出视频分辨率为 1080P
`4k`	4K 模式，高表现模式，生成质量更佳，输出视频分辨率为 4K

不同模型版本、视频模式支持范围不同，以能力地图为准。

camera_control

camera_control 用于控制相机运动。如果不指定，模型会根据输入的文本智能匹配运镜。不同模型版本、视频模式支持范围不同，以能力地图为准。

camera_control.type 为预定义相机运动类型，枚举值：

值	说明
`simple`	简单运镜，此类型下需在 `config` 中六选一设置运镜
`down_back`	镜头下压并后退，即下移拉远，此类型下无需填写 `config`
`forward_up`	镜头前进并上仰，即推进上移，此类型下无需填写 `config`
`right_turn_forward`	先右旋转后前进，即右旋推进，此类型下无需填写 `config`
`left_turn_forward`	先左旋并前进，即左旋推进，此类型下无需填写 `config`

当 type=simple 时，camera_control.config 必填。config 包含以下 6 个字段，需六选一，即只能有一个参数不为 0，其余参数为 0：

字段	类型	取值范围	说明
`horizontal`	float	`[-10,10]`	水平方向移动，负值向左平移，正值向右平移
`vertical`	float	`[-10,10]`	垂直方向移动，负值向下平移，正值向上平移
`pan`	float	`[-10,10]`	水平摇摄，负值绕 y 轴向左旋转，正值绕 y 轴向右旋转
`tilt`	float	`[-10,10]`	垂直俯仰，负值绕 x 轴向下旋转，正值绕 x 轴向上旋转
`roll`	float	`[-10,10]`	翻滚，负值绕 z 轴逆时针旋转，正值绕 z 轴顺时针旋转
`zoom`	float	`[-10,10]`	缩放，负值表示焦距变长、视野变小，正值表示焦距变短、视野变大

aspect_ratio

aspect_ratio 为生成视频帧的宽高比，类型为 string，默认值为 16:9。

枚举值：16:9、9:16、1:1。

duration

duration 为视频长度，单位秒，类型为 string，默认值为 5。

枚举值：3、4、5、6、7、8、9、10、11、12、13、14、15。

不同模型版本、视频模式支持范围不同，以能力地图为准。

watermark_info

watermark_info 用于控制是否同时生成含水印的结果，类型为 object。

格式如下：

json

{
  "watermark_info": {
    "enabled": true
  }
}

enabled=true 表示生成含水印结果，enabled=false 表示不生成含水印结果。暂不支持自定义水印。

callback_url

callback_url 为本次任务结果回调通知地址。如果配置，服务端会在任务状态发生变更时主动通知。

external_task_id

external_task_id 为自定义任务 ID。传入后不会覆盖系统生成的任务 ID，但支持通过该 ID 查询任务。请注意，单用户下需保证唯一性。

创建任务

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/text2video`	POST	application/json	application/json

查询任务

查询单个

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/text2video/{task_id}`	GET	application/json	application/json

查询列表

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/text2video?pageNum=1&pageSize=30`	GET	application/json	application/json

参数兼容

兼容字段	行为
`model`	自动映射为官方字段 `model_name`
`seconds`	统一视频创建流程可兼容，最终按标准化逻辑处理

接口约束

当模型为 Kling-Video-O1 或 Kling-V3-Omni 时，请使用 /v1/videos/kling/omni-video；走文生路径可能返回 422。

请求示例

json

{
  "model_name": "Kling-V2.6",
  "prompt": "一只可爱的小兔子，戴着眼镜，坐在桌边，看报纸",
  "duration": "5",
  "mode": "pro",
  "sound": "on",
  "aspect_ratio": "1:1",
  "callback_url": "",
  "external_task_id": ""
}

返回结构示例

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_status": "submitted",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（单个）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_status_msg": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_result": {
      "videos": [
        {
          "id": "string",
          "url": "string",
          "watermark_url": "string",
          "duration": "string"
        }
      ]
    },
    "watermark_info": {
      "enabled": true
    },
    "final_unit_deduction": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（列表）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": [
    {
      "task_id": "string",
      "task_status": "succeed",
      "task_status_msg": "string",
      "task_info": {
        "external_task_id": "string"
      },
      "task_result": {
        "videos": [
          {
            "id": "string",
            "url": "string",
            "watermark_url": "string",
            "duration": "string"
          }
        ]
      },
      "watermark_info": {
        "enabled": true
      },
      "final_unit_deduction": "string",
      "created_at": 1722769557708,
      "updated_at": 1722769557708
    }
  ],
  "aiping_id": "string"
}

注意事项

参数与取值以官方文档为准，优先使用 model_name。
model 仅是兼容写法，不建议作为主文档字段。
不同模型在 mode、duration、sound、camera_control 上支持范围不同，以官方能力地图为准。

3. 图生视频（Image2Video）

图生视频用于根据参考图像（首帧/尾帧）与提示词生成视频。

官方文档入口（仅参考）：https://klingai.com/document-api/apiReference/model/imageToVideo

创建图生视频任务

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/image2video`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

参数名	类型	必填	默认值	说明
`model_name`	string	可选	`Kling-V3`	推荐模型字段，目前支持`Kling-V3`，`Kling-V2.6`，`Kling-V1.6`
`model`	string	可选	无	兼容字段，会映射到 `model_name`
`image`	string	条件必填	无	参考图，支持 URL/Base64；与 `image_tail` 至少二选一
`image_tail`	string	条件必填	无	尾帧参考图；与 `image` 至少二选一
`multi_shot`	boolean	可选	`false`	是否多镜头；`true` 时 `prompt` 失效
`shot_type`	string	条件必填	无	`multi_shot=true` 时必填：`customize`/`intelligence`
`prompt`	string	条件必填	无	正向提示词；长度不超过 2500
`multi_prompt`	array	条件必填	无	`multi_shot=true` 且 `shot_type=customize` 时必填
`negative_prompt`	string	可选	空	负向提示词，长度不超过 2500
`element_list`	array	可选	空	参考主体列表，最多 3 个主体
`voice_list`	array	可选	空	音色列表，最多 2 个，和 `element_list` 互斥
`sound`	string	可选	`off`	是否生成声音：`on`/`off`
`cfg_scale`	float	可选	`0.5`	自由度，范围 `[0,1]`（`kling-v2.x` 不支持）
`mode`	string	可选	`std`	生成模式：`std` / `pro` / `4k`
`static_mask`	string	可选	空	静态笔刷 mask 图片
`dynamic_masks`	array	可选	空	动态笔刷配置列表（每项含 `mask` + `trajectories`）
`camera_control`	object	可选	空	摄像机运动控制参数
`aspect_ratio`	string	可选	`16:9`	画面比例：`16:9` / `9:16` / `1:1`
`seconds`	string	可选	无	兼容时长字段
`duration`	string	可选	无	时长字段
`watermark_info`	object	可选	空	水印开关
`callback_url`	string	可选	空	回调地址
`external_task_id`	string	可选	空	自定义任务 ID

image

参考图像，支持传入图片 URL 或 Base64 编码。

可选参数，但 image 与 image_tail 至少二选一，不能同时为空。
使用 Base64 时不要添加 data:image/png;base64, 等前缀，直接传 Base64 字符串。
图片格式支持 .jpg / .jpeg / .png。
图片文件大小不能超过 10MB。
图片宽高尺寸不小于 300px。
图片宽高比介于 1:2.5 ~ 2.5:1。
不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

image_tail

参考图像 - 尾帧控制，支持传入图片 URL 或 Base64 编码。

可选参数，但 image 与 image_tail 至少二选一，不能同时为空。
使用 Base64 时不要添加 data:image/png;base64, 等前缀，直接传 Base64 字符串。
图片格式支持 .jpg / .jpeg / .png。
图片文件大小不能超过 10MB。
图片宽高尺寸不小于 300px。
image_tail、dynamic_masks/static_mask、camera_control 三类能力不能同时使用，建议按官方约束组包。
不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

multi_shot

是否生成多镜头视频。

取值	说明
`false`	单镜头视频。此时 `shot_type` 和 `multi_prompt` 无效。
`true`	多镜头视频。此时 `prompt` 参数无效，需要通过 `shot_type` 指定分镜方式。

默认值为 false。

shot_type

分镜方式。当 multi_shot=true 时，当前参数必填。

取值	说明
`customize`	自定义分镜。需要传入 `multi_prompt`。
`intelligence`	智能分镜。需要传入 `prompt`。

当 multi_shot=false 时，当前参数无效。

prompt

正向文本提示词。

可选参数。
不能超过 2500 个字符。
当 multi_shot=false 时，当前参数不得为空。
当 multi_shot=true 且 shot_type=intelligence 时，当前参数不得为空。
当 multi_shot=true 且 shot_type=customize 时，当前参数无效，分镜提示词应填写在 multi_prompt 中。
指定音色时，可用 <<<voice_1>>> 引用 voice_list 中的音色；指定音色时 sound 必须为 on。

multi_prompt

各分镜信息，通过 index、prompt、duration 定义分镜序号、提示词和时长。

参数名	类型	必填	说明
`index`	int	是	分镜序号
`prompt`	string	是	分镜提示词
`duration`	string	是	分镜时长

参数规则：

当 multi_shot=true 且 shot_type=customize 时，当前参数必填。
最多支持 6 个分镜，最少支持 1 个分镜。
每个分镜相关内容最大长度不超过 512 个字符。
每个分镜时长不大于当前任务总时长，且不小于 1 秒。
所有分镜时长之和需要等于当前任务总时长。

格式如下：

json

{
  "multi_prompt": [
    { "index": 1, "prompt": "镜头一描述", "duration": "2" },
    { "index": 2, "prompt": "镜头二描述", "duration": "3" }
  ]
}

negative_prompt

负向文本提示词。

可选参数。
不能超过 2500 个字符。
建议也可通过正向提示词中的负向句子补充负向提示信息。

element_list

参考主体列表，基于主体库中的主体 ID 配置。

参数名	类型	必填	说明
`element_id`	long	是	主体库中的主体 ID

json

{
  "element_list": [
    { "element_id": 123456789 }
  ]
}

参数规则：

最多支持 3 个参考主体。
主体分为视频角色主体和多图主体，适用范围不同。
不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

voice_list

生成视频时引用的音色列表。

参数名	类型	必填	说明
`voice_id`	string	是	音色 ID，可来自音色定制接口或系统预置音色

json

{
  "voice_list": [
    { "voice_id": "voice_id_1" }
  ]
}

参数规则：

一次视频生成任务至多引用 2 个音色。
当 voice_list 不为空且 prompt 中引用音色 ID 时，任务按“有指定音色”计量计费。
element_list 与 voice_list 互斥，不能共存。
指定音色时，sound 必须为 on。

sound

生成视频时是否同时生成声音。

取值	说明
`on`	生成声音
`off`	不生成声音

默认值为 off。不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

cfg_scale

生成视频的自由度。值越大，模型自由度越小，与用户输入提示词的相关性越强。

可选参数。
默认值为 0.5。
取值范围为 [0, 1]。
kling-v2.x 模型不支持当前参数。

mode

生成视频的模式。

取值	说明
`std`	标准模式，基础模式，性价比高，通常输出 720P。
`pro`	专家模式，高品质模式，通常输出 1080P。
`4k`	4K 模式，高表现模式，通常输出 4K。

默认值为 std。不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

static_mask

静态笔刷涂抹区域，即用户通过运动笔刷涂抹的 mask 图片。

可选参数。
支持图片 URL 或 Base64，格式要求同 image 字段。
图片格式支持 .jpg / .jpeg / .png。
图片长宽比必须与输入图片相同，否则任务可能失败。
static_mask 和 dynamic_masks[].mask 的分辨率必须一致，否则任务可能失败。

dynamic_masks

动态笔刷配置列表。可配置多组，最多 6 组，每组包含涂抹区域 mask 与运动轨迹 trajectories。

参数名	类型	必填	说明
`mask`	string	是	动态笔刷涂抹区域，支持图片 URL 或 Base64，格式要求同 `image` 字段
`trajectories`	array	是	运动轨迹坐标序列

trajectories 子参数：

参数名	类型	必填	说明
`x`	int	是	轨迹点横坐标，以输入图片左下角为原点
`y`	int	是	轨迹点纵坐标，以输入图片左下角为原点

参数规则：

生成 5 秒视频时，轨迹长度不超过 77，坐标个数取值范围 [2, 77]。
坐标点越多，轨迹刻画越准确。
轨迹方向以传入顺序为指向。

camera_control

控制摄像机运动的协议。如未指定，模型会根据输入文本和图片进行智能匹配。

子参数	类型	必填	说明
`type`	string	是	预定义运镜类型
`config`	object	条件必填	当 `type=simple` 时必填；指定其他类型时不填

type 枚举：

取值	说明
`simple`	简单运镜，此类型下可在 `config` 中六选一进行运镜
`down_back`	镜头下压并后退；此类型下 `config` 无需填写
`forward_up`	镜头前进并上仰；此类型下 `config` 无需填写
`right_turn_forward`	先右旋转后前进；此类型下 `config` 无需填写
`left_turn_forward`	先左旋并前进；此类型下 `config` 无需填写

config 可选字段：

字段	类型	说明
`horizontal`	float	水平运镜，取值范围 `[-10, 10]`，负值向左，正值向右
`vertical`	float	垂直运镜，取值范围 `[-10, 10]`，负值向下，正值向上
`pan`	float	水平摇镜，取值范围 `[-10, 10]`，负值向左旋转，正值向右旋转
`tilt`	float	垂直摇镜，取值范围 `[-10, 10]`，负值向下旋转，正值向上旋转
`roll`	float	旋转运镜，取值范围 `[-10, 10]`，负值逆时针，正值顺时针
`zoom`	float	变焦，取值范围 `[-10, 10]`，负值焦距变长，正值焦距变短

当 type=simple 时，config 中以下 6 个字段只能有 1 个字段不为 0，其余字段应为 0。

watermark_info

是否同时生成含水印的结果。

json

{
  "watermark_info": {
    "enabled": false
  }
}

子参数	类型	必填	说明
`enabled`	boolean	是	`true` 表示生成含水印结果，`false` 表示不生成含水印结果

暂不支持自定义水印。

callback_url

本次任务结果回调通知地址。如果配置，服务端会在任务状态发生变更时主动通知。

external_task_id

自定义任务 ID。传入后不会覆盖系统生成的任务 ID，但支持通过该 ID 查询任务。单用户下需保证唯一。

关键约束

image 与 image_tail 至少二选一，不能同时为空。
image_tail、dynamic_masks/static_mask、camera_control 存在组合约束，建议按官方规则组包。
element_list 与 voice_list 互斥，不能共存。
multi_shot 开启时，shot_type 与 multi_prompt 必须满足条件关系。

查询任务

查询类型	请求方法	请求地址
单任务查询	GET	`/v1/videos/kling/image2video/{task_id}`
列表查询	GET	`/v1/videos/kling/image2video?pageNum=1&pageSize=30`

参数兼容

兼容字段	行为
`model`	自动映射到官方字段 `model_name`
`seconds`	统一视频创建流程可兼容，最终按标准化逻辑处理

接口约束

当模型为 Kling-Video-O1 或 Kling-V3-Omni 时，请使用 /v1/videos/kling/omni-video；走图生路径可能返回 422。

请求示例

json

{
  "model_name": "Kling-V2.6",
  "image": "https://example.com/multi-2.png",
  "image_tail": "https://example.com/multi-1.png",
  "prompt": "镜头拉远，女生微笑",
  "negative_prompt": "",
  "duration": "5",
  "mode": "pro",
  "sound": "off",
  "callback_url": "",
  "external_task_id": ""
}

返回结构示例

创建任务返回示例

json

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_status": "submitted",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（单个）

json

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_status_msg": "string",
    "watermark_info": {
      "enabled": true
    },
    "task_result": {
      "videos": [
        {
          "id": "string",
          "url": "string",
          "watermark_url": "string",
          "duration": "string"
        }
      ]
    },
    "task_info": {
      "external_task_id": "string"
    },
    "final_unit_deduction": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（列表）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": [
    {
      "task_id": "string",
      "task_status": "submitted|processing|succeed|failed",
      "task_status_msg": "string",
      "task_info": {
        "external_task_id": "string"
      },
      "task_result": {
        "videos": [
          {
            "id": "string",
            "url": "string",
            "watermark_url": "string",
            "duration": "string"
          }
        ]
      },
      "watermark_info": {
        "enabled": true
      },
      "final_unit_deduction": "string",
      "created_at": 1722769557708,
      "updated_at": 1722769557708
    }
  ],
  "aiping_id": "string"
}

注意事项

参数与取值以官方文档为准。
图生视频涉及较多互斥/组合规则（如 element_list 与 voice_list、multi_shot 条件必填等），请按官方约束组包。

4. 多图参考生视频（Multi-Image2Video）

官方文档入口（仅参考）：

https://klingai.com/document-api/apiReference/model/multiImageToVideo

创建任务

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/multi-image2video`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

参数名	类型	必填	默认值	说明
`model_name`	string	否	`Kling-V1.6`	推荐模型字段，目前支持`Kling-V1.6`
`model`	string	否	无	兼容字段，会映射到 `model_name`
`image_list`	array	是	无	参考图片列表（会自动归一化）
`reference_images`	array	否	无	`image_list` 兼容别名
`prompt`	string	否	空	正向提示词
`negative_prompt`	string	否	空	负向提示词
`mode`	string	否	`std`	模式（常见 `std` / `pro`）
`seconds`	string	否	无	兼容时长字段
`duration`	string	否	无	时长字段
`aspect_ratio`	string	否	`16:9`	画面比例
`watermark_info`	object	否	空	水印开关
`callback_url`	string	否	空	回调地址
`external_task_id`	string	否	空	自定义任务 ID

image_list

参考图片列表，必填。最多支持 4 张图片。

用 key:value 承载，格式如下：

json

{
  "image_list": [
    { "image": "https://example.com/image-1.png" },
    { "image": "https://example.com/image-2.png" }
  ]
}

子参数

参数名	类型	必填	说明
`image`	string	是	图片 URL 或 Base64 字符串

图片要求

API 端无裁剪逻辑，请直接上传已选主体后的图片。
支持传入图片 URL 或 Base64 编码。
使用 Base64 时不要添加 data:image/png;base64, 等前缀，直接传 Base64 字符串。
图片格式支持 .jpg / .jpeg / .png。
图片文件大小不能超过 10MB。
图片宽高尺寸不小于 300px。
图片宽高比介于 1:2.5 ~ 2.5:1。

image_list 元素兼容

支持以下输入并会归一化：

字符串：URL/Base64
对象：image / image_url / url / base64

归一化后透传格式：

json

"image_list": [
  { "image": "..." }
]

prompt

正向文本提示词，必填。

不能超过 2500 个字符。
建议明确描述各参考图片中的主体、动作和场景关系。

negative_prompt

负向文本提示词。

可选参数。
不能超过 2500 个字符。

mode

生成视频的模式。

取值	说明
`std`	标准模式，基础模式，性价比高
`pro`	专家模式，高品质模式，生成视频质量更佳

默认值为 std。不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

duration

生成视频时长，单位为秒。

取值
`5`
`10`

默认值为 5。不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

aspect_ratio

生成视频画面纵横比。

取值
`16:9`
`9:16`
`1:1`

默认值为 16:9。

watermark_info

是否同时生成含水印的结果。

json

{
  "watermark_info": {
    "enabled": false
  }
}

子参数	类型	必填	说明
`enabled`	boolean	是	`true` 表示生成含水印结果，`false` 表示不生成含水印结果

暂不支持自定义水印。

callback_url

本次任务结果回调通知地址。如果配置，服务端会在任务状态发生变更时主动通知。

external_task_id

自定义任务 ID。传入后不会覆盖系统生成的任务 ID，但支持通过该 ID 查询任务。单用户下需保证唯一。

查询任务

查询单个

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/multi-image2video/{task_id}`	GET	application/json	application/json

查询列表

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/multi-image2video?pageNum=1&pageSize=30`	GET	application/json	application/json

查询参数

参数名	类型	必填	默认值	说明
task_id	string	是	-	任务 ID（单任务查询时路径参数）
pageNum	int	否	1	页码，范围 [1, 1000]
pageSize	int	否	30	每页数据量，范围 [1, 500]
provider	string	否	-	指定服务商

请求示例

json

{
  "model_name": "kling-v1-6",
  "image_list": [
    {
      "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog.png"
    },
    {
      "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog_cloth.png"
    }
  ],
  "prompt": "一只白色比熊穿着东北红色花棉袄，舔自己的手",
  "negative_prompt": "",
  "mode": "pro",
  "duration": "5",
  "aspect_ratio": "16:9",
  "callback_url": "",
  "external_task_id": ""
}

返回结构示例

创建任务返回

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "submitted",
    "task_info": {
      "external_task_id": "string"
    },
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回（单个/列表元素）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_status_msg": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_result": {
      "videos": [
        {
          "id": "string",
          "url": "string",
          "watermark_url": "string",
          "duration": "string"
        }
      ]
    },
    "watermark_info": {
      "enabled": true
    },
    "final_unit_deduction": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

注意事项

model 是兼容字段，建议优先使用 model_name。
多图输入建议直接按 { "image": "..." } 结构传参，最稳定。

5. 动作控制（Motion Control）

动作控制用于通过参考图像和参考视频生成视频，使生成视频中的人物动作与参考视频一致。

官方文档入口（仅参考）：https://klingai.com/document-api/

创建动作控制任务

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/motion-control`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

参数名	类型	必填	默认值	说明
`model_name`	string	可选	`Kling-V2.6`	推荐模型字段，目前支持`Kling-V3`，`Kling-V2.6`
`model`	string	可选	无	兼容字段，会映射到 `model_name`
`prompt`	string	可选	空	文本提示词，不超过 2500
`image_url`	string	必填	无	参考图像（URL/Base64）
`video_url`	string	必填	无	参考视频链接
`element_list`	array	可选	空	主体参考列表（当前最多 1 个主体）
`keep_original_sound`	string	可选	`yes`	是否保留原声：`yes`/`no`
`character_orientation`	string	必填	无	人物朝向：`image` / `video`
`mode`	string	必填	无	生成模式：`std` / `pro`
`watermark_info`	object	可选	空	水印开关，格式：`{\"enabled\": boolean}`
`callback_url`	string	可选	空	回调地址
`external_task_id`	string	可选	空	自定义任务 ID

prompt

文本提示词，可包含正向描述和负向描述。可通过提示词为画面增加元素、实现运镜效果等。

可选参数。
不能超过 2500 个字符。
当不传入时，服务商会主要依据 image_url 和 video_url 生成动作控制结果。

image_url

参考图像，生成视频中的人物、背景等元素均以参考图为准。

图片内容建议：

人物比例尽量与参考动作比例一致，尽量避免使用全身动作驱动半身人物进行生成。
人物需要露出清晰的上半身或全身肢体及头部，避免遮挡。
画面中人物避免极端朝向，例如倒立、平卧等。
人物占画面比例不宜过低。
支持真实或风格化角色，包括人物、类人动物、部分纯动物、部分类人肢体比例角色。

图片格式要求：

支持图片 URL 或 Base64 编码。
使用 Base64 时不要添加 data:image/png;base64, 等前缀，直接传 Base64 字符串。
图片格式支持 .jpg / .jpeg / .png。
图片文件大小不能超过 10MB。
图片宽高尺寸介于 300px ~ 65536px。
图片宽高比介于 1:2.5 ~ 2.5:1。

video_url

参考视频的获取链接。生成视频中的人物动作与参考视频一致。

视频内容建议：

人物需要露出清晰的上半身或全身肢体及头部，避免遮挡。
建议上传 1 人动作视频；2 人及以上时，服务商通常会取画面占比最大的人物动作进行生成。
推荐使用真人动作，部分风格化人物或类人肢体比例角色可以通过。
动作视频建议一镜到底，角色始终出现在画面中，避免切镜、明显运镜等，否则可能被截取。
动作不宜过快，相对平稳的动作生成效果更佳。
动作难度较高或速度较快时，可能生成不足上传视频时长的结果；模型最短提取出 3 秒可用连续动作即可生成。

视频格式要求：

视频文件支持 .mp4 / .mov。
文件大小不能超过 100MB。
视频宽高边长均需位于 340px ~ 3850px。
视频时长不短于 3 秒。
当 character_orientation=image 时，参考视频时长最长 10 秒。
当 character_orientation=video 时，参考视频时长最长 30 秒。
系统会校验视频内容；校验不通过时会返回错误码等信息。

element_list

参数名	类型	必填	默认值	说明
`element_list`	array	否	无	主体参考列表，基于主体库中的主体 ID 配置。动作控制场景下暂时仅支持引入 1 个主体。

子参数

参数名	类型	必填	默认值	说明
`element_id`	long	是	无	主体库中的主体 ID。

请求格式

json

{
  "element_list": [
    {
      "element_id": 829836802793406551
    }
  ]
}

character_orientation

生成视频中人物的朝向，可选择与图片一致或与视频一致。

取值	说明
`image`	与图片中人物朝向一致；此时参考视频时长不得超过 `10` 秒
`video`	与视频中人物朝向一致；此时参考视频时长不得超过 `30` 秒

mode

生成视频的模式。

取值	说明
`std`	标准模式，基础模式，性价比高
`pro`	专家模式，高品质模式，生成视频质量更佳

不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

watermark_info

是否同时生成含水印的结果。

json

{
  "watermark_info": {
    "enabled": false
  }
}

子参数	类型	必填	说明
`enabled`	boolean	是	`true` 表示生成含水印结果，`false` 表示不生成含水印结果

暂不支持自定义水印。

callback_url

本次任务结果回调通知地址。如果配置，服务端会在任务状态发生变更时主动通知。

external_task_id

自定义任务 ID。

查询任务

功能	方法	路径
创建	POST	`/v1/videos/kling/motion-control`
单任务查询	GET	`/v1/videos/kling/motion-control/{task_id}`
列表查询	GET	`/v1/videos/kling/motion-control?pageNum=1&pageSize=30`

参数兼容

兼容字段	行为
`action_control`	历史兼容字段；当前路径下会在透传前清理，不作为必填

请求示例（官方字段）

json

{
  "model_name": "Kling-V2.6",
  "image_url": "https://example.com/character.png",
  "video_url": "https://example.com/motion.mp4",
  "character_orientation": "video",
  "prompt": "保持角色形象一致，跟随参考视频动作",
  "mode": "pro"
}

返回结构示例

创建任务返回示例

json

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_status": "submitted",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（单个）

json

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_status_msg": "string",
    "task_result": {
      "videos": [
        {
          "id": "string",
          "url": "string",
          "duration": "string"
        }
      ]
    },
    "final_unit_deduction": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（列表）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": [
    {
      "task_id": "string",
      "task_status": "submitted|processing|succeed|failed",
      "task_status_msg": "string",
      "task_info": {
        "external_task_id": "string"
      },
      "task_result": {
        "videos": [
          {
            "id": "string",
            "url": "string",
            "watermark_url": "string",
            "duration": "string"
          }
        ]
      },
      "watermark_info": {
        "enabled": true
      },
      "final_unit_deduction": "string",
      "created_at": 1722769557708,
      "updated_at": 1722769557708
    }
  ],
  "aiping_id": "string"
}

注意事项

建议优先使用 model_name；model 为兼容写法。
action_control 不是当前主参数，仅为历史兼容字段。
mode 在官方动作控制接口口径下为 std/pro，请避免传入不受支持模式。

6. Omni / 多镜头（Omni Video）

官方文档入口（仅参考）：

https://klingai.com/document-api/apiReference/model/OmniVideo

创建任务

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/omni-video`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

参数名	类型	必填	默认值	说明
`model_name`	string	否	上游默认	推荐模型字段，目前支持`kling-video-o1` ， `kling-v3-omni`
`model`	string	否	无	兼容字段，会映射到 `model_name`
`multi_shot`	boolean	否	`false`	是否多镜头；`kling-video-o1` 不支持分镜
`shot_type`	string	条件必填	无	`multi_shot=true` 时生效
`prompt`	string	条件必填	无	提示词（单镜头或智能分镜必填）
`multi_prompt`	array	条件必填	无	`multi_shot=true` 且 `shot_type=customize` 时必填
`image_list`	array	否	空	参考图列表（可含首尾帧）
`element_list`	array	否	空	主体参考列表
`video_list`	array	否	空	参考视频列表（`refer_type=base/feature`）
`sound`	string	否	`off`	是否生成声音
`mode`	string	否	`pro`	模式（`std`/`pro`/`4k`）
`aspect_ratio`	string	否	无	画幅（`16:9`/`9:16`/`1:1`）
`seconds`	string	否	无	兼容时长字段
`duration`	string	否	无	时长字段
`watermark_info`	object	否	空	水印开关
`callback_url`	string	否	空	回调地址
`external_task_id`	string	否	空	自定义任务 ID

multi_shot

是否生成多镜头视频。

取值	说明
`false`	单镜头视频。此时 `shot_type` 和 `multi_prompt` 无效。
`true`	多镜头视频。此时 `prompt` 参数无效，需要通过 `shot_type` 指定分镜方式。

默认值为 false。

kling-video-o1 不支持分镜，请保持 multi_shot=false。

shot_type

分镜方式。当 multi_shot=true 时，当前参数必填。

取值	说明
`customize`	自定义分镜。需要传入 `multi_prompt`。
`intelligence`	智能分镜。需要传入 `prompt`。

当 multi_shot=false 时，当前参数无效。

prompt

文本提示词，可包含正向描述和负向描述。可将提示词模板化来满足不同的视频生成需求。

可选参数。
不能超过 2500 个字符。
当 multi_shot=false 时，当前参数不得为空。
当 multi_shot=true 且 shot_type=intelligence 时，当前参数不得为空。
当 multi_shot=true 且 shot_type=customize 时，当前参数无效，分镜提示词应填写在 multi_prompt 中。

Omni 模型可通过 Prompt 与主体、图片、视频等内容实现多种能力：

通过 <<<image_1>>> 引用 image_list 中的第 1 张图片。
通过 <<<element_1>>> 引用 element_list 中的第 1 个主体。
通过 <<<video_1>>> 引用 video_list 中的第 1 个视频。
例如：参考<<<video_1>>>的运镜方式，让<<<element_1>>>和<<<image_1>>>中的人物同框出现。

multi_prompt 元素

参数名	类型	必填	说明
`index`	int	是	分镜序号
`prompt`	string	是	分镜提示词
`duration`	string	是	分镜时长

各分镜信息，通过 index、prompt、duration 定义分镜序号、提示词和时长。

参数规则：

当 multi_shot=true 且 shot_type=customize 时，当前参数不得为空。
最多支持 6 个分镜，最少支持 1 个分镜。
每个分镜相关内容最大长度不超过 512 个字符。
每个分镜的时长不大于当前任务总时长，且不小于 1 秒。
所有分镜的时长之和需要等于当前任务的总时长。

格式如下：

json

"multi_prompt":[
  { "index": int, "prompt": "string", "duration": "5" },
  { "index": int, "prompt": "string", "duration": "5" }
]

参数名	类型	必填	默认值	说明
`video_list`	array	否	无	参考视频列表，通过 URL 获取。可作为特征参考视频，也可作为待编辑视频；默认由服务商按待编辑视频处理。当前最多支持 1 段视频。

子参数

参数名	类型	必填	默认值	说明
`video_url`	string	是	无	视频 URL。不能为空。
`refer_type`	string	否	`base`	视频参考类型。`base` 表示待编辑视频/指令变换；`feature` 表示特征参考视频。
`keep_original_sound`	string	否	服务商默认	是否保留原声。`yes` 表示保留，`no` 表示不保留；对 `feature` 类型也生效。

参数规则

refer_type=base 时表示待编辑视频，不能同时定义视频首尾帧。
有参考视频时，sound 只能为 off。
视频格式仅支持 .mp4 / .mov。
视频时长不少于 3 秒，上限与模型版本、视频类型有关。
视频分辨率需在 720px-2160px 范围内。
视频帧率需为 24-60fps，生成结果通常输出为 24fps。
当前最多支持 1 段视频，大小不超过 200MB。

请求示例

json

{
  "model_name": "kling-video-o1",
  "prompt": "参考<<<video_1>>>的运镜方式，生成下一个镜头",
  "video_list": [
    {
      "video_url": "https://example.com/source.mp4",
      "refer_type": "feature",
      "keep_original_sound": "yes"
    }
  ],
  "mode": "pro",
  "sound": "off"
}

image_list

参数名	类型	必填	默认值	说明
`image_list`	array	否	无	参考图列表，可用于主体、场景、风格参考，也可作为首帧或尾帧生成视频。

子参数

参数名	类型	必填	默认值	说明
`image_url`	string	是	无	图片 URL 或 Base64 字符串。不能为空。
`type`	string	否	无	帧类型。`first_frame` 表示首帧，`end_frame` 表示尾帧。非首尾帧参考图请不要配置该字段。

参数规则

type=first_frame 表示首帧图，type=end_frame 表示尾帧图。
暂不支持仅尾帧；如果传入尾帧图，必须同时传入首帧图。
首帧或首尾帧生视频时，不能同时使用视频编辑功能。
图片支持 URL 或 Base64；使用 Base64 时不要添加 data:image/...;base64, 前缀。
图片格式支持 .jpg / .jpeg / .png。
图片文件大小不超过 10MB。
图片宽和高都不能小于 300px。
图片宽高比需在 1:2.5 ~ 2.5:1 之间。
image_url 参数值不能为空。

数量限制

无参考视频且仅有多图主体时，参考图片数量与多图主体数量之和不得超过 7。
无参考视频且有视频主体时，参考图片数量与多图主体数量之和不得超过 4。
有参考视频且仅有多图主体时，参考图片数量与多图主体数量之和不得超过 4。
使用 kling-video-o1 模型时，如果 image_list 超过 2 张图片，不支持设置首尾帧。

请求示例

普通参考图：

json

{
  "model_name": "kling-video-o1",
  "prompt": "参考<<<image_1>>>中的人物，在城市街头行走",
  "image_list": [
    {
      "image_url": "https://example.com/person.png"
    }
  ],
  "mode": "pro",
  "aspect_ratio": "16:9",
  "duration": "5"
}

首尾帧：

json

{
  "model_name": "kling-video-o1",
  "prompt": "让人物从首帧动作自然过渡到尾帧姿态",
  "image_list": [
    {
      "image_url": "https://example.com/first.png",
      "type": "first_frame"
    },
    {
      "image_url": "https://example.com/end.png",
      "type": "end_frame"
    }
  ],
  "mode": "pro"
}

element_list

参数名	类型	必填	默认值	说明
`element_list`	array	否	无	主体参考列表，基于主体库中的主体 ID 配置。可在 Prompt 中通过 `<<<element_1>>>`、`<<<element_2>>>` 等方式引用。

子参数

参数名	类型	必填	默认值	说明
`element_id`	long	是	无	主体库中的主体 ID。不能为空。

请求格式

json

{
  "element_list": [
    {
      "element_id": 123456789
    },
    {
      "element_id": 987654321
    }
  ]
}

参数规则

主体分为视频定制主体（视频角色主体）和图片定制主体（多图主体），不同主体类型适用范围不同。
当使用首帧或首尾帧生成视频时，kling-v3-omni 最多支持 3 个主体。
当使用首尾帧生成视频时，kling-video-o1 不支持主体。
无参考视频且仅有多图主体时，参考图片数量与多图主体数量之和不得超过 7。
无参考视频且仅有视频角色主体时，视频角色主体数量不得超过 3。
无参考视频且同时有视频角色主体和多图主体时，视频角色主体数量不得超过 3，参考图片数量与多图主体数量之和不得超过 4。
有参考视频且仅有多图主体时，参考图片数量与多图主体数量之和不得超过 4。
有参考视频时，不支持使用视频角色主体。

watermark_info

参数名	类型	必填	默认值	说明
`watermark_info`	object	否	服务商默认	是否同时生成含水印的结果。通过 `enabled` 字段控制。暂不支持自定义水印。

子参数

参数名	类型	必填	默认值	说明
`enabled`	boolean	是	无	`true` 表示生成含水印结果，`false` 表示不生成含水印结果。

请求格式

json

{
  "watermark_info": {
    "enabled": false
  }
}

sound

生成视频时是否同时生成声音。

取值	说明
`on`	生成声音
`off`	不生成声音

默认值为 off。有参考视频时，sound 参数值只能为 off。不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

mode

生成视频的模式。

取值	说明
`std`	标准模式，基础模式，性价比高，通常输出 720P。
`pro`	专家模式，高品质模式，通常输出 1080P。
`4k`	4K 模式，高表现模式，通常输出 4K。

默认值为 pro。不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

aspect_ratio

生成视频的画面纵横比。

取值
`16:9`
`9:16`
`1:1`

未使用首帧参考或视频编辑功能时，当前参数必填。图生视频、首尾帧、视频编辑等场景下，画幅支持范围以服务商实际能力为准。

duration

生成视频时长，单位为秒。

默认值为 5。使用视频编辑功能时，即 video_list[].refer_type=base，输出结果与传入视频时长相同，此时当前参数无效，并按输入视频时长四舍五入取整计量计费。不同模型版本、视频模式支持范围不同，具体以服务商能力为准。

callback_url

本次任务结果回调通知地址。如果配置，服务端会在任务状态发生变更时主动通知。

external_task_id

自定义任务 ID。传入后不会覆盖系统生成的任务 ID，但支持通过该 ID 查询任务。单用户下需保证唯一。

查询任务

查询单个

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/omni-video/{task_id}`	GET	application/json	application/json

查询列表

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/omni-video?pageNum=1&pageSize=30`	GET	application/json	application/json

关键约束

多镜头开启时，shot_type 与 multi_prompt 需满足组合规则。
有 video_list 且 refer_type=base 时，上游 Omni 会按“视频编辑/指令变换”场景处理；请求路径仍为 /v1/videos/kling/omni-video，但时长/比例等参数会受到视频编辑场景限制。
Kling-Video-O1、Kling-V3-Omni 应优先走本路径；若走 text2video/image2video 路径可能返回 422。

请求示例

json

{
  "model_name": "kling-v3-omni",
  "multi_shot": true,
  "shot_type": "customize",
  "prompt": "",
  "multi_prompt": [
    { "index": 1, "prompt": "镜头一：夜晚街灯下对话", "duration": "2" },
    { "index": 2, "prompt": "镜头二：森林中奔跑", "duration": "3" }
  ],
  "image_list": [
    { "image_url": "https://example.com/1.png" }
  ],
  "mode": "pro",
  "sound": "on",
  "aspect_ratio": "16:9",
  "duration": "5",
  "callback_url": "",
  "external_task_id": ""
}

返回结构示例

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "submitted",
    "task_info": {
      "external_task_id": "string"
    },
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（单个）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_status_msg": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_result": {
      "videos": [
        {
          "id": "string",
          "url": "string",
          "watermark_url": "string",
          "duration": "string"
        }
      ]
    },
    "watermark_info": {
      "enabled": true
    },
    "final_unit_deduction": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（列表）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": [
    {
      "task_id": "string",
      "task_status": "succeed",
      "task_status_msg": "string",
      "task_info": {
        "external_task_id": "string"
      },
      "task_result": {
        "videos": [
          {
            "id": "string",
            "url": "string",
            "watermark_url": "string",
            "duration": "string"
          }
        ]
      },
      "watermark_info": {
        "enabled": true
      },
      "final_unit_deduction": "string",
      "created_at": 1722769557708,
      "updated_at": 1722769557708
    }
  ],
  "aiping_id": "string"
}

7. 多模态视频编辑（Multi-Elements）

官方文档入口（仅参考）：

https://klingai.com/document-api/apiReference/model/multiElements

能力流程

多模态视频编辑通常按以下顺序调用：

初始化待编辑视频：init-selection
标记选区：add-selection（可配合 delete-selection、clear-selection）
预览选区：preview-selection
创建编辑任务：multi-elements
查询任务：单个 / 列表

1 初始化待编辑视频

接口

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/multi-elements/init-selection`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

参数名	类型	必填	默认值	说明
`video_id`	string	条件必填	无	与 `video_url` 二选一
`video_url`	string	条件必填	无	与 `video_id` 二选一

参数说明

video_id

视频 ID，从历史作品中选择待编辑的视频。

可选参数。
仅支持 30 天内生成的视频作品。
仅支持时长 >=2 秒且 <=5 秒，或 >=7 秒且 <=10 秒的视频。
与 video_url 不能同时为空，也不能同时有值。

video_url

待编辑视频 URL。上传时传视频下载链接；编辑选区时可传接口返回的视频 URL。

可选参数。
仅支持 .mp4 / .mov 格式。
仅支持时长 >=2 秒且 <=5 秒，或 >=7 秒且 <=10 秒的视频。
视频宽高尺寸需介于 720px ~ 2160px。
仅支持 24fps、30fps 或 60fps 的视频。
与 video_id 不能同时为空，也不能同时有值。

返回字段说明

初始化成功后，响应中的 data 通常包含以下字段：

字段	类型	说明
`status`	int	拒识码，非 0 表示识别失败
`session_id`	string	会话 ID，基于视频初始化任务生成，不会随编辑选区行为改变，有效期通常为 24 小时
`final_unit_deduction`	string	任务最终扣减积分数值
`fps`	float	解析后视频帧率，在获取选区展示视频时需携带
`original_duration`	int	解析后视频时长，在创建任务时需携带
`width`	int	解析后视频宽度
`height`	int	解析后视频高度
`total_frame`	int	解析后视频总帧数，在创建任务时需携带
`normalized_video`	string	初始化后的视频 URL

2 增加视频选区

接口

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/multi-elements/add-selection`	POST	application/json	application/json

请求体参数

参数名	类型	必填	说明
`session_id`	string	是	初始化后返回的会话 ID
`frame_index`	int	是	帧号
`points`	array	是	选区点位数组（`x`,`y`）

points 子项：

参数名	类型	必填	说明
`x`	float	是	范围 `[0,1]`
`y`	float	是	范围 `[0,1]`

参数规则

最多支持添加 10 个标记帧，即最多基于 10 帧标记视频选区。
1 次仅支持标记 1 帧。
points 坐标使用百分比表示，取值范围为 [0,1]。
[0,1] 代表画面左上角。
支持同时增加多个标记点，某一帧最多可标记 10 个点。

返回字段说明

增加选区成功后，响应中的 data.res 通常包含：

字段	类型	说明
`frame_index`	int	标记帧号
`rle_mask_list`	array	分割结果列表

rle_mask_list 子项：

字段	类型	说明
`object_id`	int	选区对象 ID
`rle_mask.size`	array	RLE mask 尺寸
`rle_mask.counts`	string	RLE mask 编码
`png_mask.size`	array	PNG mask 尺寸
`png_mask.base64`	string	PNG mask 的 Base64 数据

3 删减视频选区

接口

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/multi-elements/delete-selection`	POST	application/json	application/json

请求体参数

参数名	类型	必填	说明
`session_id`	string	是	会话 ID
`frame_index`	int	是	帧号
`points`	array	是	待删除点位（需与添加时一致）

参数规则

points 坐标使用百分比表示，取值范围为 [0,1]。
[0,1] 代表画面左上角。
支持同时删减多个标记点。
坐标点需与增加视频选区时完全一致。

4 清除视频选区

接口

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/multi-elements/clear-selection`	POST	application/json	application/json

请求体参数

参数名	类型	必填	说明
`session_id`	string	是	会话 ID

清除成功后会保留当前 session_id，但清除该会话下已标记的视频选区。

5 预览已选区视频

接口

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/multi-elements/preview-selection`	POST	application/json	application/json

请求体参数

参数名	类型	必填	说明
`session_id`	string	是	会话 ID

预览成功后，响应中的 data.res 通常包含：

字段	类型	说明
`video`	string	含 mask 的视频 URL
`video_cover`	string	含 mask 视频的封面 URL
`tracking_output`	string	图像分割结果中每一帧 mask 结果

6 创建编辑任务

接口

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/multi-elements`	POST	application/json	application/json

请求体参数

参数名	类型	必填	默认值	说明
`model_name`	string	否	`kling-v1-6`	推荐模型字段
`model`	string	否	无	兼容字段，会映射到 `model_name`
`session_id`	条件必填	string	无	会话流编辑必填
`edit_mode`	string	条件必填	无	`addition` / `swap` / `removal`
`image_list`	array	条件必填	空	`addition/swap` 通常需要，`removal` 可为空
`prompt`	string	是	无	编辑提示词
`negative_prompt`	string	否	空	负向提示词
`mode`	string	否	`std`	模式（`std` / `pro`）
`seconds`	string	否	无	兼容时长字段，会映射为 `duration`
`duration`	string	否	`5`	时长字段
`watermark_info`	object	否	空	水印开关
`callback_url`	string	否	空	回调地址
`external_task_id`	string	否	空	自定义任务 ID

session_id

会话 ID，由初始化待编辑视频接口返回。会基于视频初始化任务生成，不会随编辑选区行为改变。

edit_mode

操作类型。

取值	说明
`addition`	增加元素
`swap`	替换元素
`removal`	删除元素

image_list

裁剪后的参考图像列表。

使用规则：

增加视频元素时：当前参数必填，可上传 1 到 2 张图片。
替换视频元素时：当前参数必填，仅可上传 1 张图片。
删除视频元素时：当前参数无需填写。
API 端无裁剪逻辑，请直接上传已选主体后的图片。

图片格式要求：

支持图片 URL 或 Base64 编码。
使用 Base64 时不要添加 data:image/png;base64, 等前缀，直接传 Base64 字符串。
图片格式支持 .jpg / .jpeg / .png。
图片文件大小不能超过 10MB。
图片宽高尺寸不小于 300px。
图片宽高比介于 1:2.5 ~ 2.5:1。

格式如下：

json

{
  "image_list": [
    { "image": "https://example.com/reference.png" }
  ]
}

image_list 元素兼容：

image
image_url
url
base64

prompt

正向文本提示词。

必填参数。
可用 <<<xxx>>> 格式特指某个视频或某张图片，例如 <<<video_1>>>、<<<image_1>>>。
为保证效果，提示词中需包含视频编辑所需的视频和图片引用。
不能超过 2500 个字符。

negative_prompt

负向文本提示词。

可选参数。
不能超过 2500 个字符。

mode

生成视频的模式。

取值	说明
`std`	标准模式，基础模式，性价比高
`pro`	专家模式，高品质模式，生成视频质量更佳

默认值为 std。

duration

生成视频时长，单位为秒。

取值	说明
`5`	生成 5 秒视频；输入视频时长需 `>=2` 秒且 `<=5` 秒
`10`	生成 10 秒视频；输入视频时长需 `>=7` 秒且 `<=10` 秒

支持且仅支持生成 5 秒和 10 秒的视频。

watermark_info

是否同时生成含水印的结果。

json

{
  "watermark_info": {
    "enabled": false
  }
}

子参数	类型	必填	说明
`enabled`	boolean	是	`true` 表示生成含水印结果，`false` 表示不生成含水印结果

暂不支持自定义水印。

callback_url

本次任务结果回调通知地址。如果配置，服务端会在任务状态发生变更时主动通知。

external_task_id

自定义任务 ID。传入后不会覆盖系统生成的任务 ID，但支持通过该 ID 查询任务。单用户下需保证唯一。

7 查询任务

查询单个

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/multi-elements/{task_id}`	GET	application/json	application/json

查询列表

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/multi-elements?pageNum=1&pageSize=30`	GET	application/json	application/json

查询参数

参数名	类型	必填	默认值	说明
`pageNum`	int	否	1	页码，范围 `[1, 1000]`
`pageSize`	int	否	30	每页数据量，范围 `[1, 500]`

请求示例

初始化

json

{
  "video_url": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/animals-output-5s.mp4"
}

增加选区

json

{
  "session_id": "847570360458960960",
  "frame_index": 0,
  "points": [
    { "x": 0.77, "y": 0.29 }
  ]
}

创建任务（删除元素）

json

{
  "model_name": "kling-v1-6",
  "session_id": "847570360458960960",
  "edit_mode": "removal",
  "prompt": "删除<<<video_1>>>中的【小鸡】",
  "mode": "std",
  "duration": "5",
  "callback_url": "",
  "external_task_id": ""
}

兼容说明：

model 兼容映射为 model_name
seconds 兼容映射为 duration
会自动清理 uid/create_at/_standard_model/action_control 等系统字段

创建任务返回

json

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "submitted",
    "task_info": {
      "external_task_id": "string"
    },
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（单个）

json

{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_status_msg": "string",
    "task_info": {
      "external_task_id": "string"
    },
    "task_result": {
      "videos": [
        {
          "id": "string",
          "session_id": "id",
          "url": "string",
          "watermark_url": "string",
          "duration": "string"
        }
      ]
    },
    "watermark_info": {
      "enabled": true
    },
    "final_unit_deduction": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  },
  "aiping_id": "string"
}

查询任务返回示例（列表）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "data": [
    {
      "task_id": "string",
      "task_status": "submitted|processing|succeed|failed",
      "task_status_msg": "string",
      "task_info": {
        "external_task_id": "string"
      },
      "task_result": {
        "videos": [
          {
            "id": "string",
            "session_id": "id",
            "url": "string",
            "watermark_url": "string",
            "duration": "string"
          }
        ]
      },
      "watermark_info": {
        "enabled": true
      },
      "final_unit_deduction": "string",
      "created_at": 1722769557708,
      "updated_at": 1722769557708
    }
  ],
  "aiping_id": "string"
}

8. 视频延长（Video Extend）

视频延长用于对文生视频、图生视频或视频延长生成的视频结果继续延长。

官方文档入口（仅参考）：https://klingai.com/document-api/apiReference/model/videoExtension

创建任务

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/video-extend`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

参数名	类型	必填	默认值	说明
`video_id`	string	是	无	视频 ID，支持通过文生视频、图生视频和视频延长生成的视频 ID，仅支持 V1.6 模型生成的视频
`prompt`	string	否	无	文本提示词，长度不超过 2500 个字符
`negative_prompt`	string	否	空	负向文本提示词，长度不超过 2500 个字符
`cfg_scale`	float	否	`0.5`	提示词参考强度，数值越大参考强度越大，范围 `[0,1]`
`watermark_info`	object	否	空	水印开关，格式为 `{ "enabled": boolean }`，暂不支持自定义水印
`callback_url`	string	否	空	本次任务结果回调通知地址，任务状态变化时服务端主动通知
`external_task_id`	string	否	空	自定义任务 ID，不覆盖系统生成的任务 ID，但支持通过该 ID 查询任务；单用户下需保证唯一

video_id

video_id 为需要延长的源视频 ID，类型为 string，必填。

支持通过文生视频、图生视频和视频延长生成的视频 ID。源视频不能超过 3 分钟，且仅支持 V1.6 模型生成的视频。

请注意，基于目前的清理策略，视频生成 30 天后会被清理，清理后无法继续延长，请及时转存。

prompt

prompt 为文本提示词，类型为 string，可选，不能超过 2500 个字符。

可用于描述本次延长片段希望继续出现的内容、动作、镜头变化或场景变化。

negative_prompt

negative_prompt 为负向文本提示词，类型为 string，可选，不能超过 2500 个字符。

cfg_scale

cfg_scale 为提示词参考强度，类型为 float，可选，默认值为 0.5。

取值范围为 [0,1]，数值越大，提示词参考强度越大。

watermark_info

watermark_info 用于控制是否同时生成含水印的结果，类型为 object，可选。

格式如下：

json

{
  "watermark_info": {
    "enabled": true
  }
}

enabled=true 表示生成含水印结果，enabled=false 表示不生成含水印结果。暂不支持自定义水印。

callback_url

callback_url 为本次任务结果回调通知地址，可选。如果配置，服务端会在任务状态发生变更时主动通知。

external_task_id

external_task_id 为自定义任务 ID，可选。传入后不会覆盖系统生成的任务 ID，但支持通过该 ID 查询任务。请注意，单用户下需要保证唯一性。

关键约束

视频延长是对源视频进行时间延长，单次可延长 4-5 秒。
使用的模型和模式不可选择，默认与源视频相同。
被延长后的视频可以再次延长，但总视频时长不能超过 3 分钟。
源视频不能超过 3 分钟，且仅支持 V1.6 模型生成的视频。
生成的视频/图片通常会在 30 天后被清理，清理后无法继续延长，请及时转存。

查询任务（单个）

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/video-extend/{id}`	GET	application/json	application/json

路径参数

参数名	类型	必填	说明
`task_id`	string	条件必填	视频延长任务 ID，直接填入路径；与 `external_task_id` 二选一
`external_task_id`	string	条件必填	自定义任务 ID，直接填入路径；与 `task_id` 二选一

查询任务（列表）

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/videos/kling/video-extend`	GET	application/json	application/json

查询参数

参数名	类型	必填	默认值	说明
`pageNum`	int	否	`1`	页码，范围 `[1,1000]`
`pageSize`	int	否	`30`	每页数据量，范围 `[1,500]`

请求示例

bash

curl --request POST \
  --url https://aiping.cn/api/v1/videos/kling/video-extend \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "出现一只小狗",
    "video_id": "743211632612511839",
    "negative_prompt": "",
    "callback_url": ""
  }'

json

{
  "prompt": "出现一只小狗",
  "video_id": "743211632612511839",
  "negative_prompt": "",
  "callback_url": ""
}

查询单个任务示例

bash

curl --request GET \
  --url https://aiping.cn/api/v1/videos/kling/video-extend/{task_id} \
  --header 'Authorization: Bearer <token>'

查询任务列表示例

bash

curl --request GET \
  --url 'https://aiping.cn/api/v1/videos/kling/video-extend?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'

返回结构示例

创建任务返回示例

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "aiping_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "submitted",
    "task_info": {
      "external_task_id": "string"
    },
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  }
}

查询任务返回示例（单个/列表元素）

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "aiping_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_status_msg": "string",
    "task_info": {
      "parent_video": {
        "id": "string",
        "url": "string",
        "duration": "string"
      },
      "external_task_id": "string"
    },
    "task_result": {
      "videos": [
        {
          "id": "string",
          "url": "string",
          "watermark_url": "string",
          "duration": "string"
        }
      ]
    },
    "watermark_info": {
      "enabled": true
    },
    "final_unit_deduction": "string",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  }
}

查询任务列表返回示例

json

{
  "code": 0,
  "message": "string",
  "request_id": "string",
  "aiping_id": "string",
  "data": [
    {
      "task_id": "string",
      "task_status": "succeed",
      "task_status_msg": "string",
      "task_info": {
        "parent_video": {
          "id": "string",
          "url": "string",
          "duration": "string"
        },
        "external_task_id": "string"
      },
      "task_result": {
        "videos": [
          {
            "id": "string",
            "url": "string",
            "watermark_url": "string",
            "duration": "string"
          }
        ]
      },
      "watermark_info": {
        "enabled": true
      },
      "final_unit_deduction": "string",
      "created_at": 1722769557708,
      "updated_at": 1722769557708
    }
  ]
}

注意事项

watermark_info.enabled=true 表示生成含水印结果，false 表示不生成。
单个任务查询路径中的 {id} 可填写系统任务 ID 或自定义任务 ID。
资源 URL 有清理周期，生成结果请及时转存。

9. 主体管理（Elements）

新版主体（Element）基于可灵高级版接口，支持图片或视频参考创建主体，并可绑定/定制音色。与旧版（/v1/elements/*，同步返回）不同，新版为异步任务制：创建后先返回主体 ID，需轮询查询单个接口直到状态为 succeed。本文档以项目实现为主。

官方文档入口（仅参考）：

https://klingai.com/document-api/

重要约定

主体 ID：创建成功后返回主体唯一标识 element_id（形如 elem_lp_xxxxx），后续查询、视频生成、删除均使用该 ID。
异步状态：status 枚举为 pending（处理中）、succeed（成功）、failed（失败）。创建后通常为 pending，需轮询查询单个接口；后台也会自动收敛状态。
可用时机：仅当 status = succeed 后，该主体才可用于视频生成。

创建主体

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/kling/general/advanced-custom-elements`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息，参考接口鉴权

请求体参数

字段	类型	必填	默认值	描述
`element_name`	string	必填	无	主体名称，不能超过 20 个字符
`element_description`	string	必填	无	主体描述，不能超过 100 个字符
`reference_type`	string	必填	无	主体参考方式，枚举：`image_refer`（多图主体）、`video_refer`（视频角色主体）
`element_image_list`	object	条件必填	无	`reference_type=image_refer` 时必填。含 1 张正面参考图与 1~3 张其他参考图
`element_video_list`	object	条件必填	无	`reference_type=video_refer` 时必填。至多 1 段视频；含人声时触发音色定制
`element_voice_id`	string	可选	无	绑定音色库中已有音色 ID
`tag_list`	array	可选	无	主体标签列表，如 `[{"tag_id":"o_102"}]`
`external_task_id`	string	可选	无	自定义任务 ID（单用户内需唯一）
`callback_url`	string	可选	无	任务结果回调地址（透传可灵）

element_image_list 结构

json

"element_image_list": {
  "frontal_image": "image_url_0",
  "refer_images": [{ "image_url": "image_url_1" }]
}

支持图片 URL 或 Base64；格式 .jpg/.jpeg/.png，大小 ≤ 10MB，宽高 ≥ 300px，宽高比在 1:2.5 ~ 2.5:1。

json

"element_video_list": {
  "refer_videos": [{ "video_url": "video_url_1" }]
}

视频格式 MP4/MOV，时长 3s~8s，宽高比 16:9 或 9:16 的 1080P，至多 1 段，大小 ≤ 200MB。
视频定制的主体仅支持用于 kling-video-o3 及之后的模型。

请求示例（图片定制）

bash

curl -sS -X POST \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  "https://aiping.cn/api/v1/kling/general/advanced-custom-elements" \
  -d '{
    "element_name": "测试主体",
    "element_description": "这是一个测试主体描述",
    "reference_type": "image_refer",
    "element_image_list": {
      "frontal_image": "https://example.com/image0.jpg",
      "refer_images": [
        { "image_url": "https://example.com/image1.jpg" },
        { "image_url": "https://example.com/image2.jpg" }
      ]
    },
    "tag_list": [{ "tag_id": "o_102" }]
  }'

请求示例（视频定制）

json

{
  "element_name": "视频主体",
  "element_description": "通过视频定制的主体",
  "reference_type": "video_refer",
  "element_video_list": {
    "refer_videos": [{ "video_url": "https://example.com/video.mp4" }]
  },
  "element_voice_id": ""
}

创建返回

json

{
  "code": 0,
  "message": "success",
  "data": {
    "element_id": "elem_lp_5f8c0a3b4d2e4f1c9a7b6e5d4c3b2a10",
    "element_name": "测试主体",
    "status": "pending",
    "reference_type": "image_refer"
  }
}

element_id 为后续查询/使用的统一主体 ID；status=pending 表示仍在处理，需轮询查询单个接口。

查询自定义主体（单个）

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/kling/general/advanced-custom-elements/{task_id}`	GET	application/json	application/json

请求头

字段	值	描述
Authorization	Bearer	鉴权信息

路径参数

字段	类型	必填	默认值	描述
`task_id`	string	必填	无	主体 ID（创建时返回的 `task_id`）。

请求示例

bash

curl -sS \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  "https://aiping.cn/api/v1/kling/general/advanced-custom-elements/{task_id}"

查询返回

json

{
  "code": 0,
  "message": "success",
  "data": {
    "element_id": "elem_lp_5f8c0a3b4d2e4f1c9a7b6e5d4c3b2a10",
    "element_name": "测试主体",
    "status": "succeed",
    "reference_type": "image_refer"
  }
}

status=failed 时，data.error_message 给出失败原因（如触发内容风控）。

查询自定义主体（列表）

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/kling/general/advanced-custom-elements`	GET	application/json	application/json

查询参数

字段	类型	必填	默认值	描述
`pageNum`	int	可选	1	页码，取值范围 `[1, 1000]`
`pageSize`	int	可选	30	每页数据量，取值范围 `[1, 500]`

查询返回

json

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "element_id": "elem_lp_5f8c0a3b4d2e4f1c9a7b6e5d4c3b2a10",
      "element_name": "测试主体",
      "status": "succeed",
      "reference_type": "image_refer"
    }
  ]
}

查询官方主体（列表）

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/kling/general/advanced-presets-elements`	GET	application/json	application/json

查询参数

字段	类型	必填	默认值	描述
`pageNum`	int	可选	1	页码，取值范围 `[1, 1000]`
`pageSize`	int	可选	30	每页数据量，取值范围 `[1, 500]`

删除主体

网络协议	请求地址	请求方法	请求格式	响应格式
https	`/v1/kling/general/delete-elements`	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	鉴权信息

请求体参数

字段	类型	必填	默认值	描述
`element_id`	string	必填	无	要删除的主体 ID（创建时返回的 `element_id`）。非本人主体返回 `404`

请求示例

bash

curl -sS -X POST \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  "https://aiping.cn/api/v1/kling/general/delete-elements" \
  -d '{ "element_id": "elem_lp_5f8c0a3b4d2e4f1c9a7b6e5d4c3b2a10" }'

删除返回

json

{
  "code": 0,
  "message": "success",
  "data": {
    "element_id": "elem_lp_5f8c0a3b4d2e4f1c9a7b6e5d4c3b2a10",
    "status": "deleted"
  }
}

可灵 AI

MiniMax

MiniMax

可灵（Kling）AI 视频生成 API 文档（旧版归档） ​

目录 ​

1. 总览 ​

统一请求头 ​

核心说明 ​

视频能力接口 ​

1) 文生视频（Text2Video） ​

2) 图生视频（Image2Video） ​

3) 动作控制（Motion Control） ​

4) Omni / 多镜头（Omni Video） ​

5) 多图参考生视频（Multi-Image2Video） ​

6) 多模态视频编辑（Multi-Elements） ​

主体能力接口 ​

查询参数 ​

参数兼容 ​

关键约束 ​

返回结构（总览） ​

创建任务返回（示例） ​

单任务查询返回（示例） ​

列表查询返回（示例） ​

2. 文生视频（Text2Video） ​

请求头 ​

请求体参数 ​

multi_shot ​

shot_type ​

prompt ​

multi_prompt ​

negative_prompt ​

sound ​

cfg_scale ​

mode ​

camera_control ​

aspect_ratio ​

duration ​

watermark_info ​

callback_url ​

external_task_id ​

创建任务 ​

查询任务 ​

查询单个 ​

查询列表 ​

参数兼容 ​

接口约束 ​

请求示例 ​

返回结构示例 ​

查询任务返回示例（单个） ​

查询任务返回示例（列表） ​

注意事项 ​

3. 图生视频（Image2Video） ​

创建图生视频任务 ​

请求头 ​

请求体参数 ​

image ​

image_tail ​

multi_shot ​

shot_type ​

prompt ​

multi_prompt ​

negative_prompt ​

element_list ​

voice_list ​

sound ​

cfg_scale ​

mode ​

static_mask ​

dynamic_masks ​

camera_control ​

watermark_info ​

callback_url ​

external_task_id ​

关键约束 ​

查询任务 ​

参数兼容 ​

接口约束 ​

请求示例 ​

返回结构示例 ​

创建任务返回示例 ​

可灵（Kling）AI 视频生成 API 文档（旧版归档）

目录

1. 总览

统一请求头

核心说明

视频能力接口

1) 文生视频（Text2Video）

2) 图生视频（Image2Video）

3) 动作控制（Motion Control）

4) Omni / 多镜头（Omni Video）

5) 多图参考生视频（Multi-Image2Video）

6) 多模态视频编辑（Multi-Elements）

主体能力接口

查询参数

参数兼容

关键约束

返回结构（总览）

创建任务返回（示例）

单任务查询返回（示例）

列表查询返回（示例）

2. 文生视频（Text2Video）

请求头

请求体参数

multi_shot

shot_type

prompt

multi_prompt

negative_prompt

sound

cfg_scale

mode

camera_control

aspect_ratio

duration

watermark_info

callback_url

external_task_id

创建任务

查询任务

查询单个

查询列表

参数兼容

接口约束

请求示例

返回结构示例

查询任务返回示例（单个）

查询任务返回示例（列表）

注意事项

3. 图生视频（Image2Video）

创建图生视频任务

请求头

请求体参数

image

image_tail

multi_shot

shot_type

prompt

multi_prompt

negative_prompt

element_list

voice_list

sound

cfg_scale

mode

static_mask

dynamic_masks

camera_control

watermark_info

callback_url

external_task_id

关键约束

查询任务

参数兼容

接口约束

请求示例

返回结构示例

创建任务返回示例

查询任务返回示例（单个）

查询任务返回示例（列表）

注意事项