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：

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

  {
      "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（参考图）互换。

    配置：

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

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

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

• 第 5 步：接入您的平台

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

• 排障指引

  1. Invalid TaskId 报错
     原因： 若去查询已超时任务的状态，会收到 InvalidTaskId 错误。因此，发起 AI 任务之后，需要在 polling_interval 内持续轮询其状态，直到状态变为 success 或 error。
     解决办法： 为避免任务失效，需要实现一个定时循环，在允许的轮询窗口内按固定间隔查询任务状态。

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

输入与输出

• 实际案例： 多人换脸示例：

单人脸换脸示例：

• 拍摄建议：

文件规格与错误码

• 支持的格式与尺寸

• 错误码

点数消耗