如何使用 图片换脸 Pro API：换脸接入指南（2026）

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

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

核心特性

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

技术规格

快速开始

API 端点

请求参数总览

请求体中与 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"
}