namifusion Image Face Swap

NamiFusion Image FaceSwap

AI Image Face Swap: Supports single-person automatic face swap and multi-person precise mapping, combined with face detection for a complete face swap workflow.

NamiFusion Image FaceSwap is a high-quality AI image face swap service that replaces source faces onto target images. It offers two modes: single-person face swap (automatic mode) and multi-person face swap (precise mapping mode), and can be combined with NamiFusion Detect Faces to achieve a complete workflow from face detection to face swapping.

---

Key Features

• Single-Person Face Swap: Enable single_face_mode to automatically complete the face swap without any additional configuration.
• Multi-Person Precise Mapping: Use face_mapping to precisely specify the correspondence between source faces and target faces, supporting one-to-one and many-to-many mappings.
• Face Enhancement: Optional advanced beautification that automatically smooths skin and removes facial blemishes, improving post-swap face quality.
• Async Tasks: Returns a task_uuid after submission; retrieve results via polling or Webhook.

---

Technical Specifications

Parameter	Details
Model ID	namifusion/faceswap-image
Request Method	Async POST (submit task + poll/Webhook for results)
Input	Source face image URL + target image URL
Output	Face-swapped image URL
Processing Time	Typically 5~15 seconds

---

Quick Start

API Endpoints

Endpoint	Method	Description
/api/v1/marketplace/run/namifusion/faceswap-image	POST	Submit a face swap task
/api/v1/marketplace/run/tasks/{task_uuid}	GET	Query task status and results

Authentication

Include your API Key in the request header:

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

---

Scenario 1: Single-Person Face Swap (Simplest Usage)

Suitable for scenarios where both the source image and target image contain only one face. With single_face_mode enabled, no face_mapping configuration is needed, and the service will automatically complete the face swap.

Step 1: Submit Face Swap Task

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-image" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_url": "https://example.com/source_face.jpg",
      "target_url": "https://example.com/target_photo.jpg",
      "single_face_mode": true
    }
  }'

Response Example:

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

Step 2: Poll Task Status

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"

Processing:

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

Completed:

{
  "task_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model_id": "namifusion/faceswap-image",
  "status": "completed",
  "output": {
    "videos": ["https://cdn.namifusion.com/result/faceswap_abc123.jpg"]
  },
  "cost_credits": 10,
  "created_at": "2026-02-27T10:00:00Z",
  "completed_at": "2026-02-27T10:00:12Z"
}

The output field is named videos, but for image face swap it returns image URLs. This field name is unified for storing face swap result files.

---

Scenario 2: Multi-Person Face Swap

When the target image contains multiple faces and you need precise control over "which source face replaces which target face", you need to first call Detect Faces to get face information, then build face_mapping to submit the face swap task.

Step 1: Detect Faces in the Target Image

Call NamiFusion Detect Faces (POST /api/v1/marketplace/run/namifusion/detect_faces) to submit a detection task, then poll for results.

Submit Detection Task:

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_photo.jpg",
      "return_face_url": true
    }
  }'

Poll Task Result:

curl -X GET "https://www.namifusion.com/api/v1/marketplace/run/tasks/{task_uuid}" \
  -H "X-API-Key: sk-your-api-key"

Completed Response (assuming 3 faces detected):

{
  "task_uuid": "...",
  "status": "completed",
  "output": {
    "error_code": 0,
    "error_msg": "SUCCESS",
    "faces_obj": {
      "0": {
        "region": [[50, 80, 150, 200], [250, 70, 350, 190], [450, 90, 550, 210]],
        "face_urls": [
          "https://s3.amazonaws.com/faces/target_face_0.jpg",
          "https://s3.amazonaws.com/faces/target_face_1.jpg",
          "https://s3.amazonaws.com/faces/target_face_2.jpg"
        ],
        "landmarks": [[[...]], [[...]], [[...]]],
        "frame_time": null,
        "crop_region": [[...], [...], [...]],
        "landmarks_str": ["...", "...", "..."],
        "crop_landmarks": ["...", "...", "..."]
      }
    }
  }
}

Now you know the target image has 3 faces (faces_obj["0"].region length is 3) and their face_urls.

Step 2: Detect Source Face Image

Similarly, call Detect Faces to submit a detection task and poll for results (if you have multiple source face images or need to pass precise face coordinate information).

Submit Detection Task:

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/source_face.jpg",
      "return_face_url": true
    }
  }'

Completed Response:

