Image FaceSwap Pro

NamiFusion Image FaceSwap Pro

AI Image FaceSwap Pro: Supports single-person automatic face swap and multi-person precise keypoint mapping for highly controllable face swap scenarios.

NamiFusion Image FaceSwap Pro is an image face swap API designed for high-precision scenarios. It supports two input modes: single-person automatic mode (string URL) and multi-person precise mode (object arrays + keypoints), allowing you to balance ease of use and controllability across different business scenarios.

---

Key Features

• Single-Person Automatic Face Swap: Pass sourceImage and targetImage directly as string URLs, and the system automatically detects facial keypoints.
• Multi-Person Precise Mapping: Use ImageWithKeypoints[] and provide keypoints in opts to process pairs one by one by index.
• Optional Face Enhancement: face_enhance only supports boolean values. When enabled, it removes facial blemishes and improves facial appearance.
• Unified Input Structure: Supports both string input and object-array input.

---

Technical Specifications

Parameter	Details
Core input fields	sourceImage, targetImage, face_enhance
Image object structure	ImageWithKeypoints (path + opts)
Single-person mode input	String URL / path
Multi-person mode input	ImageWithKeypoints[] array

---

Quick Start

API Endpoint

Endpoint	Method	Description
/api/v1/marketplace/run/namifusion/faceswap-image-pro	POST	Submit a FaceSwap Pro task
/api/v1/marketplace/run/tasks/{task_uuid}	GET	Query task status and result

Request Parameter Overview

The core FaceSwap Pro fields in the request body are as follows:

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

Authentication

Include your API Key in the request header if required by your service gateway:

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

Standard Call Flow

FaceSwap Pro uses an asynchronous task workflow:

1. Call POST /api/v1/marketplace/run/namifusion/faceswap-image-pro to submit a task.
2. Get the task_uuid from the response.
3. Call GET /api/v1/marketplace/run/tasks/{task_uuid} to poll the task status.
4. When status becomes completed, read the result from output; if it becomes failed, check error_message.

Step 1: Submit the Task

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
    }
  }'

Example successful submission response:

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

Step 2: Query the Result

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"

Example processing response:

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

Example completed response:

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

Example failed response:

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

---

Prerequisite: Call Detect Faces to Build ImageWithKeypoints

In multi-person face swap scenarios, it is recommended to call the face detection API first, obtain the landmarks_str for each face, and then assemble them into the opts field required by FaceSwap Pro.

Step 1: Call Detect Faces

Detection endpoints (async):

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

Request example (detect faces in the target image):

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
    }
  }'

After detection is complete, you can read the following key fields from output.faces_obj["0"]:

• landmarks_str[i]: Can be used directly as opts
• face_urls[i]: Can be used as the cropped single-face image URL, suitable for the source side
• region[i]: Face bounding box information for troubleshooting and visualization

Example detection result snippet:

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

Step 2: Build ImageWithKeypoints

The ImageWithKeypoints structure is:

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

Recommended assembly rules:

• sourceImage: It is recommended to use the returned face_urls[i] as path and landmarks_str[i] as opts
• targetImage: You can use the same target image URL as the path for each item, and use the corresponding target-side landmarks_str[i] as opts
• Ensure that sourceImage[i] and targetImage[i] represent the same replacement pair

Assembly example:

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

---

Scenario 1: Single-Person Face Swap (Automatic Keypoint Detection)

Suitable for scenarios where both the source image and target image contain only one face. In this case, sourceImage and targetImage can be passed directly as strings.

Request Example

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

Behavior

• When sourceImage or targetImage is a string, the validation layer automatically converts it to:
  • [{"path": "<value>", "opts": ""}]
• An empty string in opts means keypoints are not manually provided.
• The pipeline enters the automatic keypoint detection flow for single-pair face processing.

---

Scenario 2: Multi-Person Face Swap (Manual Keypoint Mapping)

Suitable for scenarios where you need to explicitly specify face correspondence. In this case, you should pass object arrays for both sourceImage and targetImage, and establish the mapping strictly by index: sourceImage[0] corresponds to targetImage[0], sourceImage[1] corresponds to targetImage[1], and so on.

Additional note: sourceImage can contain multiple different source images to provide multiple face sources, but targetImage should remain the same target image. The final output is generated based on that single targetImage.

Request Example

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

Behavior

• The pipeline processes pairs using zip(sourceImage, targetImage), meaning the two arrays are paired one by one by the same index.
• For multi-pair processing, each pair should provide valid opts on both the source side and the target side.
• Missing keypoints or invalid keypoint formats may trigger runtime validation errors.

---

Parameter and Return Value Details

Request Parameters

Top-Level Fields

Parameter	Type	Required	Description
sourceImage	string | ImageWithKeypoints[]	Yes	Source image input. A string is used for single-person automatic mode; an object array is used for multi-person precise mode.
targetImage	string | ImageWithKeypoints[]	Yes	Target image input. A string is used for single-person automatic mode; an object array is used for multi-person precise mode.
face_enhance	boolean	No	Face enhancement switch. Only boolean values are supported.

ImageWithKeypoints Structure

Field	Type	Required	Description
path	string	Yes	Image URL or local path.
opts	string	No	Keypoint string in the format "x1,y1:x2,y2:x3,y3:x4,y4". An empty string means no manual keypoints are provided.

Validation Rules and Common Errors

face_enhance

• Accepts: true / false
• Rejects: any integer (including 0 / 1) and other non-boolean types

sourceImage / targetImage

• String input is supported and is automatically converted into a single-element object array internally.
• Array input must match the ImageWithKeypoints structure.
• In multi-person mode, it is recommended that the arrays on both sides have the same length and are aligned by index.

opts

• The format must satisfy x,y:x,y:...
• Points are separated by :, and each point is represented as x,y
• In multi-person mode, each pair must provide a non-empty opts

---

Impact of Parameters on Output

Parameter combination	Impact on result
sourceImage / targetImage as strings	Enters single-person automatic mode, and the system automatically detects keypoints.
sourceImage / targetImage as object arrays + valid opts	Enters multi-person precise mode and swaps faces one by one by index.
face_enhance: true	Enables face enhancement, usually improving facial appearance.
face_enhance: false	Does not enable additional face enhancement and uses the default face swap flow.

---

Notes

1. Arrays must be aligned in multi-person mode: sourceImage[i] will be paired with targetImage[i]. Keep array lengths and order consistent.
2. Keypoint format is strict: If opts does not match x,y:x,y:..., parsing will fail.
3. String input is wrapped automatically: If you need precise control of face mapping, explicitly use object arrays and provide opts.
4. Prefer publicly accessible URLs: This helps the service fetch image resources reliably.