图片换脸 Pro

NamiFusion Image FaceSwap Pro

AI 图片换脸 Pro：支持单人自动换脸与多人关键点精确映射，适用于高可控换脸场景。

NamiFusion Image FaceSwap Pro 是一个面向高精度场景的图片换脸接口。它支持两类输入方式：单人自动模式（字符串 URL）与多人精确模式（对象数组 + 关键点），可在不同业务场景下平衡易用性与可控性。

---

核心特性

• 单人自动换脸： sourceImage 和 targetImage 直接传字符串 URL，系统自动做人脸关键点检测。
• 多人精确映射： 使用 ImageWithKeypoints[] 并传入 opts 关键点，按索引一一配对处理。
• 可选面部优化： face_enhance 仅支持布尔值，开启后会移除脸部瑕疵,提升面部观感。
• 统一输入结构： 支持字符串与对象数组两种输入形态。

---

技术规格

参数	详情
核心输入字段	sourceImage、targetImage、face_enhance
图片对象结构	ImageWithKeypoints（path + opts）
单人模式输入	字符串 URL / 路径
多人模式输入	ImageWithKeypoints[] 数组

---

快速开始

API 端点

端点	方法	说明
/api/v1/marketplace/run/namifusion/faceswap-image-pro	POST	提交 FaceSwap Pro 任务
/api/v1/marketplace/run/tasks/{task_uuid}	GET	查询任务状态与结果

请求参数总览

请求体中与 FaceSwap Pro 相关的核心字段如下：

{
  "sourceImage": "string | ImageWithKeypoints[]",
  "targetImage": "string | ImageWithKeypoints[]",
  "face_enhance": "boolean"
}

认证

在请求 Header 中携带 API Key（如你的服务网关要求）：

X-API-Key: sk-your-api-key

标准调用流程

FaceSwap Pro 采用异步任务模式：

1. 调用 POST /api/v1/marketplace/run/namifusion/faceswap-image-pro 提交任务。
2. 从响应中拿到 task_uuid。
3. 调用 GET /api/v1/marketplace/run/tasks/{task_uuid} 轮询任务状态。
4. 当 status 变为 completed 时，从响应中的 output 读取结果；若为 failed，查看 error_message。

第 1 步：提交任务

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-image-pro" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "sourceImage": "https://example.com/source.jpg",
      "targetImage": "https://example.com/target.jpg",
      "face_enhance": false
    }
  }'

提交成功响应示例：

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "estimated_time": 150,
  "cost_credits": 10
}

第 2 步：查询结果

curl -X GET "https://www.namifusion.com/api/v1/marketplace/run/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-API-Key: sk-your-api-key"

处理中响应示例：

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model_id": "namifusion/faceswap-image-pro",
  "status": "processing",
  "output": null,
  "error_message": null,
  "created_at": "2026-04-13T10:00:00Z",
  "completed_at": null
}

完成响应示例：

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model_id": "namifusion/faceswap-image-pro",
  "status": "completed",
  "output": {
    "image_url": "https://cdn.namifusion.com/result/faceswap_pro_abc123.jpg"
  },
  "cost_credits": 10,
  "error_message": null,
  "created_at": "2026-04-13T10:00:00Z",
  "completed_at": "2026-04-13T10:00:12Z"
}

失败响应示例：

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model_id": "namifusion/faceswap-image-pro",
  "status": "failed",
  "output": null,
  "cost_credits": 10,
  "error_message": "Face swap failed because no valid face was detected in targetImage.",
  "created_at": "2026-04-13T10:00:00Z",
  "completed_at": "2026-04-13T10:00:08Z"
}

---

前置步骤：调用 Detect Faces 组装 ImageWithKeypoints

在多人换脸场景中，推荐先调用人脸检测接口，拿到每张脸的 landmarks_str，再组装为 FaceSwap Pro 需要的 opts 字段。

第 1 步：调用 Detect Faces

检测接口（异步）：

• POST /api/v1/marketplace/run/namifusion/detect_faces
• GET /api/v1/marketplace/run/tasks/{task_uuid}

请求示例（检测目标图）：

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/detect_faces" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "url": "https://example.com/group_target.jpg",
      "return_face_url": true
    }
  }'

检测完成后，可从 output.faces_obj["0"] 读取关键字段：

• landmarks_str[i]：可直接作为 opts
• face_urls[i]：可作为单脸裁剪图地址（适合 source 侧）
• region[i]：人脸框信息（排查和可视化用）

检测结果片段示例：

{
  "output": {
    "faces_obj": {
      "0": {
        "landmarks_str": [
          "402,486:614,489:511,626:506,702",
          "120,85:180,88:150,130:150,165"
        ],
        "face_urls": [
          "https://example.com/faces/source_face_0.jpg",
          "https://example.com/faces/source_face_1.jpg"
        ],
        "region": [
          [278, 219, 442, 640],
          [80, 50, 150, 180]
        ]
      }
    }
  }
}

第 2 步：组装 ImageWithKeypoints

ImageWithKeypoints 结构如下：

