跳到内容

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 支持多镜头(智能分镜)与视频编辑,并提供动作控制、口型同步、数字人、自定义音色等扩展能力,可同时生成音频。

基本信息 ​

项目值
ModelNameKling
ModelVersion4.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-Omni720P / 1080P / 2K(超分)/ 4K(超分)21:9 / 16:9 / 9:16 / 1:13–30 秒
4.0-Flash720P / 1080P(超分)/ 2K(超分)/ 4K(超分)21:9 / 16:9 / 9:16 / 1:13–20 秒
3.0-turbo720P / 1080P / 2K / 4K文本生成 16:9 / 9:16 / 1:13–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可选String4.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可选String480P / 720P / 1080P / 2K / 4K
OutputConfig.Duration可选Integer视频时长(秒)
OutputConfig.AspectRatio可选String16: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 则解除输出审核。使用前请咨询商务负责人

请求示例 ​

json
{
  "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"
}

响应示例 ​

json
{
  "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.InputComplianceCheckDisabled解除输入审核
OutputConfig.OutputComplianceCheckDisabled解除输出审核

将以下设置合并到现有生成请求中。要同时解除输入与输出审核,请一并传递两个字段。

json
{
  "OutputConfig": {
    "InputComplianceCheck": "Disabled",
    "OutputComplianceCheck": "Disabled"
  }
}

首 / 尾帧生成(First / Last Frame) ​

给定起始帧与结束帧图片,会生成将两帧之间自然衔接的视频。首帧通过 FileInfos 以 Usage=FirstFrame 指定,尾帧通过 LastFrameUrl(或 LastFrameFileId)指定。

json
{
  "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(标准入口)。

json
{
  "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 留空。

json
{
  "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 指定。

json
{
  "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 传递的参考对象
json
{
  "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 为可选项,即使附加,提示词中的参考标记也相同。

json
{
  "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。

json
{
  "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_shotBoolfalse为 true 时为多镜头模式。此时顶层 Prompt 会被忽略
shot_typeString空值customize(直接指定)/ intelligence(自动)。为 multi_shot=true 时必填
multi_promptArray空值逐镜信息。最多 6 个,最少 1 个

multi_prompt 条目构成:

字段说明
index镜头编号
prompt镜头脚本。最多 512 字符
duration镜头时长(秒)。1 以上,且不超过总时长

镜头时长之和必须等于总时长

请将各镜头的 duration 之和指定为与 OutputConfig.Duration 相同。

customize:直接指定镜头 ​

json
{
  "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 的示例。

python
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>>> 指定。

json
{
  "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任务优先级

请求示例

json
{
  "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
}

代码示例

python
# -*- 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)
go
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,用于后续查询创建进度:

json
{
  "Response": {
    "RequestId": "424661ad-4e48-4d42-8f31-5066cae7157c",
    "TaskId": "221073-CreateAigcCustomVoice-77226813bc1038c2720a63c6962b16e6t"
  }
}

查询创建结果(DescribeTaskDetail)

用上一步返回的 TaskId 调用 DescribeTaskDetail 轮询,直到 Status=FINISH;音色 ID 位于 CreateAigcCustomVoiceTask.Output.InfoList[].VoiceId。

json
{
  "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。

json
{
  "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必填IntegerVOD 应用程序 ID
FileInfo可选Object视频来源
FileInfo.Type必填StringFile 或 Url
FileInfo.FileId可选String为 Type=File 时必填。VOD 文件 ID
FileInfo.Url可选String为 Type=Url 时必填。可访问的视频 URL
json
{
  "SubAppId": 123456789,
  "FileInfo": {
    "Type": "Url",
    "Url": "https://<cdn>/input.mp4"
  }
}

响应字段:

字段说明
SessionId会话 ID。有效期 24 小时,在后续调用中使用
Status识别码。为 0 时表示成功
Fps视频帧率
OriginalDuration视频时长(秒)
Width / Height视频宽 / 高
TotalFrame总帧数
NormalizedVideo规范化后的视频 URL
json
{
  "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必填IntegerVOD 应用程序 ID
SelectionAction必填Stringadd / delete / clear / preview
SessionId必填String1 阶段获取的会话 ID
FrameIndex可选Integeradd/delete 时必填。目标帧编号
Points可选Arrayadd/delete 时必填。规范化坐标。Point.X / Point.Y 范围为 0~1
json
{
  "SubAppId": 123456789,
  "SelectionAction": "add",
  "SessionId": "<session-id>",
  "FrameIndex": 0,
  "Points": [
    {
      "X": 0.773,
      "Y": 0.297
    }
  ]
}

响应字段:

字段出现条件说明
Status通用识别码。为 0 时表示成功
Result.FrameIndexadd / delete操作帧编号
Result.RleMaskList.ObjectIdadd / delete所选对象 ID
Result.RleMaskList.RleMaskadd / delete选择蒙版 RLE(Counts)与尺寸(Size)
Result.RleMaskList.PngMask.Urladd / deletePNG 蒙版 URL
Result.Video / VideoCoverpreview带蒙版的预览视频 / 封面 URL
Result.TrackingOutputpreview逐帧蒙版追踪结果 URL

各动作的响应

delete 的响应结构与 add 相同。clear 不含 Result,只返回 Status。

第 3 阶段 最终生成(CreateAigcVideoTask,SceneType=multi_elements) ​

用 SceneType=multi_elements 触发多元素编辑场景。ExtInfo 的 AdditionalParameters 中放入前面创建的 session_id 与 edit_mode,并在 Prompt 中以 <<<video_1>>> 引用编辑对象。

json
{
  "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"
}
json
{
  "Response": {
    "TaskId": "<task-id>",
    "RequestId": "<request-id>"
  }
}

返回的 TaskId 按下方的任务受理响应流程用 DescribeTaskDetail 轮询。

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages