多模态视频编辑

文档版本：v1.0.0 | 最后更新：2026-06-11

本平台已完整适配可灵 AI 系列官方视频生成接口，请求与响应均为透传，参数语义与官方一致。

初始化待编辑视频

POST https://platform.shuyanai.com/kling/v1/videos/multi-elements/init-selection

使用"多模态视频编辑"功能时，需先对原始视频进行初始化处理。其中，在替换或删除现有视频中的元素时，需先标记视频中相关元素。

请求头

参数	类型	必填	默认值	说明
`Content-Type`	string	是	application/json	数据交换格式
`Authorization`	string	是		鉴权信息，参考接口鉴权

请求体

参数	类型	必填	默认值	说明
`video_id`	string	否		视频 ID，从历史作品中选择待编辑的视频，仅支持 30 天内生成的视频作品 - 仅支持 30 天内生成的视频作品 - 仅支持时长 ≥2 秒且 ≤5 秒，或 ≥7 秒且 ≤10 秒的视频 - 与 video_url 参数相关，不能同时为空，也不能同时有值
`video_url`	string	否		获取视频的 URL，上传时传视频下载链接，编辑选区时传接口返回的视频 URL - 仅支持 MP4 和 MOV 格式 - 仅支持时长 ≥2 秒且 ≤5 秒，或 ≥7 秒且 ≤10 秒的视频 - 视频宽高尺寸需介于 720px（含）和 2160px（含）之间 - 仅支持上传 24、30 或 60fps 的视频 - 与 video_id 参数相关，不能同时为空，也不能同时有值

请求示例

curl --request POST \
  --url https://platform.shuyanai.com/kling/v1/videos/multi-elements/init-selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "video_id": "",
    "video_url": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/animals-output-5s.mp4"
  }'

响应示例

{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "status": 0, // 拒识码，非0为识别失败
    "session_id": "id", // 会话ID，会基于视频初始化任务生成，不会随编辑选区行为而改变，有效期24小时
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "fps": 30.0, // 解析后视频的帧数，在获取选区展示视频时需携参
    "original_duration": 1000, // 解析后视频的时长，在创建任务时需携参
    "width": 720, // 解析后视频的宽，暂无作用
    "height": 1280, // 解析后视频的高，暂无作用
    "total_frame": 300, // 解析后视频的总帧数，在创建任务时需携参
    "normalized_video": "url" // 初始化后的视频URL
}

增加视频选区

POST https://platform.shuyanai.com/kling/v1/videos/multi-elements/add-selection

请求头

参数	类型	必填	默认值	说明
`Content-Type`	string	是	application/json	数据交换格式
`Authorization`	string	是		鉴权信息，参考接口鉴权

请求体

参数	类型	必填	说明
`session_id`	string	是	会话 ID，会基于视频初始化任务生成，不会随编辑选区行为而改变
`frame_index`	int	是	帧号 - 最多支持添加 10 个标记帧，即最多基于 10 帧标记视频选区 - 1 次仅支持标记 1 帧
`points`	array	是	点选坐标，用 x、y 表示 - 取值范围：[0, 1]，用百分比表示；[0, 1] 代表画面左上角 - 支持同时增加多个标记点，某一帧最多可标记 10 个点
`x`	float	是	X 坐标 [0-1]
`y`	float	是	Y 坐标 [0-1]

请求示例

curl --request POST \
  --url https://platform.shuyanai.com/kling/v1/videos/multi-elements/add-selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "847570360458960960",
    "frame_index": 0,
    "points": [
      {
        "x": 0.7738498789346246,
        "y": 0.297142857142857
      }
    ]
  }'

响应示例

{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "status": 0, // 拒识码，非0为识别失败
    "session_id": "id", // 会话ID，会基于视频初始化任务生成，不会随编辑选区行为而改变，有效期24小时
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "res": {
      "frame_index": 0,
      "rle_mask_list": [{
        "object_id": 0,
        "rle_mask": {
          "size": [720, 1280],
          "counts": "string"
        },
        "png_mask": {
          "size": [720, 1280],
          "base64": "string"
        }
      }]
    }
  }
}

删减视频选区

POST https://platform.shuyanai.com/kling/v1/videos/multi-elements/delete-selection

请求头

参数	类型	必填	默认值	说明
`Content-Type`	string	是	application/json	数据交换格式
`Authorization`	string	是		鉴权信息，参考接口鉴权

请求体

参数	类型	必填	说明
`session_id`	string	是	会话 ID，会基于视频初始化任务生成，不会随编辑选区行为而改变
`frame_index`	int	是	帧号
`points`	array	是	点选坐标，用 x、y 表示 - 取值范围：[0, 1]，用百分比表示；[0, 1] 代表画面左上角 - 支持同时增加多个标记点 - 坐标点需与增加视频选区时完全一致
`x`	float	是	X 坐标 [0-1]
`y`	float	是	Y 坐标 [0-1]

请求示例

curl --request POST \
  --url https://platform.shuyanai.com/kling/v1/videos/multi-elements/delete-selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "847570360458960960",
    "frame_index": 0,
    "points": [
      {
        "x": 0.7738498789346246,
        "y": 0.297142857142857
      }
    ]
  }'

