# AI Retake # 概览 留住这一刻，把脸换一换。AI 换脸（Retake）可以逐张逐脸地重建任意合照。不管是想做搞怪换脸图，还是需要一套专业工具，我们都能满足。 ![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-14/3d504686-8057-418e-a0cb-eba3d47ea42c.jpg) ## 接入指南 * 如何实现 AI 换脸（Retake） * 第 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/retake/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/retake/pre-process?task_id=TASK_ID ``` 1. 处理完成后，您会收到一份带边界框的检测到的人脸列表。 --- * 第 3 步：执行 AI 换脸（Retake）任务 1. 指定哪张参考图的脸去替换源图中的哪张脸 `face_mapping` 数组定义了 **源图** 中的人脸如何被 **参考图** 的人脸替换，作用相当于把源图中检测到的人脸与指定参考图串起来的关联表。 单次请求只支持替换一张脸。所有非目标的人脸都必须设为 `{"index": -1, "position": -1}`。尝试替换超过一张脸会返回 `error_change_too_many_faces`。返回该错误的请求不会计费。参考图只支持使用检测到的第一张脸，因此 index 必须始终为 0。 * 参数 | 参数 | 类型 | 说明 | | --- | --- | --- | | position | 整数 | 源图中检测到的人脸下标（例如 0、1、2）。 | | index | 整数 | 参考图人脸下标。目前只支持第一张检测到的人脸，因此该值必须为 0。 | * 规则 * 单脸替换：单次请求只能把一张源图人脸映射到一张参考图人脸。 * 跳过某张脸：把 index 与 position 都设为 -1。 * 参考图人脸下标：参考图只支持检测到的第一张脸，因此 index 始终为 0。 * 示例 场景 * 参考图：1 张含单张受支持人脸的图片。 * 源图：检测到 4 张脸（Face 0、Face 1、Face 2、Face 3）。 * 目标：只替换 Face 2，Face 0、Face 1、Face 3 保持不动。 ``` "face_mapping": [ { "index": -1, // Skip replacing "position": -1 // Skip replacing }, { "index": -1, // Skip replacing "position": -1 // Skip replacing }, { "index": 0, // Always use the first reference image "position": 2 // Apply to the third detected face in source }, { "index": -1, // Skip replacing "position": -1 // Skip replacing }, ] ``` 1. 发送主任务请求： ``` POST https://yce-api-01.makeupar.com/s2s/v2.0/task/retake 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": -1, "position": -1}, {"index": -1, "position": -1}, {"index": 0, "position": 2}, {"index": -1, "position": -1} ] } } ] } } ``` 1. 响应返回一个 `task_id` 。 --- * 第 4 步：轮询任务状态并取回结果 需要实现一个定时循环，在允许的轮询窗口内按固定间隔查询任务状态。 1. 在此接口轮询： ``` GET https://yce-api-01.makeupar.com/s2s/v2.0/task/retake?task_id=TASK_ID ``` 1. 当 `status` 为 `success` 时，响应中包含生成图片的 URL。 2. 从该 URL 下载或展示图片。 --- * 第 5 步：接入您的平台 * 在 **网页前端** ，可以直接用 JavaScript 的 fetch 或 Axios 实现。 * 在 **后端** （Node.js、Python、Java、PHP 等），用标准 HTTP 库调用同样的接口即可。 * 任务是异步执行的，请实现重试与错误处理。 --- * 排障指引 1. **为什么源图里有些脸没被检测到** **原因：** 理由：人脸必须清楚可见、没有被覆盖或遮挡，且在图片中足够大 **解决办法：** 重新拍一张照片，让脸部更大、清楚可见，没有任何遮盖或遮挡 --- ## 输入与输出 * 实际案例： ![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-14/9aeab2bb-28aa-48f5-ab86-2edd897ad908.jpg) ![](https://plugins-media.makeupar.com/smb/blog/post/2025-07-02/webp_0196a9d4-1430-4121-9680-5e81b58b66ac.webp) ## 文件规格与错误码 * 支持的格式与尺寸 | AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 | | --- | --- | --- | --- | | AI 换脸（Retake） | 输入与输出：长边不得超过 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 | 输入图片的宽高比不受支持 | | error_change_too_many_faces | 单次请求只支持替换一张脸。所有非目标的人脸都必须设为 {"index": -1, "position": -1}。尝试替换超过一张脸就会返回该错误。 | | unknown_internal_error | 其他内部错误 | --- ## 点数消耗 | AI 功能 | 消耗点数 | | --- | --- | | AI 换脸（Retake）V2.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 Retake](https://docs.perfectcorp.com/_bundle/@l10n/zh-CN/reference/ai_retake.yaml) ## V2.0 - [POST /s2s/v2.0/task/retake/pre-process](https://docs.perfectcorp.com/zh-cn/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1pre-process/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We - [GET /s2s/v2.0/task/retake/pre-process/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1pre-process~1%7Btask_id%7D/get.md) - [POST /s2s/v2.0/task/retake](https://docs.perfectcorp.com/zh-cn/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We - [GET /s2s/v2.0/task/retake/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_retake/v2.0/paths/~1s2s~1v2.0~1task~1retake~1%7Btask_id%7D/get.md)