Face2Face

You can interact with the service using any HTTP client (e.g., requests, httpx, curl). The service provides endpoints for swap, add_face, and enhance_face functionality.

1. Submit a request

First, load your image as bytes, then send a POST request to the desired endpoint. For example, to use add-face:

import requests

# load images from disc
with open("myimage.jpg", "rb") as image:
    my_image = image.read()

submit = requests.post(
    "http://localhost:8020/add-face",
    files={"image": ("face.jpg", my_image, "image/jpeg")},
    data={"face_name": "biden"},
)
my_job = submit.json()

2. Poll for results and parse the response

Use the job_id from the initial response to poll the /status/{job_id} endpoint. Once the job is finished, the response will contain the result (a media payload) and metrics.

import requests

# check status of job
status = requests.get(f"http://localhost:8020/status/{my_job['job_id']}").json()

# Access execution metrics
metrics = status.get("metrics", {})
print("execution_time_s:", metrics.get("execution_time_s"))

# Retrieve the result image
result = status.get("result", {})
image_url = result.get("content")

if image_url:
    image_bytes = requests.get(image_url, timeout=60).content
    with open("swapped_img.png", "wb") as f:
        f.write(image_bytes)

import requests

# 1. Submit request
with open("myimage.jpg", "rb") as image:
    my_image = image.read()

submit = requests.post(
    "http://localhost:8020/add-face",
    files={"image": ("face.jpg", my_image, "image/jpeg")},
    data={"face_name": "biden"},
)
my_job = submit.json()

# 2. Poll status
status = requests.get(f"http://localhost:8020/status/{my_job['job_id']}").json()

# 3. Parse result
result = status.get("result", {})
image_url = result.get("content")
if image_url:
    image_bytes = requests.get(image_url, timeout=60).content
    with open("swapped_img.png", "wb") as f:
        f.write(image_bytes)

Because the underlying swap model (inswapper) operates at low resolution, you can use face enhancement models to upscale and improve portrait quality.

Available Models:

• gfpgan_1.4
• gpen family (e.g., gpen_bfr_512). The GPEN model can upscale up to 2048, providing higher quality at the cost of higher runtime.

Usage:

• During swapping: Pass enhance_face_model to the swap method. The model is automatically downloaded.
• Standalone enhancement: Use enhance_faces for all faces in an image, or enhance_single_face for a specific detected face.

# enhance during swap
swapped_img = f2f.swap(media="path/to/my_img_or_video.mp4", enhance_face_model='gpen_bfr_512')

# enhance all faces in an image
enhanced_img = f2f.enhance_faces(image="path/to/my_img.jpg", enhance_face_model='gpen_bfr_512')

# enhance a specific face
target_img = cv2.imread("path/to/my_img.jpg")
detected_face = f2f.detect_faces(target_img)[0]
enhanced_img = f2f.enhance_single_face(target_img, detected_face, enhance_face_model='gpen_bfr_512')

For processing large batches of images or video frames efficiently, use the generator-based methods. These allow you to yield images (e.g., from cv2.imread) and receive swapped images iteratively.

• swap_to_face_generator: Swaps a specific face embedding onto a stream of target images.
• swap_pairs_generator: Performs recognition-based pair swapping on a stream of target images.

import cv2

def my_image_generator():
  for i in range(100):
    yield cv2.imread(f"image_{i}.jpg")

# for swapping to always the same face
for swapped_img in f2f.swap_to_face_generator(faces="my_embedding", target_img_generator=my_image_generator()):
  cv2.imshow("swapped", swapped_img)
  cv2.waitKey(1)

# including face recognition
for swapped_img in f2f.swap_pairs_generator(target_img_generator=my_image_generator(), swap_pairs={"trump": "hagrid"}):
  cv2.imshow("swapped", swapped_img)
  cv2.waitKey(1)