多模态视频编辑

PinduCloud 提供本页所列接口。请求使用 PinduCloud API Key；模型开通情况以当前账号的可用模型为准，参数按本页对应型号的协议组织。

POST 创建或管理请求可通过 model_name 选择账号已开通的可灵型号；未传时读取 model，两者都省略时使用 kling-v1。即使接口参数表未列出模型字段，也需确保账号已开通所选型号及对应能力。

初始化待编辑视频

POST https://video.pinducloud.com.cn/kling/v1/videos/multi-elements/init-selection

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

请求头

参数	类型	必填	默认值	说明
Content-Type	string	是	application/json	数据交换格式
Authorization	string	是		Bearer sk-your-pinducloud-token，使用 PinduCloud API Key

请求体

参数	类型	必填	默认值	说明
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://video.pinducloud.com.cn/kling/v1/videos/multi-elements/init-selection \
  --header 'Authorization: Bearer sk-your-pinducloud-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 字段
  "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://video.pinducloud.com.cn/kling/v1/videos/multi-elements/add-selection

请求头

参数	类型	必填	默认值	说明
Content-Type	string	是	application/json	数据交换格式
Authorization	string	是		Bearer sk-your-pinducloud-token，使用 PinduCloud API Key

请求体

参数	类型	必填	默认值	说明
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://video.pinducloud.com.cn/kling/v1/videos/multi-elements/add-selection \
  --header 'Authorization: Bearer sk-your-pinducloud-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "847570360458960960",
    "frame_index": 0,
    "points": [
      {
        "x": 0.7738498789346246,
        "y": 0.297142857142857
      }
    ]
  }'

响应示例

{
  "code": 0, // 错误码；错误详情见 message 字段
  "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://video.pinducloud.com.cn/kling/v1/videos/multi-elements/delete-selection

请求头

参数	类型	必填	默认值	说明
Content-Type	string	是	application/json	数据交换格式
Authorization	string	是		Bearer sk-your-pinducloud-token，使用 PinduCloud API Key

请求体

参数	类型	必填	默认值	说明
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://video.pinducloud.com.cn/kling/v1/videos/multi-elements/delete-selection \
  --header 'Authorization: Bearer sk-your-pinducloud-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "847570360458960960",
    "frame_index": 0,
    "points": [
      {
        "x": 0.7738498789346246,
        "y": 0.297142857142857
      }
    ]
  }'

响应示例

{
  "code": 0, // 错误码；错误详情见 message 字段
  "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://video.pinducloud.com.cn/kling/v1/videos/multi-elements/clear-selection

请求头

参数	类型	必填	默认值	说明
Content-Type	string	是	application/json	数据交换格式
Authorization	string	是		Bearer sk-your-pinducloud-token，使用 PinduCloud API Key

请求体

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

请求示例

curl --request POST \
  --url https://video.pinducloud.com.cn/kling/v1/videos/multi-elements/clear-selection \
  --header 'Authorization: Bearer sk-your-pinducloud-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "847570360458960960"
  }'

响应示例

{
  "code": 0, // 错误码；错误详情见 message 字段
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "status": 0, // 拒识码，非0为识别失败
    "session_id": "id", // 会话ID，会基于视频初始化任务生成，不会随编辑选区行为而改变，有效期24小时
    "final_unit_deduction": "string", // 任务服务原生积分信息；本站实际扣费以使用日志为准
  }
}

---

预览已选区视频

POST https://video.pinducloud.com.cn/kling/v1/videos/multi-elements/preview-selection

请求头

参数	类型	必填	默认值	说明
Content-Type	string	是	application/json	数据交换格式
Authorization	string	是		Bearer sk-your-pinducloud-token，使用 PinduCloud API Key

请求体

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

请求示例

curl --request POST \
  --url https://video.pinducloud.com.cn/kling/v1/videos/multi-elements/preview-selection \
  --header 'Authorization: Bearer sk-your-pinducloud-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "847570360458960960"
  }'

响应示例

