媒体处理视频重制接入

概述
视频换脸换人功能基于腾讯云媒体处理服务（MPS）的视频二次创作能力，通过 AI 模型实现视频中人脸替换和全身换人。该功能广泛应用于影视后期、虚拟数字人、短视频创意制作、广告创意等场景。
﻿
功能说明
功能
说明
效果示意
计费说明
AI 换脸
替换视频中指定人脸，支持多人物、多参考图，保留身体动作与服装。
﻿
收取“视频重制 – AI 换脸”费用。
AI 换人
替换视频中人物的整体形象，包含体型、服装等全身特征
﻿
收取“视频重制 – AI 换人”费用。
画中画
将原视频缩小嵌入 AI 生成的背景中。
﻿
收取“视频重制 – 画面调整”费用。
背景扩展
在视频中插入扩展背景画面。
﻿
﻿
垂直填充
竖屏填充，为横屏视频生成上下补充内容。
﻿
﻿
水平填充
横屏填充，为竖屏视频生成左右补充内容。
﻿
﻿
详细定价可参考 计费说明文档。
使用限制
模式
限制
AI 换脸
视频时长建议 ≤ 20 分钟；分辨率 ≤ 1920×1920；单张图片 < 10M，支持 jpg/png，分辨率 ≤ 4K。
AI 换人
视频时长 ≤ 20 分钟；图片大小 ≤ 5M；需正面全身照。
说明：
处理时长参考：AI 换脸和 AI 换人，处理时长约为视频时长的60倍（例如，1分钟视频约需60分钟处理）。
如需申请专用资源、确认具体配置或获取更多技术支持，请 联系我们。
接入准备
1. 腾讯云账号注册/登录。
2. 登录 MPS 控制台，开启服务并完成服务角色授权。
3. 准备 COS 存储桶用于存放输入文件和输出结果。
具体指引请参考 快速入门。账号授权问题可参考 账号授权 文档。
发起视频重制任务
使用 API 发起
调用 ProcessMedia 接口。
核心参数
参数
类型
说明
InputInfo
object
输入文件信息，支持 COS 或 URL。
OutputStorage
object
输出存储配置（COS）。
OutputDir
string
输出目录路径。
AiAnalysisTask.Definition
int
固定填 29。
AiAnalysisTask.ExtendedParameter
string
扩展参数 JSON 字符串（需转义）。
请求示例（AI 换脸）
{
    "InputInfo": {
        "Type": "URL",
        "UrlInputInfo": {
            "Url": "https://your-bucket.cos.ap-guangzhou.myqcloud.com/input/video.mp4"
        }
    },
    "OutputStorage": {
        "Type": "COS",
        "CosOutputStorage": {
            "Bucket": "your-bucket",
            "Region": "ap-guangzhou"
        }
    },
    "OutputDir": "/output/",
    "AiAnalysisTask": {
        "Definition": 29,
        "ExtendedParameter": "{\\"vremake\\":{\\"mode\\":\\"SwapFaceV2\\",\\"swapFaceV2\\":{\\"srcFaces\\":[[\\"https://your-bucket.cos.../p1_ref1.jpg\\",\\"https://your-bucket.cos.../p1_ref2.jpg\\"],[\\"https://your-bucket.cos.../p2_ref1.jpg\\"]],\\"dstFaces\\":[\\"https://your-bucket.cos.../p1_dst.jpg\\",\\"https://your-bucket.cos.../p2_dst.jpg\\"]}}}"
    }
}
说明：
ExtendedParameter 需要对 JSON 字符串进行转义。
查询任务结果
事件通知回调
发起任务时通过 TaskNotifyConfig 参数配置事件回调，任务完成后系统会主动推送结果。可通过 ParseNotification 解析回调内容。
接口查询
调用 DescribeTaskDetail 接口，传入发起任务时返回的 TaskId，解析 WorkflowTask.AiAnalysisResultSet 字段获取输出结果。
任务结果关键字段
AiAnalysisResultSet[0].VideoRemakeTask.Output.Path        → 输出视频路径
AiAnalysisResultSet[0].VideoRemakeTask.Output.OutputStorage → 输出存储信息
ExtendedParameter 扩展参数说明
指定不同重制功能，以及配置对应参数，需通过 ExtendedParameter 传入，顶层结构为：
{
    "vremake": {
        "mode": "<模式名>",
        "<模式参数对象>": { ... }
    }
}
功能
mode 值
AI 换脸
SwapFaceV2
AI 换人
SwapCharacter
画中画
PicInPic
背景扩展
BackgroundExtend
垂直填充
VerticalExtend
水平填充
HorizontalExtend
AI 换脸（SwapFaceV2）- 一站式自动处理模式
针对整段输入视频，一站式自动化完成 切镜 → 人脸追踪 → 换脸合成 → 整片拼接，输出最终换脸视频。ExtendedParameter扩展参数示例：
{
    "vremake": {
        "mode": "SwapFaceV2",
        "swapFaceV2": {
            "srcFaces": [
                ["<人物1参考图1>", "<人物1参考图2>"],
                ["<人物2参考图1>"]
            ],
            "dstFaces": [
                "<人物1目标脸>",
                "<人物2目标脸>"
            ]
        }
    }
}
参数
必选
类型
说明
srcFaces
是
string[][]
视频中需要被替换的人物列表。外层下标对应一个人物，内层是该人物的全部参考图（不同角度/表情）。每人至少 1 张，单图 < 10M。
dstFaces
是
string[]
目标人脸图 URL 列表，与 srcFaces 按人物一一对应，长度必须相等。每人 1 张，单图 < 10M。
说明：
srcFaces[i] 的全部参考图对应同一个人物，建议提供多张正面和侧面图以提升追踪精度。
dstFaces[i] 建议使用正脸无遮挡的清晰照片。
中间产物与 project.json
一站式自动处理模式执行过程中，会将所有中间产物归档到用户 COS 输出目录下的 <成品文件名>_intermediates/ 目录。该目录中的 project.json 是整个项目的单一事实源，后续微调操作均基于此文件进行。
中间产物目录结构
<OutputDir>/
├── <finalOutBase>.mp4                       # 最终成品视频
└── <finalOutBase>_intermediates/
    ├── project.json                         # 项目描述文件（微调的核心依据）
    ├── scenes/
    │   ├── scene_000.mp4                    # 切镜后的分镜视频
    │   ├── scene_001.mp4
    │   └── ...
    ├── masks/
    │   ├── scene_000_face_0.mp4             # 各分镜的人脸轨迹 mask
    │   ├── scene_000_face_1.mp4
    │   └── ...
    └── swapped/
        ├── scene_000.mp4                    # 各分镜的换脸结果
        ├── scene_001.mp4
        └── ...
