文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>API 中心>腾讯混元生视频>混元生视频相关接口>提交视频人脸融合任务

提交视频人脸融合任务

最近更新时间：2025-12-03 03:18:32

我的收藏

本页目录：

1. 接口描述

接口请求域名： vclm.tencentcloudapi.com 。

提交视频人脸融合任务

默认接口请求频率限制：20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。

参数名称 必选 类型 描述
Action 是 String 公共参数，本接口取值：SubmitVideoFaceFusionJob。
Version 是 String 公共参数，本接口取值：2024-05-23。
Region 是 String 公共参数，详见产品支持的 地域列表。
VideoUrl 否 String 视频素材下载地址。用户自定义模版视频下载地址，使用前需要先调用视频审核接口进行内容审核。视频限制：分辨率≤4k，fps≤25，视频大小≤1G，时长≤20 秒，支持格式mp4。

输入视频建议：
姿态：人脸相对镜头水平方向角度转动不超过 90°,垂直方向角度转动不超过 20°。遮挡：脸部遮挡面积不超过 50%，不要完全遮挡五官，不要有半透明遮挡（强光，玻璃，透明眼镜等）、以及细碎离散的脸部遮挡（如飘落的花瓣）。妆容及光照：避免浓妆、复杂妆容，避免复杂光照、闪烁，这些属性无法完全恢复，并对稳定性有影响。针对特殊表情和微表情，针对局部肌肉控制下的微表情，以及过于夸张的特殊表情等不保证表情效果完全恢复。
示例值：http://cloud.com/video.mp4
TemplateInfos.N 否 Array of FaceTemplateInfo 视频素材模板的人脸位置信息。
目前最多支持融合视频素材中的 6 张人脸
输入图片要求：
1、用户图限制大小不超过 10MB
2、图片最大分辨率不超过 4k，建议最小为 128， 人脸框最小为 68
3、支持格式 jpg，png
4、如果用户图中未指定人脸且有多张人脸， 默认融合最大人脸
输入图片建议： 包含上述视频中出现的人物的单人照，并且正面、清晰、无遮挡
MergeInfos.N 否 Array of FaceMergeInfo 用户人脸图片位置信息。
输入图片要求：
1、用户图限制大小不超过 10MB
2、图片最大分辨率不超过 4k，建议最小为 128，人脸框最小为 68
3、支持格式 jpg，png
4、如果未指定人脸且用户图中有多张人脸，
默认融合最大人脸
输入图建议：
正脸无遮挡
LogoAdd 否 Integer 为生成视频添加标识的开关，默认为1。
1：添加标识。 0：不添加标识。 其他数值：默认按1处理。
建议您使用显著标识来提示，该视频是 AI 生成的视频。
示例值：0
LogoParam 否 LogoParam 视频水印Logo参数标识内容设置。
默认在融合结果图右下角添加“AI生成”类似字样，您可根据自身需要替换为其他的Logo图片。
输入建议：输入水印图片宽高需小于视频宽高

3. 输出参数

参数名称 类型 描述
JobId String 视频人脸融合任务的job id（job有效期24小时）
示例值：1300653023995437056
RequestId String 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 提交视频人脸融合任务

输入示例

POST / HTTP/1.1
Host: vclm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: SubmitVideoFaceFusionJob
<公共请求参数>

{
    "VideoUrl": "https://cos.ap-guangzhou.myqcloud.com/facefusion/face/video2.mp4",
    "TemplateInfos": [
        {
            "TemplateFaceID": "0",
            "TemplateFaceImage": {
                "Url": "https://cos.ap-guangzhou.myqcloud.com/facefusion/face/face.png"
            }
        }
    ],
    "MergeInfos": [
        {
            "MergeFaceImage": {
                "Url": "https://cos.ap-guangzhou.myqcloud.com/facefusion/face/guodegang.jpg"
            },
            "TemplateFaceID": "0"
        }
    ]
}

输出示例

{
    "Response": {
        "JobId": "1383749921168539648",
        "RequestId": "de9cc0c9-2acb-400f-8986-c29e22c92a60"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。

SDK

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

命令行工具

6. 错误码

以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。

错误码 描述
FailedOperation.ImageDownloadError 图片下载失败。
FailedOperation.ImageNotSupported 不支持的图片文件。
FailedOperation.ModerationFailed 内容审核不通过。
InvalidParameter.InvalidParameter 参数不合法。
InvalidParameterValue.NoFaceInPhoto 图片中没有人脸。
InvalidParameterValue.UrlIllegal URL格式不合法。
中国站
目录