腾讯混元生视频数据结构

CameraControl

控制摄像机运动的协议

被如下接口引用：SubmitImageToVideoJob, SubmitTextToVideoJob。

名称	类型	必选	描述
Type	String	否	枚举值：“simple”, “down_back”, “forward_up”, “right_turn_forward”, “left_turn_forward” simple：简单运镜，此类型下可在"config"中六选一进行运镜 down_back：镜头下压并后退 -> 下移拉远，此类型下config参数无需填写 forward_up：镜头前进并上仰 -> 推进上移，此类型下config参数无需填写 right_turn_forward：先右旋转后前进 -> 右旋推进，此类型下config参数无需填写 left_turn_forward：先左旋并前进 -> 左旋推进，此类型下config参数无需填写示例值：simple
Config	CameraControlConfig	否	包含六个字段，用于指定摄像机在不同方向上的运动或变化。 - 当运镜类型指定simple时必填，指定其他类型时不填 - 参数6选1，即只能有一个参数不为0，其余参数为0

CameraControlConfig

指定摄像机在不同方向上的运动或变化

被如下接口引用：SubmitImageToVideoJob, SubmitTextToVideoJob。

名称	类型	必选	描述
Horizontal	Float	否	水平运镜，控制摄像机在水平方向上的移动量（沿x轴平移）取值范围：[-10, 10]，负值表示向左平移，正值表示向右平移示例值：1
Vertical	Float	否	垂直运镜，控制摄像机在垂直方向上的移动量（沿y轴平移）取值范围：[-10, 10]，负值表示向下平移，正值表示向上平移示例值：0
Pan	Float	否	水平摇镜，控制摄像机在水平面上的旋转量（绕y轴旋转）取值范围：[-10, 10]，负值表示绕y轴向左旋转，正值表示绕y轴向右旋转示例值：0
Tilt	Float	否	垂直摇镜，控制摄像机在垂直面上的旋转量（沿x轴旋转）取值范围：[-10, 10]，负值表示绕x轴向下旋转，正值表示绕x轴向上旋转示例值：0
Roll	Float	否	旋转运镜，控制摄像机的滚动量（绕z轴旋转）取值范围：[-10, 10]，负值表示绕z轴逆时针旋转，正值表示绕z轴顺时针旋转示例值：0
Zoom	Float	否	变焦，控制摄像机的焦距变化，影响视野的远近取值范围：[-10, 10]，负值表示焦距变长、视野范围变小，正值表示焦距变短、视野范围变大示例值：0

DynamicMask

动态笔刷

被如下接口引用：SubmitImageToVideoJob。

名称	类型	必选	描述
Mask	String	否	动态笔刷涂抹区域（用户通过运动笔刷涂抹的 mask 图片）支持传入图片Base64编码或图片URL（确保可访问，格式要求同 Image 字段）图片格式支持.jpg / .jpeg / .png 图片长宽比必须与输入图片相同（即Image字段），否则任务失败 StaticMask 和 DynamicMasks.Mask 这两张图片的分辨率必须一致，否则任务失败示例值：https://ai.cos.ap-guangzhou.myqcloud.com/1.jpg
Trajectories	Array of Trajectory	否	运动轨迹坐标序列生成5s的视频，轨迹长度不超过77，即坐标个数取值范围：[2, 77] 轨迹坐标系，以图片左下角为坐标原点注1：坐标点个数越多轨迹刻画越准确，如只有2个轨迹点则为这两点连接的直线注2：轨迹方向以传入顺序为指向，以最先传入的坐标为轨迹起点，依次连接后续坐标形成运动轨迹

名称

类型

必选

描述

Mask

String

否

动态笔刷涂抹区域（用户通过运动笔刷涂抹的 mask 图片）

支持传入图片Base64编码或图片URL（确保可访问，格式要求同 Image 字段）
图片格式支持.jpg / .jpeg / .png
图片长宽比必须与输入图片相同（即Image字段），否则任务失败
StaticMask 和 DynamicMasks.Mask 这两张图片的分辨率必须一致，否则任务失败

示例值：https://ai.cos.ap-guangzhou.myqcloud.com/1.jpg

Trajectories

Array of Trajectory

否

运动轨迹坐标序列

生成5s的视频，轨迹长度不超过77，即坐标个数取值范围：[2, 77]
轨迹坐标系，以图片左下角为坐标原点
注1：坐标点个数越多轨迹刻画越准确，如只有2个轨迹点则为这两点连接的直线
注2：轨迹方向以传入顺序为指向，以最先传入的坐标为轨迹起点，依次连接后续坐标形成运动轨迹

Element

被如下接口引用：SubmitImageToVideoJob, SubmitMotionControlKlingJob, SubmitVideoEditKlingJob。

名称	类型	必选	描述
ElementId	String	否	ID配置示例值：elem-qtonh-asdmk-fphda

ElementImageList

主体正面图参考图列表

被如下接口引用：CreateAigcElement, DescribeAigcElement。

名称	类型	必选	描述
ReferImages	Array of ReferImageItem	否	主体参考图
FrontalImage	String	否	主体主图示例值：https://cos-internal.ap-guangzhou.tencentcos.cn/82fe54a8-4ebf-4407-b64d-56e675f93d5d.jpeg