{
  "task_uuid": "...",
  "status": "completed",
  "output": {
    "error_code": 0,
    "error_msg": "SUCCESS",
    "faces_obj": {
      "0": {
        "region": [[100, 50, 200, 180]],
        "face_urls": ["https://s3.amazonaws.com/faces/source_face_0.jpg"],
        "landmarks": [[[...]]],
        "frame_time": null,
        "crop_region": [[...]],
        "landmarks_str": ["..."],
        "crop_landmarks": ["..."]
      }
    }
  }
}

Step 3: Build face_mapping

Based on the detection results, build the mapping from source faces to target faces. Here, the images in source_face_info.face_url and target_face_info.face_url each contain only one face.

Use the face_urls returned by Detect Faces as source_face_info.face_url and target_face_info.face_url in face_mapping:

"face_mapping": [
  {
    "source_face_info": {
      "face_url": "https://s3.amazonaws.com/faces/source_face_0.jpg"
    },
    "target_face_info": {
      "face_url": "https://s3.amazonaws.com/faces/target_face_1.jpg"
    }
  }
]

The face_url values are taken directly from the output.faces_obj["0"].face_urls[i] returned by Detect Faces in Steps 1 and 2.

face_mapping also supports source_face_index, target_face_index, bbox, and other parameters. See the "face_mapping Details" section below.

Step 4: Submit Multi-Person Face Swap Task

curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/namifusion/faceswap-image" \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_url": "https://example.com/source_face.jpg",
      "target_url": "https://example.com/group_photo.jpg",
      "single_face_mode": false,
      "face_mapping": [
        {
          "source_face_info": {
            "face_url": "https://s3.amazonaws.com/faces/source_face_0.jpg"
          },
          "target_face_info": {
            "face_url": "https://s3.amazonaws.com/faces/target_face_1.jpg"
          }
        }
      ]
    }
  }'

Response:

{
  "task_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "pending",
  "cost_credits": 10
}

Step 5: Get Face Swap Result

Poll the task status until status becomes completed:

curl -X GET "https://www.namifusion.com/api/v1/marketplace/run/tasks/b2c3d4e5-f6a7-8901-bcde-f12345678901" \
  -H "X-API-Key: sk-your-api-key"

Completed Response:

{
  "task_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "model_id": "namifusion/faceswap-image",
  "status": "completed",
  "output": {
    "videos": ["https://cdn.namifusion.com/result/faceswap_def456.jpg"]
  },
  "cost_credits": 10,
  "created_at": "2026-02-27T10:05:00Z",
  "completed_at": "2026-02-27T10:05:14Z"
}

---

Python Full Example: Multi-Person Face Swap Workflow

The following example demonstrates the complete workflow from face detection to multi-person image face swap:

import requests
import time

API_KEY = "sk-your-api-key"
BASE_URL = "https://www.namifusion.com/api/v1/marketplace/run"
HEADERS = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
}

source_url = "https://example.com/source_face.jpg"
target_url = "https://example.com/group_photo.jpg"


def detect_faces(image_url):
    """Submit face detection task and poll for result."""
    task = requests.post(
        f"{BASE_URL}/namifusion/detect_faces",
        headers=HEADERS,
        json={"input": {"url": image_url, "return_face_url": True}},
    ).json()

    while True:
        resp = requests.get(
            f"{BASE_URL}/tasks/{task['task_uuid']}",
            headers=HEADERS,
        ).json()

        if resp["status"] == "completed":
            return resp["output"]
        elif resp["status"] == "failed":
            raise Exception(resp.get("error_message", "Unknown error"))

        time.sleep(3)


# Step 1: detect faces in target image
target_detect = detect_faces(target_url)
target_frame = target_detect["faces_obj"]["0"]

print(f"Target has {len(target_frame['face_urls'])} faces")
for i, face_url in enumerate(target_frame["face_urls"]):
    print(f"  Face {i}: region={target_frame['region'][i]}")

# Step 2: detect faces in source image
source_detect = detect_faces(source_url)
source_frame = source_detect["faces_obj"]["0"]

# Step 3: build face_mapping (replace target face 1 with source face 0)
face_mapping = [
    {
        "source_face_info": {"face_url": source_frame["face_urls"][0]},
        "target_face_info": {"face_url": target_frame["face_urls"][1]},
    }
]

# Step 4: submit faceswap task
task_resp = requests.post(
    f"{BASE_URL}/namifusion/faceswap-image",
    headers=HEADERS,
    json={
        "input": {
            "source_url": source_url,
            "target_url": target_url,
            "single_face_mode": False,
            "face_mapping": face_mapping,
        }
    },
).json()

task_uuid = task_resp["task_uuid"]
print(f"Task submitted: {task_uuid}")

