Kling
Endpoint: POST https://vod.intl.tencentcloudapi.comAction: CreateAigcVideoTask
Kling 是功能最全面的视频生成模型之一,支持文生视频、首帧 / 首尾帧生视频,以及图片、视频的多模态参考生成。最新的 Kling 4(4.0 / 4.0-Omni / 4.0-Flash)支持单条最长 30 秒 原生直出,详见独立接口文档。3.0-Omni / O1 支持多镜头(智能分镜)与视频编辑,并提供动作控制、口型同步、数字人、自定义音色等扩展能力,可同时生成音频。
基本信息
| 项目 | 值 |
|---|---|
| ModelName | Kling |
| ModelVersion | 4.0 / 4.0-Omni / 4.0-Flash / 3.0 / 3.0-turbo / 3.0-Omni / O1 / 2.6 / 2.5 / 2.1 / 2.0 / 1.6 |
| 默认值 | ModelVersion=3.0 / Resolution=1080P |
| 支持解除护栏 | 支持 |
各版本支持规格
| 版本 | 分辨率 | 比例 | 时长 |
|---|---|---|---|
| 通用 | 480P / 720P / 1080P / 2K / 4K | — | — |
4.0 / 4.0-Omni | 720P / 1080P / 2K(超分)/ 4K(超分) | 21:9 / 16:9 / 9:16 / 1:1 | 3–30 秒 |
4.0-Flash | 720P / 1080P(超分)/ 2K(超分)/ 4K(超分) | 21:9 / 16:9 / 9:16 / 1:1 | 3–20 秒 |
3.0-turbo | 720P / 1080P / 2K / 4K | 文本生成 16:9 / 9:16 / 1:1 | 3–15 秒 |
4.0-Flash 不是「更便宜的 4.0」
Flash 的能力有明确裁剪:最长 20 秒(4.0 为 30 秒)、不支持尾帧与中间帧(图生只接受单张首帧),且原生只到 720P(1080P 及以上由超分补齐)。它支持全能参考生成,但主体(SubjectInfos)与音色仍只有 4.0-Omni 有。照 4.0 的示例把版本号换成 4.0-Flash 会报错,详见版本怎么选。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
ModelName | 必填 | String | 固定值 Kling |
ModelVersion | 可选 | String | 4.0 / 4.0-Omni / 4.0-Flash / 3.0 / 3.0-turbo / 3.0-Omni / O1 / 2.6 / 2.5 / 2.1 / 2.0 / 1.6 |
Prompt | 必填 | String | 生成提示词 |
FileInfos.N | 可选 | Array | 参考输入。Usage 为 FirstFrame(首帧)或 Reference(参考) |
OutputConfig.Resolution | 可选 | String | 480P / 720P / 1080P / 2K / 4K |
OutputConfig.Duration | 可选 | Integer | 视频时长(秒) |
OutputConfig.AspectRatio | 可选 | String | 16:9 / 9:16 / 1:1 等 |
ExtInfo | 可选 | String | 在 2 中以 JSON 编码。传递下方高级功能(动作控制、口型同步、数字人)的详细参数。 |
FirstFrameFileId / LastFrameUrl | 可选 | String | 用于首 / 尾帧生成。将参考帧指定为 FileInfos 的 Usage=FirstFrame,将尾帧指定为 LastFrameUrl/LastFrameFileId(2.1 版本必须填 1080P) |
OutputConfig.InputComplianceCheck | 可选 | String | 显式传递 Disabled 则解除输入审核。使用前请咨询商务负责人 |
OutputConfig.OutputComplianceCheck | 可选 | String | 显式传递 Disabled 则解除输出审核。使用前请咨询商务负责人 |
请求示例
{
"SubAppId": 123456789,
"ModelName": "Kling",
"ModelVersion": "3.0",
"Prompt": "a calm sunset over the ocean, cinematic",
"OutputConfig": {
"Resolution": "1080P",
"Duration": 5,
"AspectRatio": "16:9",
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}响应示例
{
"AigcVideoTask": {
"Status": "FINISH",
"ErrCode": 0,
"Progress": 100,
"Output": {
"FileInfos": [
{
"FileUrl": "http://<host>.vod2.myqcloud.com/.../aigcVideoGenFile.mp4",
"ExpireTime": "2026-08-01T10:29:48Z",
"MetaData": {
"Width": 1920,
"Height": 1080,
"Duration": 5.07,
"Container": "mov,mp4,m4a",
"Bitrate": 9494850
}
}
]
}
}
}参考数量限制(以 Kling 为准)
参考图片、参考对象、参考视频的数量会相互影响。
| 条件 | 限制 |
|---|---|
| 有参考视频 | 参考图片数 + 参考对象数合计 4 以下 |
| 无参考视频 | 参考图片数 + 参考对象数合计 7 以下 |
| 使用尾帧 | 参考图片最多 2 张 |
必须一并确认 ErrCode
请同时确认完成响应中的 Status="FINISH" 与 ErrCode=0。
特殊设置
解除护栏
可分别设置输入与输出审核。
要使用护栏解除参数,请先联系商务负责人确认使用权限。即使在支持的引擎中,也只有显式传递该参数时才会应用护栏解除。省略参数则不会解除。
| 参数 | 解除值 | 适用对象 |
|---|---|---|
OutputConfig.InputComplianceCheck | Disabled | 解除输入审核 |
OutputConfig.OutputComplianceCheck | Disabled | 解除输出审核 |
将以下设置合并到现有生成请求中。要同时解除输入与输出审核,请一并传递两个字段。
{
"OutputConfig": {
"InputComplianceCheck": "Disabled",
"OutputComplianceCheck": "Disabled"
}
}首 / 尾帧生成(First / Last Frame)
给定起始帧与结束帧图片,会生成将两帧之间自然衔接的视频。首帧通过 FileInfos 以 Usage=FirstFrame 指定,尾帧通过 LastFrameUrl(或 LastFrameFileId)指定。
{
"SubAppId": 123456789,
"ModelName": "Kling",
"ModelVersion": "2.1",
"Prompt": "camera slowly pushes in, cinematic",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Usage": "FirstFrame",
"Url": "https://<cdn>/first.jpg"
}
],
"LastFrameUrl": "https://<cdn>/last.jpg",
"OutputConfig": {
"Resolution": "1080P",
"Duration": 5,
"AspectRatio": "16:9",
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}2.1 版本必须填 1080P
Kling 2.1 的首 / 尾帧生成使用 OutputConfig.Resolution=1080P。
动作控制(motion_control)
将参考视频的动作套用到人物图片上生成新视频。用 SceneType=motion_control 指定,并将参考视频与人物图片通过 FileInfos 一并指定。版本使用 3.0(新版)或 2.6(标准入口)。
{
"SubAppId": 123456789,
"ModelName": "Kling",
"ModelVersion": "2.6",
"SceneType": "motion_control",
"Prompt": "用参考视频的动作生成新视频",
"FileInfos": [
{
"Type": "Url",
"Category": "Video",
"Url": "https://<cdn>/ref_motion.mp4"
},
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cdn>/person.webp"
}
],
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"keep_original_sound\\\":\\\"no\\\",\\\"character_orientation\\\":\\\"video\\\"}\"}",
"OutputConfig": {
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}ExtInfo 主要参数
keep_original_sound:yes(保留原声)/no。character_orientation:image(图片人物方向,参考视频 ≤10 秒)/video(视频人物方向,参考视频 ≤30 秒)。
口型同步(lip_sync)
让人物说话的素材与音频对齐,同步口型。先用 DescribeAigcFaceInfo 获取 SessionId 与面部信息,再用 SceneType=lip_sync 调用。音频与视频信息都通过 ExtInfo 传递,FileInfos 留空。
{
"SubAppId": 123456789,
"ModelName": "Kling",
"ModelVersion": "2.6",
"SceneType": "lip_sync",
"Prompt": "lip sync",
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"session_id\\\":\\\"845736590818832460\\\",\\\"face_choose\\\":[{\\\"face_id\\\":0,\\\"sound_file\\\":\\\"https://<cdn>/audio.mp3\\\",\\\"sound_start_time\\\":0,\\\"sound_end_time\\\":5000,\\\"sound_insert_time\\\":0,\\\"sound_volume\\\":2,\\\"original_audio_volume\\\":0}]}\"}",
"OutputConfig": {
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}两阶段流程
1 阶段:用 DescribeAigcFaceInfo 获取 session_id 与 face_id。2 阶段:调用 lip_sync 时 FileInfos 留空,并在 face_choose 数组中指定 face_id / sound_file、区间(ms)、音量。
数字人(avatar_i2v)
用人物图片 1 张 与音频生成说话或活动的人物视频。用 SceneType=avatar_i2v 指定,人物图片用 FileInfos 指定,音频用 ExtInfo 的 sound_file 指定。
{
"SubAppId": 123456789,
"ModelName": "Kling",
"ModelVersion": "2.6",
"SceneType": "avatar_i2v",
"Prompt": "talking naturally",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cdn>/portrait.png"
}
],
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"sound_file\\\":\\\"https://<cdn>/audio.mp3\\\"}\"}",
"OutputConfig": {
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}音频输入规则
输入 sound_file(mp3/wav/m4a/aac,最长 5MB,2~300 秒)或 audio_id 其中之一。
图片 / 视频参考(image_list / video_list)
可在提示词内用 <<<...>>> 标记指定参考列表中的条目。图片列表与视频列表通过 FileInfos 传递,并用 Category 区分种类。顺序遵循 FileInfos 数组的顺序。
| 标记 | 对象 |
|---|---|
<<<image_1>>> / <<<image_2>>> ... | Category=Image 条目 |
<<<video_1>>> / <<<video_2>>> ... | Category=Video 条目 |
<<<element_1>>> / <<<element_2>>> ... | 通过 SubjectInfos 或 element_list 传递的参考对象 |
{
"SubAppId": 123456789,
"ModelName": "Kling",
"ModelVersion": "3.0-Omni",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/f0.jpeg",
"Usage": "Reference"
},
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/f1.jpeg",
"Usage": "Reference"
},
{
"Type": "Url",
"Category": "Video",
"Url": "https://<cos>/1.mp4",
"Usage": "Reference"
}
],
"Prompt": "let <<<image_1>>> hold hands with <<<image_2>>> in the environment of <<<video_1>>>",
"OutputConfig": {
"Duration": 8,
"Resolution": "1080P",
"AspectRatio": "16:9",
"AudioGeneration": "Disabled",
"StorageMode": "Temporary"
},
"SessionContext": "job-001"
}ReferenceType:参考视频的性质
为 Category=Video 时用 ReferenceType 指定用途。适用于 GV、Kling、PixVerse。
| 值 | 含义 |
|---|---|
feature | 特征参考。仅参考视频的风格或动作特征 |
base | 编辑对象。修改该视频本身 |
参考数量限制
| 条件 | 限制 |
|---|---|
| 有参考视频 | 参考图片数 + 参考对象数合计 4 以下 |
| 无参考视频 | 参考图片数 + 参考对象数合计 7 以下 |
| 使用尾帧 | 参考图片最多 2 张 |
已注册的参考对象(SubjectInfos)
在多个人物或物体需跨多个任务复用时使用。预先创建参考对象后会签发 ID,生成请求中引用该 ID。Kling 仅支持已注册的参考对象。
参考对象创建 API
| API | 说明 |
|---|---|
CreateAigcAdvancedCustomElement | 推荐。异步。图片与视频均支持。响应返回 TaskId,用 DescribeTaskDetail 查询 |
CreateAigcCustomElement | 旧版。同步。仅图片。仅为向下兼容保留 |
DescribeAigcAdvancedCustomElements | 查询已创建的参考对象列表 |
DeleteAigcAdvancedCustomElement | 删除参考对象 |
若已开通海外参考对象库,向 CreateAigcAdvancedCustomElement 传入 DisableModeration=True 时会使用海外参考对象库。
角色注册
将参考对象 ID 放入 SubjectInfos.N.Id,并在提示词中以 <<<element_N>>> 指定。Name 为可选项,即使附加,提示词中的参考标记也相同。
{
"SubAppId": 123456789,
"ModelName": "Kling",
"ModelVersion": "3.0-Omni",
"SubjectInfos": [
{
"Id": "858477278396170315"
},
{
"Id": "858477602846711835"
}
],
"Prompt": "let <<<element_1>>> hold hands with <<<element_2>>> and spin around",
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "1080P"
},
"SessionContext": "job-001"
}已注册的参考对象(旧版,ExtInfo)
也可以通过 ExtInfo 的 element_list 实现同样效果,但新实现建议使用 SubjectInfos。
{
"SubAppId": 123456789,
"ModelName": "Kling",
"ModelVersion": "3.0-Omni",
"Prompt": "let <<<element_1>>> hold hands with <<<element_2>>> and spin around",
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "1080P"
},
"ExtInfo": "{\"AdditionalParameters\": \"{\\\"element_list\\\": [{\\\"element_id\\\": 858477278396170315}, {\\\"element_id\\\": 858477602846711835}]}\"}",
"SessionContext": "job-001"
}智能分镜(multi_shot)
Kling 3.0 系列可用提示词中的一句话自动构成多个镜头,也可直接指定逐镜脚本。通过 ExtInfo 的 AdditionalParameters 传递。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
multi_shot | Bool | false | 为 true 时为多镜头模式。此时顶层 Prompt 会被忽略 |
shot_type | String | 空值 | customize(直接指定)/ intelligence(自动)。为 multi_shot=true 时必填 |
multi_prompt | Array | 空值 | 逐镜信息。最多 6 个,最少 1 个 |
multi_prompt 条目构成:
| 字段 | 说明 |
|---|---|
index | 镜头编号 |
prompt | 镜头脚本。最多 512 字符 |
duration | 镜头时长(秒)。1 以上,且不超过总时长 |
镜头时长之和必须等于总时长
请将各镜头的 duration 之和指定为与 OutputConfig.Duration 相同。
customize:直接指定镜头
{
"SubAppId": 123456789,
"ModelName": "Kling",
"ModelVersion": "3.0",
"Prompt": "not used when multi_shot is on",
"OutputConfig": {
"StorageMode": "Temporary",
"Resolution": "1080P",
"Duration": 5,
"AspectRatio": "16:9",
"AudioGeneration": "Enabled"
},
"ExtInfo": "{\"AdditionalParameters\": \"{\\\"multi_shot\\\": true, \\\"shot_type\\\": \\\"customize\\\", \\\"multi_prompt\\\": [{\\\"index\\\": 1, \\\"prompt\\\": \\\"A person sitting on a park bench, sunlight filtering through trees\\\", \\\"duration\\\": 2}, {\\\"index\\\": 2, \\\"prompt\\\": \\\"A car speeding down a rainy street, headlights glowing. Dynamic angle, focus on motion.\\\", \\\"duration\\\": 3}]}\"}",
"SessionContext": "job-001"
}以下是用 Python 生成 ExtInfo 的示例。
import json
kl_ext_info = {
"multi_shot": True,
"shot_type": "customize",
"multi_prompt": [
{"index": 1, "prompt": "A person sitting on a park bench, sunlight filtering through trees", "duration": 2},
{"index": 2, "prompt": "A car speeding down a rainy street, headlights glowing. Dynamic angle, focus on motion.", "duration": 3},
],
}
inner = json.dumps(kl_ext_info, ensure_ascii=False)
ext_info = json.dumps({"AdditionalParameters": inner}, ensure_ascii=False)intelligence:自动分割
为 shot_type=intelligence 时 multi_prompt 会被忽略,模型以 Prompt 为基准构成镜头。
自定义音色(voice_id)
生成含语音内容时指定声音。支持版本为 2.6 / 3.0 / 3.0-Omni,其中 2.6 仅在 1080P 中可指定音色 ID。
音色需通过单独的 API 预先创建,经 ExtInfo 的 voice_list 传递后,在提示词中以 <<<voice_N>>> 指定。
{
"SubAppId": 123456789,
"ModelName": "Kling",
"ModelVersion": "2.6",
"FileInfos": [
{
"Type": "Url",
"Category": "Image",
"Url": "https://<cos>/portrait.png",
"Usage": "FirstFrame"
}
],
"Prompt": "the person in the image says loudly with <<<voice_1>>>: I want to be free",
"OutputConfig": {
"StorageMode": "Permanent",
"Duration": 5,
"Resolution": "1080P",
"AspectRatio": "9:16",
"AudioGeneration": "Enabled"
},
"ExtInfo": "{\"AdditionalParameters\": \"{\\\"voice_list\\\": [{\\\"voice_id\\\": 869048851066937391}]}\"}",
"SessionContext": "job-001"
}创建自定义音色(CreateAigcCustomVoice)
上面 voice_list 里的 voice_id 不是现成的,需要先用 CreateAigcCustomVoice 接口,基于一段参考音频(或含音频的视频)创建出自己的音色,拿到 VoiceId 后再填进生成请求。
Endpoint: POST https://vod.intl.tencentcloudapi.comAction: CreateAigcCustomVoice
说明:
- 当前自定义音色需由调用方自行管理(创建、记录
VoiceId、复用)。 CreateAigcCustomVoice是异步接口,返回TaskId;请保存该TaskId,再用DescribeTaskDetail轮询创建结果。- 参考音频建议使用清晰、无明显噪声的人声素材;取值口径可参考可灵平台文档。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 必填 | Integer | 点播应用 ID |
VoiceName | 必填 | String | 音色名称,便于后续识别与管理 |
VoiceUrl | 可选 | String | 参考音频 / 视频的 URL(与 VideoId 二选一) |
VideoId | 可选 | String | 点播媒资 ID,作为参考音源(与 VoiceUrl 二选一) |
SessionId | 可选 | String | 请求去重用的会话 ID |
SessionContext | 可选 | String | 透传给回调的来源上下文 |
TasksPriority | 可选 | Integer | 任务优先级 |
请求示例
{
"SubAppId": 221073,
"VoiceName": "myVoice",
"VoiceUrl": "https://cg-sdk-1258344699.cos.ap-nanjing.myqcloud.com/BackendBeauty/testcase/input.mp4",
"VideoId": null,
"SessionId": null,
"SessionContext": null,
"TasksPriority": null
}代码示例
# -*- coding: utf-8 -*-
import os
import json
from tencentcloud.common.common_client import CommonClient
from tencentcloud.common import credential
from tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKException
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
try:
# 密钥从环境变量读取,避免硬编码:需提前设置 TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY
# 密钥可前往控制台 https://console.tencentcloud.com/cam/capi 获取
cred = credential.Credential(os.getenv("TENCENTCLOUD_SECRET_ID"), os.getenv("TENCENTCLOUD_SECRET_KEY"))
httpProfile = HttpProfile()
httpProfile.endpoint = "vod.intl.tencentcloudapi.com"
clientProfile = ClientProfile()
clientProfile.httpProfile = httpProfile
params = "{\"SubAppId\":221073,\"VoiceName\":\"myVoice\",\"VoiceUrl\":\"https://cg-sdk-1258344699.cos.ap-nanjing.myqcloud.com/BackendBeauty/testcase/input.mp4\"}"
common_client = CommonClient("vod", "2018-07-17", cred, "", profile=clientProfile)
print(common_client.call_json("CreateAigcCustomVoice", json.loads(params)))
except TencentCloudSDKException as err:
print(err)package main
import (
"os"
"fmt"
"github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common"
"github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/errors"
"github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/profile"
vod "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/vod/v20180717"
)
func main() {
// 密钥从环境变量读取:需提前设置 TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY
credential := common.NewCredential(
os.Getenv("TENCENTCLOUD_SECRET_ID"),
os.Getenv("TENCENTCLOUD_SECRET_KEY"),
)
cpf := profile.NewClientProfile()
cpf.HttpProfile.Endpoint = "vod.intl.tencentcloudapi.com"
client, _ := vod.NewClient(credential, "", cpf)
request := vod.NewCreateAigcCustomVoiceRequest()
request.SubAppId = common.Uint64Ptr(221073)
request.VoiceName = common.StringPtr("myVoice")
request.VoiceUrl = common.StringPtr("https://cg-sdk-1258344699.cos.ap-nanjing.myqcloud.com/BackendBeauty/testcase/input.mp4")
response, err := client.CreateAigcCustomVoice(request)
if _, ok := err.(*errors.TencentCloudSDKError); ok {
fmt.Printf("An API error has returned: %s", err)
return
}
if err != nil {
panic(err)
}
fmt.Printf("%s", response.ToJsonString())
}返回示例
接口立即返回 TaskId,用于后续查询创建进度:
{
"Response": {
"RequestId": "424661ad-4e48-4d42-8f31-5066cae7157c",
"TaskId": "221073-CreateAigcCustomVoice-77226813bc1038c2720a63c6962b16e6t"
}
}查询创建结果(DescribeTaskDetail)
用上一步返回的 TaskId 调用 DescribeTaskDetail 轮询,直到 Status=FINISH;音色 ID 位于 CreateAigcCustomVoiceTask.Output.InfoList[].VoiceId。
{
"Response": {
"CreateAigcCustomVoiceTask": {
"ErrCode": 0,
"Input": {
"VideoId": "",
"VoiceName": "myVoice",
"VoiceUrl": "https://cg-sdk-1258344699.cos.ap-nanjing.myqcloud.com/BackendBeauty/testcase/input.mp4"
},
"Output": {
"InfoList": [
{
"VoiceId": "858488987974373383",
"VoiceInfo": "{\"voice_id\":\"858488987974373383\",\"voice_name\":\"myVoice\",\"trial_url\":\"https://.../xxx.quality.wav\",\"owned_by\":\"826925436873121851\",\"status\":\"succeed\"}"
}
]
},
"Progress": 100,
"Status": "FINISH",
"TaskId": "221073-CreateAigcCustomVoice-77226813bc1038c2720a63c6962b16e6t"
},
"TaskType": "CreateAigcCustomVoice",
"Status": "FINISH",
"RequestId": "a6676cfe-865b-4564-b614-ea40ce126f46"
}
}拿到 VoiceId(如 858488987974373383)后,将其作为前述 ExtInfo → voice_list → voice_id 的取值传入生成请求即可。VoiceInfo 中的 trial_url 是临时试听地址,需尽快下载保存。
视频编辑(base 视频)
以已生成的视频为编辑对象,用提示词改变内容。在 Category=Video 中指定 ReferenceType=base。
{
"SubAppId": 123456789,
"ModelName": "Kling",
"ModelVersion": "3.0-Omni",
"FileInfos": [
{
"Type": "Url",
"Category": "Video",
"Url": "https://<cos>/source.mp4",
"ReferenceType": "base"
}
],
"Prompt": "change the color of the main character's dress to white",
"OutputConfig": {
"StorageMode": "Permanent",
"MediaName": "kling-video-edit"
},
"SessionContext": "job-001"
}feature 与 base 的区别
feature 只取参考视频的特征并生成新视频。base 则编辑该视频本身。若目的是编辑,必须指定 base。
多元素编辑(multi_elements)
选择视频中的特定元素(被摄主体)进行删除或重新生成的 Kling 编辑功能。用两个会话 API 创建选择区域以准备 SessionId,之后以 CreateAigcVideoTask 的 SceneType=multi_elements 提交最终生成任务,这是 3 阶段的流程。
1 阶段 InitializeAigcMultiElementsSelection 上传并解析输入视频,签发 SessionId 2 阶段 EditAigcMultiElementsSelection 选择区域编辑(add / delete / clear / preview)。重复至满意为止 3 阶段 CreateAigcVideoTask 用 SceneType=multi_elements 生成最终视频
输入视频限制
输入视频时长须在 10 秒 以下,宽与高分别在 720px 以上。签发的 SessionId 有效期为 24 小时。
第 1 阶段 选择会话初始化(InitializeAigcMultiElementsSelection)
上传并解析待编辑视频,签发 SessionId。
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 必填 | Integer | VOD 应用程序 ID |
FileInfo | 可选 | Object | 视频来源 |
FileInfo.Type | 必填 | String | File 或 Url |
FileInfo.FileId | 可选 | String | 为 Type=File 时必填。VOD 文件 ID |
FileInfo.Url | 可选 | String | 为 Type=Url 时必填。可访问的视频 URL |
{
"SubAppId": 123456789,
"FileInfo": {
"Type": "Url",
"Url": "https://<cdn>/input.mp4"
}
}响应字段:
| 字段 | 说明 |
|---|---|
SessionId | 会话 ID。有效期 24 小时,在后续调用中使用 |
Status | 识别码。为 0 时表示成功 |
Fps | 视频帧率 |
OriginalDuration | 视频时长(秒) |
Width / Height | 视频宽 / 高 |
TotalFrame | 总帧数 |
NormalizedVideo | 规范化后的视频 URL |
{
"Response": {
"SessionId": "<session-id>",
"Status": 0,
"Fps": 30.0,
"OriginalDuration": 5.0,
"Width": 720,
"Height": 1280,
"TotalFrame": 150,
"NormalizedVideo": "https://<cdn>/normalized.mp4",
"RequestId": "<request-id>"
}
}第 2 阶段 选择区域编辑(EditAigcMultiElementsSelection)
一个 API 用 SelectionAction 区分四种动作。add(添加选择点)/ delete(删除选择点)/ clear(全部重置)/ preview(蒙版预览)。重复调用直至选择结果满意。
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
SubAppId | 必填 | Integer | VOD 应用程序 ID |
SelectionAction | 必填 | String | add / delete / clear / preview |
SessionId | 必填 | String | 1 阶段获取的会话 ID |
FrameIndex | 可选 | Integer | add/delete 时必填。目标帧编号 |
Points | 可选 | Array | add/delete 时必填。规范化坐标。Point.X / Point.Y 范围为 0~1 |
{
"SubAppId": 123456789,
"SelectionAction": "add",
"SessionId": "<session-id>",
"FrameIndex": 0,
"Points": [
{
"X": 0.773,
"Y": 0.297
}
]
}响应字段:
| 字段 | 出现条件 | 说明 |
|---|---|---|
Status | 通用 | 识别码。为 0 时表示成功 |
Result.FrameIndex | add / delete | 操作帧编号 |
Result.RleMaskList.ObjectId | add / delete | 所选对象 ID |
Result.RleMaskList.RleMask | add / delete | 选择蒙版 RLE(Counts)与尺寸(Size) |
Result.RleMaskList.PngMask.Url | add / delete | PNG 蒙版 URL |
Result.Video / VideoCover | preview | 带蒙版的预览视频 / 封面 URL |
Result.TrackingOutput | preview | 逐帧蒙版追踪结果 URL |
各动作的响应
delete 的响应结构与 add 相同。clear 不含 Result,只返回 Status。
第 3 阶段 最终生成(CreateAigcVideoTask,SceneType=multi_elements)
用 SceneType=multi_elements 触发多元素编辑场景。ExtInfo 的 AdditionalParameters 中放入前面创建的 session_id 与 edit_mode,并在 Prompt 中以 <<<video_1>>> 引用编辑对象。
{
"SubAppId": 123456789,
"ModelName": "Kling",
"ModelVersion": "1.6",
"FileInfos": [
{
"Type": "Url",
"Url": "https://<cdn>/ref.jpeg",
"Usage": "Reference"
}
],
"Prompt": "重新生成 <<<video_1>>> 中的特定主体",
"OutputConfig": {
"Duration": 10,
"StorageMode": "Temporary"
},
"SceneType": "multi_elements",
"ExtInfo": "{\"AdditionalParameters\":\"{\\\"session_id\\\":\\\"<session-id>\\\",\\\"edit_mode\\\":\\\"addition\\\"}\"}",
"SessionContext": "job-001"
}{
"Response": {
"TaskId": "<task-id>",
"RequestId": "<request-id>"
}
}返回的 TaskId 按下方的任务受理响应流程用 DescribeTaskDetail 轮询。