Face Swap in 10 Lines

Use the face2face module to swap a face between two images, extract face embeddings for reuse, and swap faces in video — all from Python.

Uses: face2face (Socaity-hosted, official). One-shot face swap with Insightface inswapper and optional GFPGAN / GPEN restoration. Live playground at socaity.ai/APIs/service/face2face.

The face2face module ships inside the socaity package. One install covers all models.

pip install socaity

Import and instantiate the module with your API key. The client is reusable across calls.

import os
from socaity import face2face

f2f = face2face(api_key=os.getenv("SOCAITY_API_KEY"))

swap_img_to_img takes a source face image and a target image, and pastes the source face onto every face detected in the target. The SDK accepts local paths, URLs, raw bytes, PIL Images, and numpy arrays.

result = f2f.swap_img_to_img(
    source_img="./my_face.jpg",   # face to transplant
    target_img="./photo.jpg",     # image to swap onto
).get_result()

result.save("swapped.jpg")
print("Saved swapped.jpg")

add_face registers a face image under a name and returns its embedding. Once registered, you can pass the name as the faces argument in subsequent calls — no re-upload required.

# 1. Register the face once — assigns a name and extracts the embedding
embedding = f2f.add_face(
    image="./my_face.jpg",
    face_name="my_face",
    save=True,             # persist server-side for later sessions
).get_result()

# 2. Reuse by name — no re-upload needed
result = f2f.swap_img_to_img(
    source_img="my_face",          # use the registered name directly
    target_img="./another_photo.jpg",
).get_result()

result.save("swapped_from_embedding.jpg")

swap_video applies the face swap frame-by-frame. For long videos, the job runs asynchronously on GPU — submit it and call .get_result() when you are ready to collect the output.

job = f2f.swap_video(
    faces="./my_face.jpg",
    target_video="./clip.mp4",
)

# Do other work while the GPU processes frames...

video = job.get_result()
video.save("swapped_video.mp4")
print("Video saved!")

// The JavaScript SDK is in early development.
// High-level model methods are coming soon.
// For now, use the Python SDK for full model access.

import { socaity } from "socaity"

socaity.setApiKey(process.env.SOCAITY_API_KEY)
const models = await socaity.getAvailableModels()
console.log("Available models:", models)

Key parameters you will adjust in practice. Defaults apply when omitted.

• Use a well-lit, front-facing source image for the highest swap quality.
• The model detects all faces in the target — use face_index to target a specific person.
• For video, 720p / 30fps is the sweet spot for speed vs. quality on a single GPU.
• Pre-extract embeddings in bulk and cache them; you pay for inference, not storage.

• Swapped a face between two images with swap_img_to_img
• Registered a face with add_face and reused it by name to skip re-upload
• Applied a face swap to an entire video with swap_video
• Learned the equivalent JavaScript API