响应示例

{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "status": 0, // 拒识码，非0为识别失败
    "session_id": "id", // 会话ID，会基于视频初始化任务生成，不会随编辑选区行为而改变，有效期24小时
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "res": {
      "frame_index": 0,
      "rle_mask_list": [{
        "object_id": 0,
        "rle_mask": {
          "size": [720, 1280],
          "counts": "string"
        },
        "png_mask": {
          "size": [720, 1280],
          "base64": "string"
        }
      }]
    }
  }
}

清除视频选区

POST https://platform.shuyanai.com/kling/v1/videos/multi-elements/clear-selection

请求头

参数	类型	必填	默认值	说明
`Content-Type`	string	是	application/json	数据交换格式
`Authorization`	string	是		鉴权信息，参考接口鉴权

请求体

参数	类型	必填	默认值	说明
`session_id`	string	是		会话 ID，会基于视频初始化任务生成，不会随编辑选区行为而改变

请求示例

curl --request POST \
  --url https://platform.shuyanai.com/kling/v1/videos/multi-elements/clear-selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "847570360458960960"
  }'

响应示例

{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "status": 0, // 拒识码，非0为识别失败
    "session_id": "id", // 会话ID，会基于视频初始化任务生成，不会随编辑选区行为而改变，有效期24小时
    "final_unit_deduction": "string", // 任务最终扣减积分数值
  }
}

预览已选区视频

POST https://platform.shuyanai.com/kling/v1/videos/multi-elements/preview-selection

请求头

参数	类型	必填	默认值	说明
`Content-Type`	string	是	application/json	数据交换格式
`Authorization`	string	是		鉴权信息，参考接口鉴权

请求体

参数	类型	必填	默认值	说明
`session_id`	string	是		会话 ID，会基于视频初始化任务生成，不会随编辑选区行为而改变

请求示例

curl --request POST \
  --url https://platform.shuyanai.com/kling/v1/videos/multi-elements/preview-selection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "847570360458960960"
  }'

响应示例

{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "status": 0, // 拒识码，非0为识别失败
    "session_id": "id", // 会话ID，会基于视频初始化任务生成，不会随编辑选区行为而改变，有效期24小时
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "res": {
      "video": "url", // 含mask的视频
      "video_cover": "url", // 含mask的视频的封面
      "tracking_output": "url" // 图像分割结果中，每一帧mask结果
    }
  }
}

创建任务

POST https://platform.shuyanai.com/kling/v1/videos/multi-elements

请求头

参数	类型	必填	默认值	说明
`Content-Type`	string	是	application/json	数据交换格式
`Authorization`	string	是		鉴权信息，参考接口鉴权

请求体

参数	类型	必填	默认值	说明
`model_name`	string	否	kling-v1-6	模型名称可选值: `kling-v1-6`
`session_id`	string	是		会话 ID，会基于视频初始化任务生成，不会随编辑选区行为而改变
`edit_mode`	string	是		操作类型可选值: `addition`, `swap`, `removal` - addition：增加元素 - swap：替换元素 - removal：删除元素
`image_list`	array	否		裁剪后的参考图像 - 增加视频元素时：当前参数必填，可上传 1~2 张图片 - 编辑视频元素时：当前参数必填，仅可上传 1 张图片 - 删除视频元素时，当前参数无需填写 - 用 key:value 承载，如下： - API 端无裁剪逻辑，请直接上传已选主体后的图片 - 支持传入图片 Base64 编码或图片 URL（确保可访问） - 注意：若您使用 Base64 方式，请不要在 Base64 编码字符串前添加任何前缀（如 `data:image/png;base64,`），直接传递 Base64 编码后的字符串即可。 - 正确的 Base64 编码参数： - 错误的 Base64 编码参数（包含 data: 前缀）： - 图片格式支持 .jpg / .jpeg / .png - 图片文件大小不能超过 10MB，图片宽高尺寸不小于 300px，图片宽高比要在 1:2.5 ~ 2.5:1 之间
`image`	string	是		图片 URL 或 Base64 字符串
`prompt`	string	是		正向文本提示词 - 用 <<>> 的格式来特指某个视频或某张图片，如 <<<video_1>>>、<<<image_1>>> - 为保证效果，提示词中需包含视频编辑所需的视频和图片（如有） - 不能超过 2500 个字符推荐的 Prompt 模板：增加元素： - 中文：基于<<<video_1>>>中的原始内容，以自然生动的方式，将<<<image_1>>>中的【】，融入<<<video_1>>>的【】 - 英文：Using the context of <<<video_1>>>, seamlessly add [x] from <<<image_1>>> 替换元素： - 中文：使用<<<image_1>>>中的【】，替换<<<video_1>>>中的【】 - 英文：swap [x] from <<<image_1>>> for [x] from <<<video_1>>> 删除元素： - 中文：删除<<<video_1>>>中的【】 - 英文：Delete [x] from <<<video_1>>> 注：中文的【】，英文的 [x]，是需要用户填写的部分
`negative_prompt`	string	否		负向文本提示词 - 不能超过 2500 个字符
`mode`	string	否	std	生成视频的模式可选值: `std`, `pro` - std：标准模式（标准），基础模式，性价比高 - pro：专家模式（高品质），高表现模式，生成视频质量更佳
`duration`	string	否	5	生成视频时长，单位 s 可选值: `5`, `10` - 支持且仅支持生成 5s 和 10s 的视频 - 如生成 5s 时长视频，输入视频时长需 ≥2s 且 ≤5s - 如生成 10s 时长视频，输入视频时长需 ≥7s 且 ≤10s
`watermark_info`	object	否		是否同时生成含水印的结果 - 通过enabled参数定义，具体格式如下： - true 为生成，false 为不生成 - 暂不支持自定义水印
`callback_url`	string	否		本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知 - 具体通知的消息 schema 见 Callback 协议
`external_task_id`	string	否		自定义任务 ID - 用户自定义任务 ID，传入不会覆盖系统生成的任务 ID，但支持通过该 ID 进行任务查询 - 请注意，单用户下需要保证唯一性
参数格式说明

