AI MediaKit 的视频人脸打码工具，能够自动并精准地识别视频画面中的人脸区域，并对所有人脸进行模糊或马赛克处理。此功能适用于需要保护人物五官隐私的场景，例如短剧内容脱敏、保护未成年人、新闻素材处理、生成式视频的参考素材预处理等。本篇开发指南将引导您： * 快速体验为一个视频中的所有人脸打上马赛克。 * 了解如何通过各项参数，精细化地控制打码的方式、强度与范围。 ## 效果预览通过视频人脸打码工具，您可以将一个包含人脸的视频作为输入，快速生成一个人脸均被精确地打上马赛克或高斯模糊的视频。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/fa53b57ced4448a3bc7c404464c61c41) ## 快速体验：为人脸打上马赛克本节将演示如何为一个视频，快速生成一个人脸区域被马赛克处理的视频。 ### 准备工作 1. **获取访问凭证**：在开始之前，访问 AI MediaKit 控制台 [API Key 管理页面](https://console.volcengine.com/imp/ai-mediakit/settings)，创建并获取 **AI MediaKit API Key**（用于媒体处理功能鉴权）。 2. **准备视频文件**：准备一个待处理的视频，并将其上传至公网可访问的服务器或[视频点播服务](https://www.volcengine.com/docs/4/2834?lang=zh)中，以获取可供 API 调用的 URL。为方便您快速测试，本文后续步骤的示例代码中提供了两个可直接使用的演示视频 URL。 ### 操作流程视频人脸打码是一个异步任务，完整流程如下： 1. 成功调用 `POST /api/v1/tools/face-blur-video` 提交任务后，您将获得一个任务 ID。 2. 您可以轮询 `GET /api/v1/tasks/{task_id}` 接口，直到任务状态 `status` 变为 `completed`；或者使用[事件回调](https://www.volcengine.com/docs/6448/2288701)自动接收任务状态变化。 3. 任务完成后，解析响应中的 `result` 字段，即可在 `video_url` 字段获取最终生成的视频文件下载地址。 #### 第 1 步：提交任务您需要调用[提交视频人脸打码任务 API](https://www.volcengine.com/docs/6448/2529910)。可直接复制以下 cURL 命令，提交一个使用默认参数（马赛克、中等强度）的打码任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/face-blur-video' \ -H 'Authorization: Bearer {Your_MediaKit_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://vod-ai-test.tos-cn-beijing.volces.com/demo/drama_ep01.mp4" }' ```

说明

将 {Your_MediaKit_API_Key} 替换为您的有效 API Key。

video_url：示例中已提供可直接测试的视频 URL。您可以替换为您自己的地址。

请求成功后，您会收到如下包含 `task_id` 的响应，请保存此 ID 用于后续查询。 ```JSON { "success": true, "task_id": "amk-tool-face-blur-video-123456789", "request_id": "20260415160000ABCDEFG12345" } ``` #### 第 2 步：获取结果您需要通过轮询[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532)，直到任务状态 `status` 变为 `completed`。 ```Bash curl -X GET 'https://mediakit.cn-beijing.volces.com/api/v1/tasks/{task_id}' \ -H 'Authorization: Bearer {Your_MediaKit_API_Key}' ```

说明

需替换参数：将 URL 末尾的 {task_id} 替换为第 1 步返回的任务 ID。

当任务成功完成后，您将收到如下响应。您可以在 `result.video_url` 字段中找到最终生成的打码视频下载地址（默认有效期为 24 小时）。 ```JSON { "success": true, "task_id": "amk-tool-face-blur-video-123456789", "request_id": "20260415160000ABCDEFG12345", "status": "completed", "result": { "video_url": "https://example.volcvideo.com/blurred_video.mp4?auth_key=...", "duration": 180.5 }, "expires_at": 1777464650, "created_at": 1777291767, "finished_at": 1777291851 } ``` ## 进阶使用在快速入门的基础上，您可以通过在提交任务时配置不同的参数，实现更精细的打码效果。 ### 选择打码方式：高斯模糊或马赛克通过 `mask_mode` 选择对人脸区域应用马赛克还是高斯模糊效果。 * `mosaic`：（默认）马赛克。 * `blur`：高斯模糊。 #### **示例：使用高斯模糊方式打码** ```JSON { "video_url": "https://example.com/your_video.mp4", "mask_mode": "blur" } ``` ### 调整打码强度通过 `mask_strength` 控制打码的强度，以适应不同场景下的隐私保护级别。 * `low`：低强度。 * `medium`：（默认）中强度。 * `high`：高强度。 #### **示例：使用高强度打码** ```JSON { "video_url": "https://example.com/your_video.mp4", "mask_strength": "high" } ``` ### 扩大打码范围为了更彻底地覆盖人脸轮廓，您可以通过 `face_box_expand` 设置一个扩展比例，在系统检测到的人脸边界框基础上向外扩大打码范围。例如，`0.2` 表示在原边界框的每条边上向外扩展 20%。 #### **示例：将打码范围向外扩展 20%** ```JSON { "video_url": "https://example.com/your_video.mp4", "face_box_expand": 0.2 } ``` ### 调整人脸识别灵敏度通过 `face_confidence` 调整人脸检测的置信度阈值，您可以控制人脸识别的严格程度。该值越高，检测结果越保守（即要求更高的人脸相似度），可能会漏掉一些模糊或非正面的脸；值越低，则可能将一些非人脸的物体误识别为人脸。取值范围为 `[0.1, 1.0]`，默认值为 `0.35`。 #### **示例：设置更高的识别置信度** ```JSON { "video_url": "https://example.com/your_video.mp4", "face_confidence": 0.5 } ``` ## 参考信息 ### 使用限制 |限制项 |说明 | |---|---| |输入视频限制 |* **视频来源**：支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、来源于火山引擎视频点播 (`vod://`) 和火山引擎对象存储 (`tos://`) 四种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://www.volcengine.com/docs/6448/2536893)。

* **支持格式**：`mp4`, `flv`, `ts`, `avi`, `mov`, `wmv`, `mkv` 等主流视频格式。

* **分辨率限制**：最高支持 4K，推荐使用 1080P 以获得最佳处理效果。

* **时长限制**：不得超过 10 分钟，

* **帧率限制**：帧率需在 25~60 范围内。 | ## 相关 API 文档 * [提交视频人脸打码任务 API](https://www.volcengine.com/docs/6448/2529910) * [查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) * [事件回调](https://www.volcengine.com/docs/6448/2288701)