{
  "path": "https://example.com/face_or_image.jpg",
  "opts": "402,486:614,489:511,626:506,702"
}

组装规则建议：

• sourceImage： 推荐使用检测返回的 face_urls[i] 作为 path，landmarks_str[i] 作为 opts
• targetImage： 可使用同一张目标图 URL 作为每项 path，并用目标侧对应人脸的 landmarks_str[i] 作为 opts
• 保证 sourceImage[i] 与 targetImage[i] 是同一组替换关系

组装示例：

{
  "sourceImage": [
    {
      "path": "https://example.com/faces/source_face_0.jpg",
      "opts": "402,486:614,489:511,626:506,702"
    }
  ],
  "targetImage": [
    {
      "path": "https://example.com/group_target.jpg",
      "opts": "120,85:180,88:150,130:150,165"
    }
  ],
  "face_enhance": true
}

---

场景一：单人换脸（自动关键点检测）

适用于源图和目标图均只有一张人脸的场景。此时 sourceImage 和 targetImage 可直接使用字符串。

请求示例

{
  "sourceImage": "https://example.com/source.jpg",
  "targetImage": "https://example.com/target.jpg",
  "face_enhance": false
}

行为说明

• 当 sourceImage 或 targetImage 为字符串时，校验层会自动转换为：
  • [{"path": "<value>", "opts": ""}]
• opts 为空字符串表示未手动传关键点。
• 管线将进入自动关键点检测流程（单对人脸处理）。

---

场景二：多人换脸（手动关键点映射）

适用于需要显式指定人脸对应关系的场景。此时应同时传入 sourceImage 与 targetImage 的对象数组，并严格按索引建立映射关系：sourceImage[0] 对应 targetImage[0]，sourceImage[1] 对应 targetImage[1]，依此类推。

补充说明：sourceImage 可以传入多张不同的源图片，用于提供多个人脸来源；但 targetImage 应保持为同一张目标图片。最终生成结果会统一基于这张 targetImage 输出。

请求示例

{
  "sourceImage": [
    {
      "path": "https://example.com/source_face_1.jpg",
      "opts": "145.2,210.8:188.1,209.6:166.7,241.3:165.9,272.4"
    },
    {
      "path": "https://example.com/source_face_2.jpg",
      "opts": "320.4,198.2:360.8,197.0:340.2,228.1:339.7,258.6"
    }
  ],
  "targetImage": [
    {
      "path": "https://example.com/target.jpg",
      "opts": "512.1,301.4:548.9,299.8:530.0,330.2:529.0,360.5"
    },
    {
      "path": "https://example.com/target.jpg",
      "opts": "710.2,288.6:748.7,287.1:729.9,317.7:729.1,349.2"
    }
  ],
  "face_enhance": true
}

行为说明

• 管线以 zip(sourceImage, targetImage) 方式逐对处理，即两个数组会按相同索引一一配对。
• 多对处理时，每一对都应在源图和目标图两侧提供有效 opts。
• 若关键点缺失或格式异常，可能触发运行时校验错误。

---

参数与返回值详解

请求参数

顶层字段

参数	类型	必填	说明
sourceImage	string | ImageWithKeypoints[]	是	源图输入。字符串用于单人自动模式；对象数组用于多人精确模式。
targetImage	string | ImageWithKeypoints[]	是	目标图输入。字符串用于单人自动模式；对象数组用于多人精确模式。
face_enhance	boolean	否	面部优化开关，仅支持布尔值。

ImageWithKeypoints 结构

字段	类型	必填	说明
path	string	是	图片 URL 或本地路径。
opts	string	否	关键点字符串，格式为 "x1,y1:x2,y2:x3,y3:x4,y4"。空字符串表示不传手动关键点。

校验规则与常见错误

face_enhance

• 接受：true / false
• 拒绝：任意整数（包括 0 / 1）及其他非布尔类型

sourceImage / targetImage

• 支持字符串输入，内部会自动转为单元素对象数组。
• 数组输入必须符合 ImageWithKeypoints 结构。
• 多人模式下建议两侧数组长度一致并按索引对齐。

opts

• 格式必须满足 x,y:x,y:...
• 点位之间使用 : 分隔，每个点使用 x,y 表示
• 多人模式下每一对都必须提供非空 opts

---

参数对输出结果的影响

参数组合	对结果的影响
sourceImage/targetImage 为字符串	进入单人自动模式，系统自动检测关键点。
sourceImage/targetImage 为对象数组 + 有效 opts	进入多人精确模式，按索引一一配对换脸。
face_enhance: true	启用面部优化，通常可提升面部观感。
face_enhance: false	不启用额外面部优化，走默认换脸流程。

---

注意事项

1. 多人模式必须对齐： sourceImage[i] 会与 targetImage[i] 配对处理，请保持数组长度和顺序一致。
2. 关键点格式严格： opts 不符合 x,y:x,y:... 时会解析失败。
3. 字符串输入会被自动封装： 若你需要精确控制人脸映射，请显式使用对象数组并传 opts。
4. 建议优先使用公开可访问 URL： 便于服务侧稳定拉取图片资源。