image_list

"image_list":[
  { "image":"image_url" },
  { "image":"image_url" }
]

iVBORw0KGgoAAAANSUhEUgAAAAUA...

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...

watermark_info

"watermark_info": { "enabled": boolean }

请求示例

curl --request POST \
  --url https://platform.shuyanai.com/kling/v1/videos/multi-elements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v1-6",
    "session_id": "847570360458960960",
    "edit_mode": "removal",
    "image_list": [],
    "prompt": "删除<<<video_1>>>中的【小鸡】",
    "negative_prompt": "",
    "mode": "std",
    "duration": "5",
    "callback_url": "",
    "external_task_id": ""
  }'

响应示例

{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "task_id": "string", // 任务ID，系统生成
    "task_status": "string", // 任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "task_info": {
      "external_task_id": "string" // 客户自定义任务ID
    },
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
  }
}

查询任务（单个）

GET https://platform.shuyanai.com/kling/v1/videos/multi-elements/{id}

请求头

参数	类型	必填	默认值	说明
`Content-Type`	string	是	application/json	数据交换格式
`Authorization`	string	是		鉴权信息，参考接口鉴权

请求示例

curl --request GET \
  --url https://platform.shuyanai.com/kling/v1/videos/multi-elements/{task_id} \
  --header 'Authorization: Bearer <token>'

响应示例

{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "task_id": "string", // 任务ID，系统生成
    "task_status": "string", // 任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "task_status_msg": "string", // 任务状态信息，当任务失败时展示失败原因（如触发平台的内容风控等）
    "task_info": { // 任务创建时的参数信息
      "external_task_id": "string" // 客户自定义任务ID
    },
    "task_result": {
      "videos": [
        {
          "id": "string", // 生成的视频ID；全局唯一
          "session_id": "id", // 会话ID，会基于视频初始化任务生成，不会随编辑选区行为而改变，有效期24小时
          "url": "string", // 生成视频的URL（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
          "watermark_url": "string", // 含水印视频下载URL，防盗链格式
          "duration": "string" // 视频总时长，单位s
        }
      ]
    },
    "watermark_info": {
      "enabled": boolean
    },
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
  }
}

查询任务（列表）

GET https://platform.shuyanai.com/kling/v1/videos/multi-elements

请求头

参数	类型	必填	默认值	说明
`Content-Type`	string	是	application/json	数据交换格式
`Authorization`	string	是		鉴权信息，参考接口鉴权

请求示例

curl --request GET \
  --url 'https://platform.shuyanai.com/kling/v1/videos/multi-elements?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'

响应示例

{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": [
    {
      "task_id": "string", // 任务ID，系统生成
      "task_status": "string", // 任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
      "task_status_msg": "string", // 任务状态信息，当任务失败时展示失败原因（如触发平台的内容风控等）
      "task_info": { // 任务创建时的参数信息
        "external_task_id": "string" // 客户自定义任务ID
      },
      "task_result": {
        "videos": [
          {
            "id": "string", // 生成的视频ID；全局唯一
            "session_id": "id", // 会话ID，会基于视频初始化任务生成，不会随编辑选区行为而改变，有效期24小时
            "url": "string", // 生成视频的URL（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
            "watermark_url": "string", // 含水印视频下载URL，防盗链格式
            "duration": "string" // 视频总时长，单位s
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "final_unit_deduction": "string", // 任务最终扣减积分数值
      "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
      "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
    }
  ]
}

06-多模态视频编辑

多模态视频编辑

初始化待编辑视频

请求头

请求体

请求示例

响应示例

增加视频选区

请求头

请求体

请求示例

响应示例

删减视频选区

请求头

请求体

请求示例

响应示例

清除视频选区

请求头

请求体

请求示例

响应示例

预览已选区视频

请求头

请求体

请求示例

响应示例

创建任务

请求头

请求体

请求示例

响应示例

查询任务（单个）

请求头

请求示例

响应示例

查询任务（列表）

请求头

请求示例

响应示例