ExtraParam

扩展字段。

被如下接口引用：SubmitTemplateToVideoJob。

名称	类型	必选	描述
UserDesignatedUrl	String	否	预签名的上传url，支持把视频直接传到客户指定的地址。示例值：http://tencent.com/result/video.mp4
CallbackUrl	String	否	回调地址需要您在创建任务时主动设置 CallbackUrl，请求方法为 POST，当视频生成结束时，我们将向此地址发送生成结果。数据格式如下： { "JobId": "1397428070633955328", "Status": "DONE", "ErrorCode": "", "ErrorMessage": "", "ResultVideoUrl": "https://vcg.cos.tencentcos.cn/template_to_video/fa80b846-b933-4981-afad-8a39b46ef2ca.mp4" } 示例值：http://vclm.tencent.com/template2video/callback
BGMText	String	否	BGM音频文本。示例值：祝大家身体健康，万事如意，心想事成。

FaceMergeInfo

人脸图片和待被融合的素材模板图的人脸位置信息。

被如下接口引用：SubmitVideoFaceFusionJob。

名称	类型	必选	描述
MergeFaceImage	Image	否	融合图片
MergeFaceRect	FaceRect	否	上传的图片人脸位置信息（人脸框） Width、Height >= 30。
TemplateFaceID	String	否	素材人脸ID，不填默认取上传图片中最大人脸。示例值：1

FaceRect

人脸框信息。

被如下接口引用：SubmitVideoFaceFusionJob。

名称	类型	必选	描述
X	Integer	否	人脸框左上角横坐标。示例值：1
Y	Integer	否	人脸框左上角纵坐标。示例值：1
Width	Integer	否	人脸框宽度。单位：px 示例值：30
Height	Integer	否	人脸框高度。单位：px 示例值：30

FaceTemplateInfo

模板信息

被如下接口引用：SubmitVideoFaceFusionJob。

名称	类型	必选	描述
TemplateFaceID	String	否	角色ID。需要与MergeInfos中的TemplateFaceID依次对应。需要填数字，建议填"0"、"1"，依次累加。示例值：0
TemplateFaceImage	Image	否	视频模板中要替换的人脸图片
TemplateFaceRect	FaceRect	否	视频模板中要替换的人脸图片的人脸框。不填默认取要替换的人脸图片中最大人脸。

Image

图片

被如下接口引用：SubmitHunyuanToVideoJob, SubmitImageToVideoGeneralJob, SubmitImageToVideoJob, SubmitTemplateToVideoJob, SubmitVideoEditJob, SubmitVideoFaceFusionJob。

名称	类型	必选	描述
Base64	String	否	图片Base64 示例值：MIIHNjCCBh6gAwIBAgIQCVe4E0h49mzI0NcSqMy1
Url	String	否	图片Url 示例值：https://cos.ap-guangzhou.myqcloud.com/image.jpg

ImageInfo

参考图列表

被如下接口引用：SubmitVideoEditKlingJob。

名称	类型	必选	描述
ImageUrl	String	是	图片URL 示例值：https://tencentcos.cn/input/1.png
Type	String	否	首帧：first_frame 尾帧：end_frame 其他：空示例值：first_frame

LogoParam

logo参数

被如下接口引用：SubmitAigcVideoJob, SubmitHumanActorJob, SubmitHunyuanToVideoJob, SubmitImageAnimateJob, SubmitImageToVideoGeneralJob, SubmitImageToVideoJob, SubmitImageToVideoViduJob, SubmitMotionControlKlingJob, SubmitPortraitSingJob, SubmitReferenceToVideoViduJob, SubmitTemplateToVideoJob, SubmitTextToVideoJob, SubmitTextToVideoViduJob, SubmitVideoEditJob, SubmitVideoEditKlingJob, SubmitVideoExtendKlingJob, SubmitVideoFaceFusionJob, SubmitVideoVoiceJob。

名称	类型	必选	描述
LogoUrl	String	否	水印 Url 示例值：https://cos.ap-guangzhou.myqcloud.com/logo.jpg
LogoImage	String	否	水印 Base64，Url 和 Base64 二选一传入，如果都提供以 Url 为准示例值：/9j/4QlQaHR0c...N6a2M5ZCI
LogoRect	LogoRect	否	水印图片位于生成结果图中的坐标及宽高，将按照坐标对标识图片进行位置和大小的拉伸匹配。示例值：{ "X": -222, "Y": -54, "Width": 202, "Height": 34 }

LogoRect

水印图输入框

名称	类型	必选	描述
X	Integer	否	水印图框X坐标值。当值大于0时，坐标轴原点位于原图左侧，方向指右；当值小于0时，坐标轴原点位于原图右侧，方向指左。示例值：-222
Y	Integer	否	水印图框Y坐标值。当值大于0时，坐标轴原点位于原图上侧，方向指下；当值小于0时，坐标轴原点位于原图下侧，方向指上。示例值：-54
Width	Integer	否	水印图框宽度。单位：px 示例值：202
Height	Integer	否	水印图框高度。单位：px 示例值：34

