{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-CN/reference/ai_retake.yaml","sidebar":"sidebar-@l10n/zh-CN/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-CN/reference/ai_retake.yaml","settings":{"baseUrlPath":"/zh-cn/reference/ai_retake"},"disableAutoScroll":true,"seo":{"title":"AI Retake","description":"YouCam API documentation by Perfect Corp. Learn how to use Skin analysis API, Virtual try-on API, Image editing API, and Video generative AI APIs.","siteUrl":"https://docs.perfectcorp.com","keywords":"AI Skin Analysis, AI Clothes, AI Hairstyle, AI Outfits","image":"/assets/favicon.cd6fa4d833b2a573b3c6dae68386b293da205b203402cb0c97b80bd2acc07ea2.8351e24f.png"},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"AI Retake","version":"","description":"# 概览\n留住这一刻，把脸换一换。AI 换脸（Retake）可以逐张逐脸地重建任意合照。不管是想做搞怪换脸图，还是需要一套专业工具，我们都能满足。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-14/3d504686-8057-418e-a0cb-eba3d47ea42c.jpg)\n\n## 接入指南\n* 如何实现 AI 换脸（Retake）\n\n   * 第 1 步：上传源图与参考图\n\n      1. 向接口请求上传 URL：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/file\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body：\n\n        ```json\n        {\n            \"files\": [\n            {\n                \"file_name\": \"target.jpg\",\n                \"file_size\": 123456,\n                \"content_type\": \"image/jpeg\"\n            }\n            ]\n        }\n        ```\n        1. 响应会给出一个预签名的**上传 URL** 和一个 `file_id`。\n        2. 用 HTTP PUT 请求把文件上传到该 URL。\n        3. 保存 `file_id` 备用。**目标图**与**参考图**都要重复这一套流程。\n\n      2. 把实际文件上传到**上传 URL**。\n\n---\n\n   * 第 2 步：预处理源图与参考图（人脸检测）\n\n        1. 创建预处理任务：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/retake/pre-process\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body：\n\n        ```json\n        {\n            \"request_id\": 1,\n            \"payload\": {\n            \"file_sets\": {\n                \"src_ids\": [\"TARGET_FILE_ID\"]\n            },\n            \"actions\": [\n                { \"id\": 0 }\n            ]\n            }\n        }\n        ```\n        1. 接口返回一个 `task_id`。\n        2. 在此接口轮询任务状态：\n\n        ```\n        GET https://yce-api-01.makeupar.com/s2s/v2.0/task/retake/pre-process?task_id=TASK_ID\n        ```\n        1. 处理完成后，您会收到一份带边界框的检测到的人脸列表。\n\n---\n\n   * 第 3 步：执行 AI 换脸（Retake）任务\n        1. 指定哪张参考图的脸去替换源图中的哪张脸\n        `face_mapping` 数组定义了**源图**中的人脸如何被**参考图**的人脸替换，作用相当于把源图中检测到的人脸与指定参考图串起来的关联表。 \n        \n        单次请求只支持替换一张脸。所有非目标的人脸都必须设为 `{\"index\": -1, \"position\": -1}`。尝试替换超过一张脸会返回 `error_change_too_many_faces`。返回该错误的请求不会计费。参考图只支持使用检测到的第一张脸，因此 index 必须始终为 0。\n\n        * 参数\n            \n            | 参数\t| 类型\t| 说明 |\n            | -- | -- | -- |\n            | position\t| 整数\t| 源图中检测到的人脸下标（例如 0、1、2）。\n            | index\t| 整数\t| 参考图人脸下标。目前只支持第一张检测到的人脸，因此该值必须为 0。\n            \n        * 规则\n          * 单脸替换：单次请求只能把一张源图人脸映射到一张参考图人脸。\n          * 跳过某张脸：把 index 与 position 都设为 -1。\n          * 参考图人脸下标：参考图只支持检测到的第一张脸，因此 index 始终为 0。\n            \n        * 示例\n\n            场景\n            * 参考图：1 张含单张受支持人脸的图片。\n            * 源图：检测到 4 张脸（Face 0、Face 1、Face 2、Face 3）。\n            * 目标：只替换 Face 2，Face 0、Face 1、Face 3 保持不动。\n            ```\n                \"face_mapping\": [\n                    {\n                        \"index\": -1, // Skip replacing\n                        \"position\": -1 // Skip replacing\n                    },\n                    {\n                        \"index\": -1, // Skip replacing\n                        \"position\": -1 // Skip replacing\n                    },\n                    {\n                        \"index\": 0, // Always use the first reference image\n                        \"position\": 2 // Apply to the third detected face in source\n                    },\n                    {\n                        \"index\": -1, // Skip replacing\n                        \"position\": -1 // Skip replacing\n                    },\n                ]\n            ```\n        1. 发送主任务请求：\n\n        ```\n        POST https://yce-api-01.makeupar.com/s2s/v2.0/task/retake\n        Authorization: Bearer YOUR_API_KEY\n        Content-Type: application/json\n        ```\n\n        Body：\n\n        ```json\n        {\n          \"request_id\": 2,\n          \"payload\"   : {\n            \"file_sets\": {\n              \"src_ids\": [\"TARGET_FILE_ID\"   ],\n              \"ref_ids\": [\"REFERENCE_FILE_ID\"]\n            },\n            \"actions\"  : [\n              {\n                \"id\"    : 0,\n                \"params\": {\n                  \"face_mapping\": [\n                    {\"index\": -1, \"position\": -1},\n                    {\"index\": -1, \"position\": -1},\n                    {\"index\":  0, \"position\":  2},\n                    {\"index\": -1, \"position\": -1}\n                  ]\n                }\n              }\n            ]\n          }\n        }\n        ```\n        1. 响应返回一个 `task_id`。\n\n---\n\n   * 第 4 步：轮询任务状态并取回结果\n        需要实现一个定时循环，在允许的轮询窗口内按固定间隔查询任务状态。\n        1. 在此接口轮询：\n\n        ```\n        GET https://yce-api-01.makeupar.com/s2s/v2.0/task/retake?task_id=TASK_ID\n        ```\n        2. 当 `status` 为 `success` 时，响应中包含生成图片的 URL。\n        3. 从该 URL 下载或展示图片。\n\n---\n\n   * 第 5 步：接入您的平台\n\n        * 在**网页前端**，可以直接用 JavaScript 的 fetch 或 Axios 实现。\n        * 在**后端**（Node.js、Python、Java、PHP 等），用标准 HTTP 库调用同样的接口即可。\n        * 任务是异步执行的，请实现重试与错误处理。\n\n---\n\n    * 排障指引\n\n        1. **为什么源图里有些脸没被检测到**\n            </br>**原因：** 理由：人脸必须清楚可见、没有被覆盖或遮挡，且在图片中足够大\n            </br>**解决办法：** 重新拍一张照片，让脸部更大、清楚可见，没有任何遮盖或遮挡\n\n---\n\n## 输入与输出\n\n* 实际案例：\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-14/9aeab2bb-28aa-48f5-ab86-2edd897ad908.jpg)\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2025-07-02/webp_0196a9d4-1430-4121-9680-5e81b58b66ac.webp)\n\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |\n| ---- | ---- | ---- | ---- |\n| AI 换脸（Retake） | 输入与输出：长边不得超过 4096 像素 | < 10MB | jpg/jpeg/png |\n\n\n* 错误码\n\n| 错误码 | 说明 |\n| ------------------ | ----------- |\n| exceed_max_filesize | 输入文件大小超出上限 |\n| invalid_parameter | 参数取值无效 |\n| error_download_image | 下载源图片出错 |\n| error_download_mask | 下载蒙版图片出错 |\n| error_decode_image | 解码源图片出错 |\n| error_decode_mask | 解码蒙版图片出错 |\n| error_download_video | 下载源视频出错 |\n| error_decode_video | 解码源视频出错 |\n| error_nsfw_content_detected | 在源图中检测到不适宜内容（NSFW） |\n| error_no_face | 源图中未检测到人脸 |\n| error_pose | 源图中姿态检测失败 |\n| error_face_parsing | 源图的人脸解析失败 |\n| error_inference | 推理流程中出错 |\n| exceed_nsfw_retry_limits | 为避免生成不适宜内容，重试次数已超限 |\n| error_upload | 上传结果图片出错 |\n| error_multiple_people | 人数超出上限 |\n| error_no_shoulder | 源图中看不到肩部 |\n| error_large_face_angle | 上传图片中的脸部角度过大 |\n| error_unsupport_ratio | 输入图片的宽高比不受支持 |\n| error_change_too_many_faces | 单次请求只支持替换一张脸。所有非目标的人脸都必须设为 {\"index\": -1, \"position\": -1}。尝试替换超过一张脸就会返回该错误。 |\n| unknown_internal_error | 其他内部错误 |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 换脸（Retake）V2.0 | 1 |\n\n---\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.217.126"},"lang":"zh-CN","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/zh-cn/reference/ai_retake","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}