FaceSwap API

The FaceSwap API allows users to seamlessly swap faces between two images. The API processes two input images: the target image where the swap will occur, and the swap image whose face will replace the selected face on the target.

---

Image swapping

Endpoint

URL: https://fapihub.com/v2/faceswap/image/ - Image Swapping Url

Method: POST

---

Authentication

Header:

• token: A valid API token is required to authenticate the request.

---

Request Parameters

Form Data:

Parameter	Type	Description	Required
target_url	string	The URL of the target image where the face will be swapped.	Yes
swap_url	string	The URL of the image containing the face to swap.	Yes
target_face_index	integer	The index of the face in the target image to be replaced (useful for images with multiple faces). In deafault, it is 0	No

---

Example Request

curl -X POST "https://fapihub.com/v2/faceswap/image/" \
  -H "token: API_TOKEN" \
  -F "target_url=https://storage.ws.pho.to/s2/7aa4876bc1f50bc92fc54cb3c326181ac5bbf5ef_m.jpeg" \
  -F "swap_url=https://storage.ws.pho.to/s2/818f3e408ee37c090cf23a3d12e15a08ada80ad9_m.jpeg" \
  -F "target_face_index=0"

---

Example Response

Successful Response (200 OK):

{
  "image_process_response": {
    "request_id": "8de25da8-fa81-4f0f-b6ba-91dbc62e2370",
    "status": "OK",
    "description": null,
    "err_code": "0"
  }
}

Response Parameters:

Parameter	Type	Description
request_id	string	Unique ID for the API request.
status	string	Status of the request (e.g., OK).
description	string	Additional information or null if no description.
err_code	string	Error code (0 indicates no error).

Video Swapping

Endpoint

URL: https://fapihub.com/v2/faceswap/video/ - Video Swapping Url

Method: POST

---

Authentication

Header:

• token: A valid API token is required to authenticate the request.

---

Video FaceSwapping processess only first 4 seconds of the video and below, there is a way to process the whole video

Request Parameters

Form Data:

Parameter	Type	Description	Required
target_url	string	The URL of the target video where the face will be swapped.	Yes
swap_url	string	The URL of the image containing the face to swap.	Yes
target_face_index	integer	The index of the face in the target video to be replaced (useful for images with multiple faces). In default, it is 0	No

---

Exaample Request

curl -X POST "https://fapihub.com/v2/faceswap/video/" \
  -H "token: API_TOKEN" \
  -F "target_url=https://storage.ws.pho.to/s2/7e2131eaef5e5cbb0d2c9eef7e2f19343b5a1292.mp4" \
  -F "swap_url=https://storage.ws.pho.to/s2/818f3e408ee37c090cf23a3d12e15a08ada80ad9_m.jpeg" \
  -F "target_face_index=0"

---

Example Response

Successful Response (200 OK):

{
  "image_process_response": {
    "request_id": "8de25da8-fa81-4f0f-b6ba-91dbc62e2370",
    "status": "OK",
    "description": null,
    "err_code": "0"
  }
}

Response Parameters:

Parameter	Type	Description
request_id	string	Unique ID for the API request.
status	string	Status of the request (e.g., OK).
description	string	Additional information or null if no description.
err_code	string	Error code (0 indicates no error).

Get Result

Endpoint

URL: https://fapihub.com/v2/faceswap/result/ - Get Result

Method: POST

faceswap/result/ is not counted as a request usage. However, on the graph, result/ endpoint usages are added for success and errorsline.

---

Authentication

Header:

• token: A valid API token is required to authenticate the request.

---

Request Parameters

Form Data:

Parameter	Type	Description	Required
request_id	string	The unique ID of the face swap request to retrieve results for.	Yes

---

Example Request

curl -X POST "https://fapihub.com/v2/faceswap/result/" \
  -H "token: API_TOKEN" \
  -F "request_id=REQUEST_ID"

---

Response

Successful Response (200 OK):