MultiPrompt

各分镜信息，如提示词、时长等

通过index、prompt、duration参数定义分镜序号及相应提示词和时长，其中：

最多支持6个分镜，最小支持1个分镜

每个分镜相关内容的最大长度不超过512

每个分镜的时长不大于当前任务的总时长，不小于1

所有分镜的时长之和等于当前任务的总时长

用key:value承载，如下：

"multi_prompt":[
{
"index":int,
"prompt": "string",
"duration": "5"
},
{
"index":int,
"prompt": "string",
"duration": "5"
}
]
当mult_shot参数为true且shot_type参数为customize时，当前参数不得为空

被如下接口引用：SubmitImageToVideoJob, SubmitTextToVideoJob, SubmitVideoEditKlingJob。

名称	类型	必选	描述
Index	Integer	否	分镜序号示例值：1
Prompt	String	否	分镜提示词示例值：女孩在转呼啦圈
Duration	String	否	时长示例值：5

ProviderDetail

被如下接口引用：DescribeAigcElement。

名称	类型	必选	描述
Provider	String	否	供应商详情示例值：kling
Status	String	否	状态示例值：pending
ErrorMessage	String	否	错误信息示例值：SUCCEED

ReferImageItem

生成视频时所引用的音色

被如下接口引用：CreateAigcElement, DescribeAigcElement。

名称	类型	必选	描述
ImageUrl	String	否	图片地址示例值：https://vcg.cos.ap-guangzhou.tencentcos.cn/1.png

ReferVideoInfo

参考视频信息

被如下接口引用：SubmitVideoEditKlingJob。

名称	类型	必选	描述
VideoUrl	String	否	视频地址示例值：http://cloud.com/file/video.mp4
ReferType	String	否	视频类型 feature为特征参考视频 base为待编辑视频示例值：base
KeepOriginalSound	String	否	否保留视频原声，yes为保留，no为不保留；当前参数对特征参考视频（feature）也生效。示例值：yes

ReferenceSubject

参考主体，主要用作参考图生视频。由主体id、主体图（三视图）以及声音组成。

被如下接口引用：SubmitReferenceToVideoViduJob。

名称	类型	必选	描述
Id	String	是	主体id，后续生成时在提示词中可以通过@主体id的方式使用。示例值：subject_1
Images	Array of String	是	该主体对应的图片url，每个主体最多支持3张图片注1：支持传入图片URL（确保可访问）注2：图片支持 png、jpeg、jpg、webp格式注3：图片像素不能小于 128*128，且比例需要小于1:4或者4:1，且大小不超过50M。示例值：["https://xx.jpg"]
Name	String	否	主体id，后续生成时可以通过@主体id的方式使用示例值：subject_1
Videos	Array of String	否	主体视频，该主体对应的视频url，与videos必填一个注1：仅viduq2-pro模型支持使用视频主体注2：每个主体中的图片和视频，共享3个槽位注3：支持1个5秒视频注4：支持传入视频 URL（确保可访问）注5：视频支持 mp4、avi、mov格式注6：视频像素不能小于 128128，且比例需要小于1:4或者4:1 注7：请注意，base64 decode之后的字节长度需要小于20M，且编码必须包含适当的内容类型字符串示例值：["https:/********.cos.ap-guangzhou.myqcloud.com/longvideopro/output_16.mp4"]
VoiceId	String	否	音色ID用来决定视频中的声音音色，为空时系统会自动推荐，可选枚举值参考列表：[音色列表](URL https://shengshu.feishu.cn/sheets/EgFvs6DShhiEBStmjzccr5gonOg) 示例值：male-qn-qingse

生成视频时所引用的音色

被如下接口引用：CreateAigcElement, DescribeAigcElement。

名称	类型	必选	描述
TagId	String	否	tag标签示例值：o_102

Trajectory

运动轨迹坐标序列

被如下接口引用：SubmitImageToVideoJob。

名称	类型	必选	描述
X	Integer	否	轨迹点横坐标（在像素二维坐标系下，以输入图片image左下为原点的像素坐标）示例值：50
Y	Integer	否	轨迹点纵坐标（在像素二维坐标系下，以输入图片image左下为原点的像素坐标）示例值：50

VideoEditParam

视频编辑参数

被如下接口引用：SubmitVideoEditJob。

名称	类型	必选	描述
Magic	String	否	魔法词，针对特定场景生效。不同场景传不同的值。默认不传。 - 换人场景：1 示例值：1

Voice

生成视频时所引用的音色

被如下接口引用：SubmitImageToVideoJob。

名称	类型	必选	描述
VoiceId	String	否	音色id 示例值：626193

数据结构

本页目录：

CameraControl

CameraControlConfig

DynamicMask

Element

ElementImageList

ExtraParam

FaceMergeInfo

FaceRect

FaceTemplateInfo

Image

ImageInfo

LogoParam

LogoRect

MultiPrompt

ProviderDetail

ReferImageItem

ReferVideoInfo

ReferenceSubject

TagList

Trajectory

VideoEditParam

Voice