本文为您介绍如何调用 StartExecution 接口提交异步的视频人脸打码任务。视频点播会自动识别画面中的人脸，并通过马赛克或高斯模糊方式进行遮挡，适用于隐私保护、内容合规等场景。

注意事项

支持地域：当前仅支持中国内地地域。

输入限制：

文件格式：MP4、MOV、MKV、WEBM、AVI。

视频时长：不超过 10 分钟。

视频帧率：25～60 fps。

视频分辨率：最高支持 4K，推荐使用 1080P 视频以获得更好的处理效果。

调用准备：调用本接口前，建议先阅读如何调用 OpenAPI，了解在线调试、请求签名等通用调用流程。

计费说明：提交任务会产生视频 AI 费用，具体参见视频 AI 应用计费。

QPS 限制：本接口的单用户 QPS 限制为 50 次/秒。超过限制时，API 调用会被限流。更多信息请参见 API QPS 限制。

请求说明

请求方式：POST

请求地址：https://vod.volcengineapi.com?Action=StartExecution&Version=2023-07-01

请求参数

下表仅列出该任务特有的请求参数和部分公共参数。更多信息请参见公共请求参数。

Query

Action String 必选示例值：StartExecution

接口名称。当前 API 的名称为 StartExecution。

Version String 必选示例值：2025-01-01

接口版本。当前 API 的版本为 2025-01-01。

Body

Input Object 必选示例值：-

输入文件信息。

Type String 必选示例值：Vid

输入文件类型。取值如下：

Vid：Vid 模式。此模式下，还需设置 Vid。

DirectUrl：DirectUrl 模式。此模式下，还需设置 DirectUrl。

Vid String 可选示例值：v0ccfeg7007acsg***fog65ubr7niqng

待处理视频的 Vid。您需要先将视频上传至点播空间并获取 Vid。

注意

您必须设置 Vid 或 DirectUrl 参数之一，但不能同时设置这两个参数。

DirectUrl Object 可选示例值：-

通过 DirectUrl 模式指定待处理视频的信息。

SpaceName String 必选示例值：test

点播空间名称。可调用 ListSpace 获取当前账号下所有空间的信息。

FileName String 必选示例值：example.mp4

文件路径。音视频上传至视频点播服务后，可通过媒资上传完成事件获取该参数。

BucketName String 可选示例值：tos-cn-v-cd3a11

存储桶名称。可调用 ListSpace 获取空间所绑定的存储桶名称。

Operation Object 必选示例值：-

媒体处理操作配置。

Type String 必选示例值：Task

处理类型。视频人脸打码任务需设置为 Task。

Task Object 必选示例值：-

单任务配置。

Type String 必选示例值：FaceMosaic

任务类型。视频人脸打码任务需设置为 FaceMosaic。

FaceMosaic Object 必选示例值：-

视频人脸打码任务配置。

Confidence Float 可选示例值：0.35

人脸检测置信度阈值，取值范围为 [0.1, 1.0]，默认值为 0.35。低于该阈值的检测结果会被丢弃；值越高，检测结果越保守。

UprightOnly Boolean 可选示例值：false

是否仅检测竖向人脸。默认值为 false。

Mode String 可选示例值：mosaic

人脸遮挡方式。默认值为 mosaic。取值如下：

mosaic：像素化马赛克。

blur：高斯模糊。

Strength String 可选示例值：medium

遮挡强度。默认值为 medium。取值如下：

low：低。

medium：中。

high：高。

当 Mode 为 mosaic 时，该参数控制像素块大小；当 Mode 为 blur 时，该参数控制模糊核大小和叠加次数。

Expand Float 可选示例值：0.2

检测框向外扩展的比例，取值范围为 [0.0, 1.0]，默认值为 0.2。例如，取值为 0.2 时，检测框的上、下、左、右各扩展 20%。

Control Object 可选示例值：-

任务控制配置。

ClientToken String 可选示例值：QqS3o5L4BLFCDxGZ&b

用户请求凭证，用于区分不同请求。大小写敏感，不超过 64 个 ASCII 可打印字符。关于幂等行为、目的和条件，请参见工作流幂等说明。

CallbackArgs String 可选示例值：Example

自定义字段，将在媒体处理任务执行完成事件中透传返回。字段长度最大为 512 字节。

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见公共返回参数。

RunId String 示例值：hb:c5cacd4946bd***a5fd9f74159b03ae8

媒体处理任务执行 ID。您可以使用该参数调用 GetExecution 查询任务状态和结果。

请求示例

以下示例通过 Vid 提交视频人脸打码任务，使用高斯模糊方式并将遮挡强度设置为高。

获取任务结果

任务提交成功后，您可以通过以下任一方式获取处理结果：

调用 GetExecution，传入 RunId 查询任务状态。当 Status 为 Success 时，从 Output.Task.FaceMosaic 获取输出视频时长、分辨率、帧率和文件信息。

配置媒体处理任务执行完成事件，通过事件回调接收任务结果。

错误码

本接口无特有的错误码。更多信息请参见公共错误码。

服务端 SDK

视频点播为 OpenAPI 提供配套的服务端 SDK。本接口仅 VOD SDK 2.0 支持，详见 V2.0 SDK 介绍与迁移说明。