# Step 5: poll for result
while True:
    status_resp = requests.get(
        f"{BASE_URL}/tasks/{task_uuid}",
        headers=HEADERS,
    ).json()

    status = status_resp["status"]
    print(f"Status: {status}")

    if status == "completed":
        result_url = status_resp["output"]["videos"][0]
        print(f"Result: {result_url}")
        break
    elif status == "failed":
        print(f"Failed: {status_resp.get('error_message', 'Unknown error')}")
        break

    time.sleep(5)

---

Parameter and Response Details

Request Parameters

The request body is in JSON format, with all parameters inside the input object:

{
  "input": {
    "source_url": "https://...",
    "target_url": "https://...",
    "single_face_mode": true,
    "face_enhance": false,
    "face_mapping": [],
    "model_style": "realistic"
  }
}

Parameter	Type	Required	Default	Description
source_url	string	Yes	-	Source face image URL (the face to swap onto the target). Must be publicly accessible.
target_url	string	Yes	-	Target image URL (the image to be face-swapped). Must be publicly accessible.
single_face_mode	boolean	No	true	Single face mode. When enabled, face swap is completed automatically without configuring face_mapping.
face_enhance	boolean	No	false	Whether to enable face enhancement. When enabled, automatically smooths skin and removes facial blemishes for higher face quality, but increases processing time.
face_mapping	array	No	null	Face mapping configuration. Only effective when single_face_mode: false. See details below.
model_style	string	No	"realistic"	Face swap style. Options: "realistic", "beautify", "lossless". See the "Impact of Parameters on Output" section.

face_mapping Details

face_mapping is an array where each element defines a mapping from a source face to a target face:

Field	Type	Required	Description
source_face_index	integer	Yes	Index of the face in the source image (0-based, sorted left to right).
target_face_index	integer	Yes	Index of the face in the target image (0-based, sorted left to right).
source_face_info	object	No	Coordinate information of the source face. When provided, skips internal re-detection to ensure consistent face ordering.
target_face_info	object	No	Coordinate information of the target face. When provided, improves matching accuracy.

source_face_info Fields

Field	Type	Description
bbox	number[]	Face bounding box [x1, y1, x2, y2].
kps	number[][]	5 facial keypoint coordinates. When provided, the backend uses them directly, skipping re-detection.

target_face_info Fields

Field	Type	Description
bbox	number[]	Target face bounding box [x1, y1, x2, y2].

Task Status

After submitting a task, poll for status. Recommended polling interval: 5 seconds.

Status	Description
pending	Task created, waiting to be processed.
processing	Task is being processed.
completed	Task completed. Retrieve result URL from output.videos.
failed	Task failed. Check error_message for the reason.

Response Structure

Task Submission Response

Field	Type	Description
task_uuid	string	Unique task identifier for subsequent status queries.
status	string	Initial status, typically pending.
cost_credits	number	Credits consumed by this task.

Task Completion Response

Field	Type	Description
task_uuid	string	Unique task identifier.
model_id	string	Model ID (namifusion/faceswap-image).
status	string	Task status.
output.videos	string[]	List of face-swapped result image URLs.
cost_credits	number	Credits consumed.
created_at	string	Task creation time (ISO 8601).
completed_at	string	Task completion time (ISO 8601).
error_message	string	Error message (only returned when failed).

---

Impact of Parameters on Output

Parameter	Impact on Result
single_face_mode: true	Automatically completes face swap, suitable for single-person scenarios without configuring face_mapping.
single_face_mode: false + face_mapping	Precisely controls which faces to replace. Faces not specified in the mapping remain unchanged.
face_enhance: true	Enables face enhancement, automatically smoothing skin and removing blemishes for a more refined and natural look, but increases processing time by ~20-50%.
face_enhance: false	Default mode, no additional face processing, faster processing speed.
model_style: "realistic"	Realistic style. Produces a natural look close to real faces, preserving lifelike skin tones and textures.
model_style: "beautify"	Beautify style. Automatic skin smoothing and brightening for a refined, smooth appearance.
model_style: "lossless"	Lossless style. Ultimate lossless mode that perfectly preserves all original facial details with the highest realism, nearly indistinguishable.

---

Notes

1. URLs must be publicly accessible: Both source_url and target_url must be publicly downloadable URLs.
2. Face index sorting rule: Both source_face_index and target_face_index start from 0, sorted left to right by the x-coordinate of the face bbox's top-left corner.
3. Strongly recommended to pass face_info: If you have already called Detect Faces, passing the detected bbox into face_mapping can avoid index inconsistency issues caused by internal re-detection in the face swap service.
4. Polling interval: Recommended to poll task status every 5 seconds. Image face swap typically completes in 5~15 seconds.
5. Result field name: The output field is named output.videos, but for image face swap it returns image URLs. This is a unified naming convention for the API.