project.json 结构
{
    "faces": [
        {
            "face_id": "face_0",
            "face_ref_urls": ["<人物0参考图1>", "<人物0参考图2>"],
            "face_dst_url": "<人物0目标脸>"
        }
    ],
    "scenes": [
        {
            "video": "<分镜源视频URL>",
            "dst_video": "<分镜换脸结果URL>",
            "start_time": 0,
            "end_time": 5.32,
            "faces": [
                {
                    "face_id": "face_0",
                    "face_ref_urls": ["<参考图URL>"],
                    "face_dst_url": "<目标脸URL>",
                    "face_mask_url": "<人脸轨迹mask视频URL>"
                }
            ]
        }
    ],
    "dst_video": "<最终成品视频URL>"
}
关键字段说明：
字段
类型
说明
faces
object[]
项目级人物列表，由入参 srcFaces/dstFaces 派生，按 face_<i> 编号。
scenes
object[]
按镜头切片得到的分镜列表，数组顺序即拼接顺序。
scenes[i].video
string
该分镜的源视频 URL。
scenes[i].dst_video
string
该分镜换脸后的结果视频 URL。
scenes[i].start_time / end_time
float
分镜在原始视频中的起止时间（秒）。
scenes[i].faces[j].face_mask_url
string
该人物在本分镜的人脸轨迹 mask 视频，可人工微调后回写。
dst_video
string
全部分镜拼接后的最终成品视频 URL。
说明：
任务成功时，project.json 在回调上报前完成最终落盘，读到的一定是终态。
所有 URL 已转存到用户 COS，不会指向临时地址。
微调流程
基于 project.json，可以对任意分镜进行微调后重新生成：
SwapFaceV2（一把梭）
    │  产出 project.json
    ▼
对某个分镜重新追踪 → SwapFaceV2TrackFace
    │  回写 face_mask_url
    ▼
对某个分镜重新换脸 → SwapFaceV2SwapFace
    │  回写 dst_video
    ▼
重新拼接整片 → SwapFaceV2Concat
    │  更新 project.dst_video
    ▼
保存 project.json 到 COS 同一路径（幂等覆盖）
每次微调子任务完成后，将结果回写到 project.json 对应字段，并将整份 JSON 重新 PUT 回用户 COS 的同一路径。
AI 换脸（SwapFaceV2）- 微调流程
基于一站式自动模式输出的 project.json，可以对任意分镜进行微调后重新生成：
SwapFaceV2（一把梭）
    │  产出 project.json
    ▼
对某个分镜重新追踪 → SwapFaceV2TrackFace
    │  回写 face_mask_url
    ▼
对某个分镜重新换脸 → SwapFaceV2SwapFace
    │  回写 dst_video
    ▼
重新拼接整片 → SwapFaceV2Concat
    │  更新 project.dst_video
    ▼