{
    "image_process_response": {
        "request_id": "8de25da8-fa81-4f0f-b6ba-91dbc62e2370",
        "status": "OK",
        "duration": "1.439673703s",
        "total_duration": "1.553463687s",
        "result_url": "http://worker-images-6.ws.pho.to/i2/e6d15dd5641c003c27a0c43a24d65aaec19d40ac_result.jpeg",
        "masks": null,
        "answers": null
    }
}

Response Parameters:

Parameter	Type	Description
request_id	string	Unique ID for the original face swap request.
status	string	Status of the request (e.g., OK).
duration	string	Time taken to process the face swap request.
total_duration	string	Total time including network and processing.
result_url	string	URL of the final processed image.
masks	null	Reserved for future use.
answers	null	Reserved for future use.

---

Multiple Face Swapping

When your target image contains multiple people, you may want to swap the face of a specific individual, such as the person in the middle. Is this possible with the FaceSwap API? Absolutely!

To achieve this, the API provides the target_face_index parameter, available exclusively in the image-swapping endpoint. This parameter allows you to specify the face to be replaced by its index.

Key Points:

• Indexing Starts at 0: The first face in the image is assigned an index of 0, the second face is 1, and so on.

• Default Value: If no value is specified, the API automatically uses 0 (the first detected face).

• Ease of Selection: Selecting the correct face might seem tricky, but visualizing indices makes it straightforward.

Example:

In the image below, faces are indexed for clarity. For instance:

• To swap the face of the person in the middle (Index 2 in the first image), set target_face_index=2.

• For the second example, the person with Index 3 can be targeted similarly.

Video Duration

This API processes only the first 4 seconds of any uploaded video. For instance, if you upload a 35-second video, only the first 4 seconds will be processed.

How to Process an Entire Video?

To process the whole video, you need to split it into smaller 4-second segments and upload each segment individually. While this approach increases the number of API requests, it allows for faster processing by leveraging concurrent requests using threading or asynchronous methods.

Once all segments are processed, you can combine the results to cover the entire video. Video splitting can be done using various programming languages. Below is an example in Python using the moviepy library:

from moviepy.editor import VideoFileClip

def split_video_by_4_seconds(input_file, output_folder): 
    video = VideoFileClip(input_file)
    duration = video.duration
    num_clips = int(duration // 4) + (1 if duration % 4 > 0 else 0)

    for i in range(num_clips):
        start_time = i * 4
        end_time = min((i + 1) * 4, duration)
        subclip = video.subclip(start_time, end_time)
        output_filename = f"{output_folder}/clip_{i + 1}.mp4"
        subclip.write_videofile(output_filename, codec="libx264")

    video.close()

# Example usage
input_file = "path/to/your/video.mp4" 
output_folder = "path/to/output/folder" 
split_video_by_4_seconds(input_file, output_folder)

Key Points to Consider:

1. Concurrency: Use threading or asynchronous techniques to send multiple API requests simultaneously, speeding up the processing.

2. Recombination: After obtaining results for all segments, you can recombine them to create the final processed video.

3. Compatibility: Ensure your videos are properly formatted and compatible with the API requirements.

By following this approach, you can efficiently process videos of any length while utilizing the API's capabilities to their fullest.

Usage Notes

• Publicly Accessible URLs: Ensure that target_url and swap_url are publicly accessible

• Multiple Faces: For images with multiple detected faces, use the target_face_index parameter to specify which face to replace. Indexing begins at 0.

• High-Quality Images: For the best results, upload clear, well-lit images. Avoid blurry or obscured faces.

• Video Processing: This API processes up to 4 seconds of video by default. To handle longer videos, split them into 4-second clips and upload them in parallel for faster processing.

• Output Formats: Ensure your input and output files match supported formats (e.g., .jpg, .png, .mp4).

• Error Handling: Use the API’s response codes to manage errors effectively. For example, a 400 status indicates a bad request, while 500 denotes a server-side issue and server errors are also not counted as a request usage

• Threading for Performance: To optimize request handling for multiple images or videos, implement threading or asynchronous processing in your code.

---