# AI 换脸 # 概览 用 AI 视频换脸做出逼真到位的效果，并支持多人脸。我们的人脸换脸人工智能支持一次换一张或多张脸。不管是想做搞怪换脸图，还是需要一套专业工具，我们都能满足。 ## 接入指南 * 如何实现 AI 换脸 * 第 1 步：上传源图与参考图 1. 向接口请求上传 URL： ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/file Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` Body： ```json { "files": [ { "file_name": "target.jpg", "file_size": 123456, "content_type": "image/jpeg" } ] } ``` 1. 响应会给出一个预签名的**上传 URL** 和一个 `file_id`。 2. 用 HTTP PUT 请求把文件上传到该 URL。 3. 保存 `file_id` 备用。**目标图**与**参考图**都要重复这一套流程。 4. 把实际文件上传到**上传 URL**。 --- * 第 2 步：预处理源图与参考图（人脸检测） 1. 创建预处理任务： ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` Body： ```json { "request_id": 1, "payload": { "file_sets": { "src_ids": ["TARGET_FILE_ID"] }, "actions": [ { "id": 0 } ] } } ``` 1. 接口返回一个 `task_id` 。 2. 在此接口轮询任务状态： ``` GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process?task_id=TASK_ID ``` 1. 处理完成后，您会收到一份带边界框的检测到的人脸列表。 --- * 第 3 步：执行换脸任务 1. 指定哪些参考图的脸去替换源图中的哪张脸 `face_mapping` 数组定义了 **源图** 中的人脸如何被 **参考图列表** 中的人脸替换，作用相当于把源图中检测到的人脸与指定参考图串起来的关联表。 * 结构 数组中的每个元素是一个包含两个属性的对象： | 参数 | 类型 | 说明 | | --- | --- | --- | | `position` | `integer` | **源图**中检测到的人脸下标（例如 0、1、2）。 | | `index` | `integer` | **参考图列表**中要与之互换的人脸图片下标。 | * 逻辑规则 1. **下标映射：** `index` 直接对应您在参考图列表中提供的图片顺序。 * `0` ：第一张参考图。 * `1` ：第二张参考图。 2. **跳过互换：** 要跳过源图中某张检测到的人脸，把 `index` 与 `position` 都设为 `-1`。 3. **数组顺序：** 数组中各对象的排列顺序需与 `position` 对应。 * 使用示例 **场景：** * **参考图列表：** 提供 2 张图片（Image A、Image B）。 * **源图：** 检测到 3 张脸（Face 0、Face 1、Face 2）。 **目标：** * 把 **Face 0** （源图）与 **Image 1** （参考图）互换。 * 跳过 **Face 1** （源图）。 * 把 **Face 2** （源图）与 **Image 0** （参考图）互换。 **配置：** ```json "face_mapping": [ { "index": 1, // Use the second reference image "position": 0 // Apply to the first detected face in source }, { "index": -1, // Skip swapping "position": -1 // Skip swapping }, { "index": 0, // Use the first reference image "position": 2 // Apply to the third detected face in source } ] ``` 1. 发送主任务请求： ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` Body： ```json { "request_id": 2, "payload": { "file_sets": { "src_ids": ["TARGET_FILE_ID"], "ref_ids": ["REFERENCE_FILE_ID"] }, "actions": [ { "id": 0, "params": { "face_mapping": [ { "index": 0, "position": 0 }, { "index": -1, "position": -1 } ] } } ] } } ``` 1. 响应返回一个 `task_id` 。 --- * 第 4 步：轮询任务状态并取回结果 需要实现一个定时循环，在允许的轮询窗口内按固定间隔查询任务状态。 1. 在此接口轮询： ``` GET https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap?task_id=TASK_ID ``` 1. 当 `status` 为 `success` 时，响应中包含生成图片的 URL。 2. 从该 URL 下载或展示图片。 --- * 第 5 步：接入您的平台 * 在 **网页前端** ，可以直接用 JavaScript 的 fetch 或 Axios 实现。 * 在 **后端** （Node.js、Python、Java、PHP 等），用标准 HTTP 库调用同样的接口即可。 * 任务是异步执行的，请实现重试与错误处理。 --- * 排障指引 1. **Invalid TaskId 报错** **原因：** 若去查询已超时任务的状态，会收到 InvalidTaskId 错误。因此，发起 AI 任务之后，需要在 polling_interval 内持续轮询其状态，直到状态变为 success 或 error。 **解决办法：** 为避免任务失效，需要实现一个定时循环，在允许的轮询窗口内按固定间隔查询任务状态。 2. **为什么源图里有些脸没被检测到** **原因：** 理由：人脸必须清楚可见、没有被覆盖或遮挡，且在图片中足够大 **解决办法：** 重新拍一张照片，让脸部更大、清楚可见，没有任何遮盖或遮挡 --- ## 输入与输出 * 实际案例： 多人换脸示例： ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_04_d4b747a41d.jpg) 单人脸换脸示例： ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_face_swap_S2_img_05_8e68faff2c.jpg) * 拍摄建议： ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png) ## 文件规格与错误码 * 支持的格式与尺寸 | AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 | | --- | --- | --- | --- | | AI 换脸 | 输入与输出：长边不得超过 4096 像素 | < 10MB | jpg/jpeg/png | * 错误码 | 错误码 | 说明 | | --- | --- | | exceed_max_filesize | 输入文件大小超出上限 | | invalid_parameter | 参数取值无效 | | error_download_image | 下载源图片出错 | | error_download_mask | 下载蒙版图片出错 | | error_decode_image | 解码源图片出错 | | error_decode_mask | 解码蒙版图片出错 | | error_download_video | 下载源视频出错 | | error_decode_video | 解码源视频出错 | | error_nsfw_content_detected | 在源图中检测到不适宜内容（NSFW） | | error_no_face | 源图中未检测到人脸 | | error_pose | 源图中姿态检测失败 | | error_face_parsing | 源图的人脸解析失败 | | error_inference | 推理流程中出错 | | exceed_nsfw_retry_limits | 为避免生成不适宜内容，重试次数已超限 | | error_upload | 上传结果图片出错 | | error_multiple_people | 人数超出上限 | | error_no_shoulder | 源图中看不到肩部 | | error_large_face_angle | 上传图片中的脸部角度过大 | | error_unsupport_ratio | 输入图片的宽高比不受支持 | | unknown_internal_error | 其他内部错误 | --- ## 点数消耗 | AI 功能 | 消耗点数 | | --- | --- | | AI 换脸 V1.0 | 1 | --- License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 使用标准的 Bearer 鉴权。把您的 API 密钥放进请求头： `Authorization:Bearer YOUR_API_KEY`。请注意 'Bearer' 与 'YOUR_API_KEY' 之间有一个空格。 Type: http Scheme: bearer ## Download OpenAPI description - [AI 换脸](https://docs.perfectcorp.com/_bundle/@l10n/zh-CN/reference/ai_face_swap.yaml) ## V1.0 - [POST /s2s/v2.0/task/face-swap/pre-process](https://docs.perfectcorp.com/zh-cn/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process/post.md): 当源图中可能存在多个有效目标，或您的接入需要显式指定特效作用在哪个已检测目标上时，请使用预处理任务。若图片只有一个目标，且功能支持默认的 `index` 取值、您的应用也不需要手动挑选目标，这一步可以省略。 预处理任务会在源图中检测候选目标，并把它们的坐标返回在 `data.results.result` 中。结果数组里的每一项对应一个检测到的目标。请查看返回的坐标，与源图中您要处理的脸部或区域对 - [GET /s2s/v2.0/task/face-swap/pre-process/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1pre-process~1%7Btask_id%7D/get.md) - [POST /s2s/v2.0/task/face-swap](https://docs.perfectcorp.com/zh-cn/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We - [GET /s2s/v2.0/task/face-swap/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_face_swap/v1.0/paths/~1s2s~1v2.0~1task~1face-swap~1%7Btask_id%7D/get.md)