保存 project.json 到 COS 同一路径（幂等覆盖）
mode
用途
计费说明
SwapFaceV2TrackFace
仅追踪人脸（单分镜）：输出人脸轨迹 mask。
收取“视频重制 – AI 换脸”费用。
SwapFaceV2SwapFace
仅换脸（单分镜）：输入 mask + 目标脸，输出本分镜的换脸结果视频。
收取“视频重制 – AI 换脸”费用。
SwapFaceV2Concat
仅拼接：输入是多段视频 URL（videoUrls），按数组顺序统一分辨率和帧率拼接为最终成品视频。
收取“视频重制 – 画面调整”费用。
详细定价可参考 计费说明文档。
每次微调子任务完成后，系统会将结果回写到 project.json 对应字段，并将整份 JSON 重新 PUT 回用户 COS 的同一路径。
SwapFaceV2TrackFace
仅追踪人脸（单分镜）：输出人脸轨迹 mask。
{
    "vremake": {
        "mode": "SwapFaceV2TrackFace",
        "swapFaceV2TrackFace": {
            "srcFaces": [
                ["<人物1参考图1>", "<人物1参考图2>"],
                ["<人物2参考图1>"]
            ]
        }
    }
}
输出为 JSON 文件，包含每个人物的 face_mask_url（人脸轨迹 mask 视频）。
SwapFaceV2SwapFace
仅换脸（单分镜）：输入 mask + 目标脸，输出本分镜的换脸结果视频。
{
    "vremake": {
        "mode": "SwapFaceV2SwapFace",
        "swapFaceV2SwapFace": {
            "faces": [
                {
                    "face_id": "face_0",
                    "mask_url": "<追踪输出的mask视频URL>",
                    "dst_face_url": "<目标人脸图URL>"
                }
            ]
        }
    }
}
SwapFaceV2Concat
仅拼接：输入是多段视频 URL（videoUrls），按数组顺序统一分辨率和帧率拼接为最终成品视频。该模式常用于多次 SwapFaceV2SwapFace 单分镜微调后导出整片。
{
    "vremake": {
        "mode": "SwapFaceV2Concat",
        "swapFaceV2Concat": {
            "videoUrls": [
                "<分镜1换脸结果URL>",
                "<分镜2换脸结果URL>"
            ]
        }
    }
}
说明：
可通过任务级 InputInfo 指定外部音频源（推荐传入原始整片），避免分片拼接时的音频卡顿。
当 InputInfo 未指定或下载失败时，自动退化为「拼接各分片自带音频」，不会阻断主流程。
AI 换人（SwapCharacter）
{
    "vremake": {
        "mode": "SwapCharacter",
        "swapCharacter": {
            "srcCharacter": "<原视频中人物的正面全身图URL>",
            "character": "<目标人物的正面全身图URL>"
        }
    }
}
参数
必选
类型
说明
srcCharacter
是
string
原视频中人物的 URL（正面全身照）。
character
是
string
目标替换人物的 URL（正面全身照）。
templateId
否
string
模板 ID，可实现特定效果（如仅换头），默认为全身换人。
画面调整
画中画（PicInPic）
{
    "vremake": {
        "mode": "PicInPic",
        "picInPic": {
            "llmPrompt": "生成一张科技感背景图片"
        }
    }
}
参数
必选
类型
说明
llmVideoPrompt
二选一
string
生成背景视频的提示词。
llmPrompt
二选一
string
生成背景图片的提示词。
randomMove
否
bool
是否随机移动，默认 false。
frontRect
否
Rect
上层视频的位置与大小（x/y 默认居中，width/height 默认 0.5）。
背景扩展（BackgroundExtend）
{
    "vremake": {
        "mode": "BackgroundExtend",
        "backgroundExtend": {
            "minSceneSecs": 2.0
        }
    }
}
参数
必选
类型
说明
minSceneSecs
否
float
插入扩展画面的最小间隔（秒），默认2.0。
垂直填充（VerticalExtend）
{
    "vremake": {
        "mode": "VerticalExtend",
        "verticalExtend": {
            "llmVideoPrompt": "生成一段自然风景视频"
        }
    }
}
参数
必选
类型
说明
llmVideoPrompt
否
string
生成填充视频的提示词，默认"随机生成一个视频"。
水平填充（HorizontalExtend）
{
    "vremake": {
        "mode": "HorizontalExtend",
        "horizontalExtend": {
            "llmVideoPrompt": "生成一段城市街景视频"
        }
    }
}
参数
必选
类型
说明
llmVideoPrompt
否
string
生成填充视频的提示词，默认"随机生成一个视频"。

视频重制接入

本页目录：

概述

功能说明

使用限制

接入准备

发起视频重制任务

使用 API 发起

核心参数

请求示例（AI 换脸）

