Face2Face

Face2Face is an open-source library that swaps faces in images and videos from a single reference image. It uses the Insightface inswapper backbone, with optional GPEN or GFPGAN restoration. No training step is needed. You run it yourself; it is not a hosted Socaity model.

github.com/SocAIty/face2face · open-source, self-host or deploy via APIPod

No hosted face-swap model exists in the Socaity catalog. Face swapping lives in face2face, an open-source SocAIty library you self-host or deploy yourself via APIPod. Install it from github.com/SocAIty/face2face. For a hosted face capability, see Face Restoration, which runs the hosted tencentarc/gfpgan model.

Runs on your hardware. Face2Face runs locally; no SOCAITY_API_KEY is involved and no credits are charged. CPU works, but use a GPU with at least 8 GB of VRAM for video. Allow at least 5 GB of RAM. Models download automatically on first use.

Capabilities

Face2Face exposes a few call shapes against the same underlying swap engine. Use swap_img_to_img for two-image swaps, swap_video for video files, add_face to register a named embedding ahead of time, and the generic swap entry point when the input may be either an image or a video and you want to address faces by name. Choose restoration per call (GPEN BFR at 256, 512, 1024, or 2048 pixels, or GFPGAN 1.4); the default is gpen_bfr_512. Pass enhance_face_model=None to skip restoration.

Install

Install the open-source package from PyPI. Use the [full] extra if you want to run it as a web service; for plain in-script inference the base package is enough.

# Open-source, self-host. Not part of the hosted Socaity catalog.
pip install socaity-face2face

# Add the [full] extra to run it as a web service:
pip install "socaity-face2face[full]"

Quick start

Swap the face from a source image onto a target image. The default gpen_bfr_512 restoration cleans up the inswapper output, so you do not need a separate restoration pass. The call returns an ImageFile directly; save it to disk. Supply your own source.jpg and target.jpg in the working directory.

from face2face import Face2Face

f2f = Face2Face()

# swap_img_to_img returns an ImageFile directly (runs locally, no API key).
swapped = f2f.swap_img_to_img(
    source_image="source.jpg",
    target_image="target.jpg",
    enhance_face_model="gpen_bfr_512",
)

swapped.save("swapped.jpg")

Methods

Each method returns the swapped media directly: an ImageFile for image swaps, a VideoFile for video swaps. Call .save(path) to write the result to disk.

swap_img_to_img(source_image, target_image, enhance_face_model="gpen_bfr_512") -> ImageFile

Swap faces between two images. Takes the face(s) from source_image and places them onto target_image.

Parameter	Type	Default	Description
`source_image`	`ImageFile \| str \| np.ndarray`	`required`	Image containing the face to swap from.
`target_image`	`ImageFile \| str \| np.ndarray`	`required`	Image to swap the face onto.
`enhance_face_model`	`str \| None`	`"gpen_bfr_512"`	Face restoration model. Options: gpen_bfr_256, gpen_bfr_512, gpen_bfr_1024, gpen_bfr_2048, gfpgan_1.4. None disables restoration.

swap(media, faces=None, enhance_face_model="gpen_bfr_512", include_audio=True) -> ImageFile | VideoFile

Unified swap on an image or video. Pass a registered name, an image path, or a {source: target} dict for faces. Returns an ImageFile or VideoFile depending on the input media.

Parameter	Type	Default	Description
`media`	`str \| ImageFile \| VideoFile \| np.ndarray \| tuple \| list`	`required`	Image or video to apply the swap to.
`faces`	`str \| dict \| list \| Face \| ImageFile`	`None`	Face reference. str: registered name or path. dict: {source_name: target} pairs. list: multiple faces (left to right).
`enhance_face_model`	`str \| None`	`"gpen_bfr_512"`	Face restoration model applied after swapping. None disables it.
`include_audio`	`bool`	`True`	For video media, whether to keep the original audio in the output.

swap_video(video, faces, enhance_face_model=None, include_audio=True) -> VideoFile

Swap faces in a video file. Audio is preserved by default.

Parameter	Type	Default	Description
`video`	`VideoFile \| str`	`required`	Video to apply the swap to.
`faces`	`str \| dict \| list \| Face`	`required`	Face reference. Same format as swap().
`enhance_face_model`	`str \| None`	`None`	Face restoration model applied to each frame. None (the default here) disables it.
`include_audio`	`bool`	`True`	Whether to include the original audio in the output video.

add_face(face_name, media, save=False) -> tuple | dict

Register a reference face from an image. For multi-person images, pass a list of names; embeddings are created left to right.

Parameter	Type	Default	Description
`face_name`	`str \| list[str]`	`required`	Name(s) to assign. Single string for one face; list for multiple faces in the same image (left to right).
`media`	`ImageFile \| str \| np.ndarray \| MediaFile`	`required`	Image to extract the face(s) from, or a media file containing an embedding.
`save`	`bool`	`False`	Persist the embedding to disk in the _face_embeddings folder. When False, it is held in memory only.

Source

Face2Face is open source. The GitHub repository carries the authoritative install instructions, runnable examples, and the option to deploy the swap engine as a web service. Treat its README as the source of truth when this page lags behind a release.

Next steps

Face Restoration: the closest hosted face capability, running tencentarc/gfpgan on Socaity's cloud.
Deploy on APIPod: wrap a self-host model like face2face as your own serverless endpoint.
Python SDK reference: the hosted catalog client contract for models that do run on Socaity's cloud.

SpeechCraft

Audio-Driven Face Video