AI Retake

接入指南

• 如何实现 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：

    {
        "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：

  {
      "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：

  {
    "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

  2. 当 status 为 success 时，响应中包含生成图片的 URL。
  3. 从该 URL 下载或展示图片。

• 第 5 步：接入您的平台

  • 在网页前端，可以直接用 JavaScript 的 fetch 或 Axios 实现。
  • 在后端（Node.js、Python、Java、PHP 等），用标准 HTTP 库调用同样的接口即可。
  • 任务是异步执行的，请实现重试与错误处理。

• 排障指引

  1. 为什么源图里有些脸没被检测到
     原因： 理由：人脸必须清楚可见、没有被覆盖或遮挡，且在图片中足够大
     解决办法： 重新拍一张照片，让脸部更大、清楚可见，没有任何遮盖或遮挡

输入与输出

• 实际案例：

文件规格与错误码

• 支持的格式与尺寸

• 错误码

点数消耗