# 提交视频人脸融合任务 API 文档

> SDK: `tencentcloud.vclm.v20240523`

## 接口信息

- **接口域名**：vclm.tencentcloudapi.com
- **Action**：SubmitVideoFaceFusionJob
- **Version**：2024-05-23
- **类型**：异步接口，提交后返回 JobId，需通过 DescribeVideoFaceFusionJob 查询结果

## 输入参数

| 参数名称        | 必选 | 类型                     | 描述                                                                                                                                                    |
| --------------- | ---- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| VideoUrl        | 是   | String                   | 视频素材下载地址。分辨率≤4k，fps≤25，大小≤1G，时长≤20秒，支持 mp4 格式。                                                                                     |
| TemplateInfos   | 是   | Array of FaceTemplateInfo | 视频素材模板的人脸位置信息。最多支持融合视频中 6 张人脸。                                                                                                     |
| MergeInfos      | 是   | Array of FaceMergeInfo   | 用户人脸图片位置信息。图片≤10MB，分辨率≤4k，建议最小 128，人脸框最小 68，支持 jpg/png。                                                                         |
| LogoAdd         | 否   | Integer                  | 是否添加 AI 合成标识。默认 1（添加）。0：不添加，1：添加。                                                                                                     |
| LogoParam       | 否   | LogoParam                | 视频水印 Logo 参数。默认右下角添加"AI生成"字样。                                                                                                               |

### FaceTemplateInfo 结构

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

### FaceMergeInfo 结构

| 参数名称        | 必选 | 类型     | 描述                                                    |
| --------------- | ---- | -------- | ------------------------------------------------------- |
| MergeFaceImage  | 是   | Image    | 融合图片（用户人脸）。                                     |
| MergeFaceRect   | 否   | FaceRect | 用户图片人脸位置信息（人脸框）。Width、Height >= 30。       |
| TemplateFaceID  | 否   | String   | 素材人脸 ID，不填默认取最大人脸。                            |

### Image 结构

| 参数名称 | 必选 | 类型   | 描述                                   |
| -------- | ---- | ------ | -------------------------------------- |
| Base64   | 否   | String | 图片 Base64 编码数据                      |
| Url      | 否   | String | 图片 URL 地址。Base64 和 Url 二选一       |

### FaceRect 结构

| 参数名称 | 必选 | 类型    | 描述              |
| -------- | ---- | ------- | ----------------- |
| X        | 是   | Integer | 人脸框左上角横坐标  |
| Y        | 是   | Integer | 人脸框左上角纵坐标  |
| Width    | 是   | Integer | 人脸框宽度          |
| Height   | 是   | Integer | 人脸框高度          |

### LogoParam 结构

| 参数名称   | 必选 | 类型     | 描述                                                     |
| ---------- | ---- | -------- | -------------------------------------------------------- |
| LogoUrl    | 否   | String   | 水印 URL 地址                                              |
| LogoImage  | 否   | String   | 水印 Base64 数据。Url 和 Base64 二选一，都提供以 Url 为准     |
| LogoRect   | 否   | LogoRect | 水印位置和大小                                               |

## 输出参数

| 参数名称   | 类型   | 描述                                    |
| ---------- | ------ | --------------------------------------- |
| JobId      | String | 视频人脸融合任务 ID（有效期 24 小时）      |
| RequestId  | String | 唯一请求 ID                               |

## 视频素材要求

- **格式**：mp4
- **分辨率**：≤ 4k
- **帧率**：≤ 25fps
- **大小**：≤ 1G
- **时长**：≤ 20 秒
- **人脸姿态**：水平转动不超过 90°，垂直转动不超过 20°
- **遮挡要求**：脸部遮挡面积不超过 50%，避免半透明遮挡
- **妆容光照**：避免浓妆、复杂妆容、复杂光照和闪烁

## 人脸图片要求

- **大小**：≤ 10MB
- **分辨率**：≤ 4k，建议最小 128，人脸框最小 68
- **格式**：jpg、png
- **建议**：正脸无遮挡，包含视频中出现人物的单人照