查询任务结果

事件通知回调

接口查询

任务结果关键字段

`ExtendedParameter` 扩展参数说明

AI 换脸（SwapFaceV2）- 一站式自动处理模式

中间产物与 project.json

中间产物目录结构

project.json 结构

关键字段说明：

微调流程

AI 换脸（SwapFaceV2）- 微调流程

SwapFaceV2TrackFace

SwapFaceV2SwapFace

SwapFaceV2Concat

AI 换人（SwapCharacter）

画面调整

画中画（PicInPic）

背景扩展（BackgroundExtend）

垂直填充（VerticalExtend）

水平填充（HorizontalExtend）

功能	说明	效果示意	计费说明
AI 换脸	替换视频中指定人脸，支持多人物、多参考图，保留身体动作与服装。		收取“视频重制 – AI 换脸”费用。
AI 换人	替换视频中人物的整体形象，包含体型、服装等全身特征		收取“视频重制 – AI 换人”费用。
画中画	将原视频缩小嵌入 AI 生成的背景中。			收取“视频重制 – 画面调整”费用。
背景扩展	在视频中插入扩展背景画面。
垂直填充	竖屏填充，为横屏视频生成上下补充内容。
水平填充	横屏填充，为竖屏视频生成左右补充内容。

模式	限制
AI 换脸	视频时长建议 ≤ 20 分钟；分辨率 ≤ 1920×1920；单张图片 < 10M，支持 jpg/png，分辨率 ≤ 4K。
AI 换人	视频时长 ≤ 20 分钟；图片大小 ≤ 5M；需正面全身照。

参数	类型	说明
`InputInfo`	object	输入文件信息，支持 COS 或 URL。
`OutputStorage`	object	输出存储配置（COS）。
`OutputDir`	string	输出目录路径。
`AiAnalysisTask.Definition`	int	固定填 `29`。
`AiAnalysisTask.ExtendedParameter`	string	扩展参数 JSON 字符串（需转义）。

功能	`mode` 值
AI 换脸	`SwapFaceV2`
AI 换人	`SwapCharacter`
画中画	`PicInPic`
背景扩展	`BackgroundExtend`
垂直填充	`VerticalExtend`
水平填充	`HorizontalExtend`

参数	必选	类型	说明
`srcFaces`	是	string[][]	视频中需要被替换的人物列表。外层下标对应一个人物，内层是该人物的全部参考图（不同角度/表情）。每人至少 1 张，单图 < 10M。
`dstFaces`	是	string[]	目标人脸图 URL 列表，与 `srcFaces` 按人物一一对应，长度必须相等。每人 1 张，单图 < 10M。

字段	类型	说明
`faces`	object[]	项目级人物列表，由入参 `srcFaces`/`dstFaces` 派生，按 `face_<i>` 编号。
`scenes`	object[]	按镜头切片得到的分镜列表，数组顺序即拼接顺序。
`scenes[i].video`	string	该分镜的源视频 URL。
`scenes[i].dst_video`	string	该分镜换脸后的结果视频 URL。
`scenes[i].start_time` / `end_time`	float	分镜在原始视频中的起止时间（秒）。
`scenes[i].faces[j].face_mask_url`	string	该人物在本分镜的人脸轨迹 mask 视频，可人工微调后回写。
`dst_video`	string	全部分镜拼接后的最终成品视频 URL。

mode	用途	计费说明
`SwapFaceV2TrackFace`	仅追踪人脸（单分镜）：输出人脸轨迹 mask。	收取“视频重制 – AI 换脸”费用。
`SwapFaceV2SwapFace`	仅换脸（单分镜）：输入 mask + 目标脸，输出本分镜的换脸结果视频。	收取“视频重制 – AI 换脸”费用。
`SwapFaceV2Concat`	仅拼接：输入是多段视频 URL（videoUrls），按数组顺序统一分辨率和帧率拼接为最终成品视频。	收取“视频重制 – 画面调整”费用。

视频重制接入

本页目录：

概述

功能说明

﻿

使用限制

接入准备

发起视频重制任务

使用 API 发起

核心参数

请求示例（AI 换脸）

查询任务结果

事件通知回调

接口查询

任务结果关键字段

ExtendedParameter 扩展参数说明

AI 换脸（SwapFaceV2）- 一站式自动处理模式

中间产物与 project.json

中间产物目录结构

project.json 结构

关键字段说明：

微调流程

AI 换脸（SwapFaceV2）- 微调流程

SwapFaceV2TrackFace

SwapFaceV2SwapFace

SwapFaceV2Concat

AI 换人（SwapCharacter）

画面调整

画中画（PicInPic）

背景扩展（BackgroundExtend）

垂直填充（VerticalExtend）

水平填充（HorizontalExtend）

`ExtendedParameter` 扩展参数说明