`POST https://mediakit.cn-beijing.volces.com/api/v1/tools/face-swap-video` 本 API 用于提交一个异步的视频人脸融合任务，将用户提供的目标人脸融合替换到视频中的人物上，输出高质量换脸视频，适用于出海、生成式视频脱敏、娱乐社交内容创作、数字人/虚拟主播等需要换脸的场景。当前仅支持单人换脸。 * **获取任务结果**：任务提交成功后，您需要保存返回的 `task_id`，并通过轮询[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) 或配置[事件回调](https://www.volcengine.com/docs/6448/2288701)获取最终结果。 * **开发指南**：如需了解完整的使用流程和应用示例，请参阅[视频人脸融合（换脸）](https://www.volcengine.com/docs/6448/2558631)。 ## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_MediaKit_API_Key}` |格式为 `Bearer {Your_MediaKit_API_Key}`。请参考[基础概念及准备工作](https://www.volcengine.com/docs/6448/2300661)获取 API Key。 | ### Body 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`video_url` |String |是 |`https://example.com/source.mp4` |待换脸的视频源 URL。

* **视频来源**：支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、来源于火山引擎视频点播 (`vod://`) 和火山引擎对象存储 (`tos://`) 四种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://www.volcengine.com/docs/6448/2536893)。

* **支持格式**：当前仅支持 MP4。

* **分辨率限制**：不得超过 1080P。

* **时长限制**：不得超过 10 分钟（600 秒）。 | |`face_mappings` |Array |是 |`-` |人脸映射列表。当前仅支持单人换脸，传入一项即可。其包含的参数详见[face_mapping 结构](https://www.volcengine.com/docs/6448/2563058#cdceb2c9)。 | |`client_token` |String |否 |`your_unique_request_id_131` |用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考[幂等性控制](https://www.volcengine.com/docs/6448/2300661#672adae7)。 | |`callback_args` |String |否 |`your_unique_callback_args` |自定义回调参数。您提供的内容将在任务完成时，通过[事件回调](https://www.volcengine.com/docs/6448/2288701)原样返回，方便您关联业务。字段长度最大为 512 字节。 | |`callback_url` |String |否 |`https://example.com/callback` |用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考[事件回调](https://www.volcengine.com/docs/6448/2288701)了解回调接收机制和回调消息结构。 | |`queue_id` |String |否 |`q00a9731598092652e4a95292434198` |任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考[项目与队列管理](https://www.volcengine.com/docs/6448/2519520)。 | ### face_mapping 结构 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`target_face_url` |String |是 |`https://example.com/face.jpg` |目标人脸图片 URL。

* **文件来源**：支持公网可访问的 HTTP/HTTPS URL，或 mediakit/tos 平台资源链接。支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`) 和火山引擎对象存储 (`tos://`) 三种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://www.volcengine.com/docs/6448/2536893)。

* **支持格式**：`jpeg`、`png`。

* **分辨率建议**：256×256～1080×1080。

* **画面要求**：一张清晰可见、无遮挡的正脸；不支持动漫人脸。 | ## 请求示例以下示例演示了如何为一个视频提交人脸融合任务，将视频中的主体人脸替换为目标人脸照片。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/face-swap-video' \ -H 'Authorization: Bearer {Your_MediaKit_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/source.mp4", "face_mappings": [ { "target_face_url": "https://example.com/face.jpg" } ] }' ``` ## 响应说明 ### 任务提交成功响应任务提交成功后，接口会立即返回以下 JSON 对象。 |参数 |类型 |描述 | |---|---|---| |`success` |Boolean |任务是否提交成功。

* `true`：成功。

* `false`：失败。更多信息请查看[错误码](https://www.volcengine.com/docs/6448/2300662)。 | |`task_id` |String |任务的唯一标识，用于后续查询任务进度和结果。 | |`request_id` |String |本次请求的唯一标识，可用于问题排查。 | 示例： ```JSON { "success": true, "task_id": "amk-tool-face-swap-video-1703201", "request_id": "20260629160000F6DE4C24A6A0D94B8AB2" } ``` ### 异步任务结果任务处理完成后，通过[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) 或[事件回调](https://www.volcengine.com/docs/6448/2288701)获取的 `result` 字段将包含以下内容。 |参数 |类型 |示例 |描述 | |---|---|---|---| |`video_url` |String |`https://example.volcvideo.com/output.mp4?auth_key=...` |已完成人脸融合的视频文件下载地址。该地址的有效期为 **24 小时**，请务必及时保存产物。 | |`duration` |Number |`180.5` |输出视频的总时长（单位：秒）。 | 最终的完整任务信息示例： ```JSON { "success": true, "task_id": "amk-tool-face-swap-video-1703201", "request_id": "20260629160000F6DE4C24A6A0D94B8AB2", "result": { "video_url": "https://example.volcvideo.com/face_swap_result.mp4?auth_key=1775271661-...", "duration": 180.5 }, "expires_at": 1777464650, "created_at": 1777291767, "finished_at": 1777291851 } ``` ## 错误处理当请求的参数或鉴权信息不正确时，任务将不会被创建，接口会返回一个同步的错误响应。详见[错误码](https://www.volcengine.com/docs/6448/2300662)。示例如下： ```JSON { "success": true, "task_id": "amk-tool-face-swap-video-47708906754", "task_type": "face-swap-video", "status": "failed", "created_at": 1778827959, "finished_at": 1778827973, "request_id": "202606291452382EB49B08B360546311E7", "error": { "code": "AbilityProcessingError", "type": "BadRequest", "message": "file upload by url failed, code: DownloadFailed.UrlDownloadFail, message: GetUrlInfo failed, http status code is 403, msg: 403 Forbidden" } } ```

智能处理