{
  "code": 0, // 错误码；错误详情见 message 字段
  "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://video.pinducloud.com.cn/kling/v1/videos/multi-elements

请求头

参数	类型	必填	默认值	说明
Content-Type	string	是	application/json	数据交换格式
Authorization	string	是		Bearer sk-your-pinducloud-token，使用 PinduCloud API Key

请求体

参数	类型	必填	默认值	说明
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 编码后的字符串即可。 - 图片格式支持 .jpg / .jpeg / .png - 图片文件大小不能超过 10MB，图片宽高尺寸不小于 300px，图片宽高比要在 1:2.5 ~ 2.5:1 之间
image	string	是		图片 URL 或 Base64 字符串
prompt	string	是		正向文本提示词 - 用 <<<xxx>>> 的格式来特指某个视频或某张图片，如 <<<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	否		本次任务结果回调地址，发送给任务服务；是否投递及消息格式以实际服务行为为准 - 查询接口用于确认最终任务状态，请保留创建响应中的任务 ID
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": true }
}

请求示例

curl --request POST \
  --url https://video.pinducloud.com.cn/kling/v1/videos/multi-elements \
  --header 'Authorization: Bearer sk-your-pinducloud-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 字段
  "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://video.pinducloud.com.cn/kling/v1/videos/multi-elements/{id}

请求头

参数	类型	必填	默认值	说明
Content-Type	string	否	application/json	GET 查询不携带 JSON 请求体，可省略此头
Authorization	string	是		Bearer sk-your-pinducloud-token，使用 PinduCloud API Key

请求示例

curl --request GET \
  --url https://video.pinducloud.com.cn/kling/v1/videos/multi-elements/{task_id} \
  --header 'Authorization: Bearer sk-your-pinducloud-token'

响应示例

{
  "code": 0, // 错误码；错误详情见 message 字段
  "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（请注意，为下载地址可能有有效期，请及时转存）
          "watermark_url": "string", // 含水印视频下载URL，防盗链格式
          "duration": "string" // 视频总时长，单位s
        }
      ]
    },
    "watermark_info": {
      "enabled": true
    },
    "final_unit_deduction": "string", // 任务服务原生积分信息；本站实际扣费以使用日志为准
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
  }
}

---

查询任务（列表）

列表仅返回当前用户在该接口创建的任务。响应使用本站的 items 分页结构；每项 data 保留原生任务字段，task_id 为本站公开任务 ID。外层 created_at 使用 Unix 秒，原生 data 内的时间单位见字段注释。

查询参数

参数	类型	必填	默认值	说明
pageNum	integer	否	1	页码，范围 1–500
pageSize	integer	否	20	每页数量，范围 1–500
filter.model	string	否		按原版模型名称筛选
filter.task_ids	string	否		按公开任务 ID 筛选；重复传入参数指定多个 ID，最多 100 个

GET https://video.pinducloud.com.cn/kling/v1/videos/multi-elements

请求头

参数	类型	必填	默认值	说明
Content-Type	string	否	application/json	GET 查询不携带 JSON 请求体，可省略此头
Authorization	string	是		Bearer sk-your-pinducloud-token，使用 PinduCloud API Key

请求示例

curl --request GET \
  --url 'https://video.pinducloud.com.cn/kling/v1/videos/multi-elements?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer sk-your-pinducloud-token'

响应示例

{
  "items": [{
    "task_id": "task-example",
    "platform": "kling",
    "action": "multi_elements",
    "status": "SUCCESS",
    "progress": "100%",
    "fail_reason": "",
    "created_at": 1722769557,
    "data": {
      "code": 0,
      // 错误码；错误详情见 message 字段
      "message": "string",
      // 错误信息
      "request_id": "string",
      // 请求ID，系统生成，用于跟踪请求、排查问题
      "data": {
        "task_id": "task-example",
        // 任务ID，系统生成
        "task_status": "succeed",
        // 任务状态，枚举值：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（请注意，为下载地址可能有有效期，请及时转存）
            "watermark_url": "string",
            // 含水印视频下载URL，防盗链格式
            "duration": "string" // 视频总时长，单位s
          }]
        },
        "watermark_info": {
          "enabled": true
        },
        "final_unit_deduction": "string",
        // 任务服务原生积分信息；本站实际扣费以使用日志为准
        "created_at": 1722769557708,
        // 任务创建时间，Unix时间戳、单位ms
        "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
      }
    }
  }],
  "total": 1,
  "page_num": 1,
  "page_size": 30
}