🔄 AI Face Swap Alternative — Free & Open Source
Free local face swap (InsightFace) + AI enhancement (Real-ESRGAN) + Cloud AI generation (Atlas Cloud)
✨ Why This Skill?
- 🆓 100% FREE local face swap — no API key, no cloud, no cost
- 🔒 Privacy first — all processing happens on your machine, nothing gets uploaded
- ⚡ One command —
uv runand go, dependencies auto-install - 🎭 High quality — InsightFace (inswapper_128) + Real-ESRGAN enhancement
- ☁️ Optional cloud features — API face swap + AI portrait generation via Atlas Cloud
- 🤖 AI Agent ready — works with Claude Code, Cursor, Windsurf, and other AI coding tools
- 💰 Save money — free alternative to FaceApp ($4.99/mo), Reface ($12.99/mo), DeepSwap ($9.99/mo)
📦 Installation
1. Add the Skill
npx skills add ristponex/ai-face-swap-alternative-skill
This installs the skill so AI agents (Claude Code, Cursor, etc.) can use it automatically.
2. Prerequisites
- Python 3.10 - 3.12 (3.13 is not yet supported by some dependencies)
- uv — Python package manager (auto-manages Python versions)
If you don't have uv installed:
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Note:
uvwill automatically download and manage the correct Python version if needed. You don't need to install Python separately.
3. Cloud Setup (Optional)
Cloud features (API face swap & AI generation) require an Atlas Cloud API key. Local tools work without any API key.
cp .env.example .env
# Edit .env and add your API key
Get your API key at atlascloud.ai
🆓 Free Local Tools
Face Swap (scripts/face-swap.py)
Swap faces between two images using InsightFace (inswapper_128 model). Runs 100% locally — no API key, no internet connection needed after first model download.
Powered by:
- InsightFace — State-of-the-art face analysis library
- inswapper_128 model — High-quality face swapping (auto-downloaded on first run)
- ONNX Runtime — Cross-platform inference engine
Basic Usage
uv run scripts/face-swap.py --source face.jpg --target photo.jpg -o output.jpg
Options
| Flag | Description | Default |
|---|---|---|
--source |
Source face image (the face to use) | Required |
--target |
Target image (the face to replace) | Required |
-o, --output |
Output file path | ./output/<target>_swapped.png |
--face-index |
Which face in target to swap (for group photos) | 0 |
Examples
Simple face swap:
uv run scripts/face-swap.py --source celebrity.jpg --target selfie.jpg -o result.jpg
Group photo — swap specific face:
# Swap the third face (index starts at 0)
uv run scripts/face-swap.py --source face.jpg --target group.jpg --face-index 2 -o result.jpg
How It Works
- Detects all faces in both source and target images
- Extracts the face embedding from the source image
- Replaces the selected face in the target image using the inswapper_128 model
- Saves the output with the swapped face seamlessly blended
Face Enhance (scripts/face-enhance.py)
Enhance face and image quality using Real-ESRGAN with NCNN backend. Great for restoring old photos, fixing blurry faces, and improving image details.
Powered by:
- Real-ESRGAN — Practical image restoration model
- NCNN backend — Fast inference, works on CPU and GPU
Basic Usage
uv run scripts/face-enhance.py input.jpg -o enhanced.jpg
Options
| Flag | Description | Default |
|---|---|---|
input |
Input image path or folder | Required |
-o, --output |
Output directory | ./output/ |
--mode |
enhance (detail boost, keep size) or upscale (4x enlarge) |
enhance |
--sharpness |
Sharpness factor (1.0 = unchanged) | 1.3 |
--contrast |
Contrast factor (1.0 = unchanged) | 1.1 |
--gpu |
GPU ID (-1 for CPU) | 0 |
Examples
Enhance a single image (keep original size, boost details):
uv run scripts/face-enhance.py old_photo.jpg -o restored/
4x upscale:
uv run scripts/face-enhance.py low_res.jpg --mode upscale -o output/
Batch processing a folder:
uv run scripts/face-enhance.py ./photos/ -o ./enhanced_photos/
Fine-tune sharpness and contrast:
uv run scripts/face-enhance.py portrait.jpg --sharpness 1.5 --contrast 1.2
CPU-only processing:
uv run scripts/face-enhance.py input.jpg --gpu -1
Enhancement Modes
| Mode | What It Does | Output Size |
|---|---|---|
enhance |
Upscales with Real-ESRGAN then downscales back, boosting detail and removing artifacts | Same as input |
upscale |
4x super-resolution enlargement | 4x input size |
☁️ Cloud Features (Optional)
Cloud features require an Atlas Cloud API key. They're useful when you want faster processing, don't have a GPU, or need AI-generated portraits.
Cloud Face Swap
API-based face swap using the atlascloud/image-face-swap model. No local GPU required — processing happens in the cloud.
uv run scripts/cloud-generate.py swap source.jpg target.jpg -o output/
When to use cloud swap vs local swap:
| Local (face-swap.py) | Cloud (cloud-generate.py swap) | |
|---|---|---|
| Cost | Free | Pay per use |
| Privacy | 100% local | Images sent to API |
| Speed | Depends on CPU/GPU | Fast, server-side |
| Setup | Auto (first run downloads model) | API key needed |
| Offline | Works offline | Requires internet |
AI Portrait Generation
Generate AI portraits, headshots, or any image using any model available on Atlas Cloud (Flux, Seedream, Stable Diffusion, etc.).
# Generate with Flux 2 Pro
uv run scripts/cloud-generate.py generate "professional headshot of a young woman, studio lighting" \
--model black-forest-labs/flux-2-pro
# Generate with a specific size
uv run scripts/cloud-generate.py generate "cinematic portrait, dramatic lighting" \
--model black-forest-labs/flux-2-pro --size 1024x1024
# Pass extra model-specific parameters
uv run scripts/cloud-generate.py generate "portrait painting, oil on canvas style" \
--model black-forest-labs/flux-2-pro --extra '{"num_inference_steps": 30}'
Generation Options
| Flag | Description | Default |
|---|---|---|
prompt |
Text description of the image to generate | Required |
--model |
Model ID on Atlas Cloud | black-forest-labs/flux-2-pro |
--size |
Image dimensions (e.g., 1024x1024) |
Model default |
--extra |
Additional parameters as JSON string | None |
-o, --output |
Output directory | ./output/ |
💰 Price Comparison vs Paid Apps
Why pay for face swap apps when you can do it for free?
| App | Price | Features |
|---|---|---|
| This Skill (local) | FREE | Face swap + face enhance, unlimited use |
| FaceApp | $4.99/mo | Face swap, filters, aging |
| Reface | $12.99/mo | Face swap, GIF swap |
| DeepSwap | $9.99/mo | Face swap, video swap |
| FaceMagic | $5.99/mo | Face swap, video |
With this skill you get unlimited face swaps and enhancements at zero cost, running entirely on your own machine with full privacy.
🌐 Related Open Source Tools
This skill builds on top of the amazing open source face swap ecosystem. Here are some notable projects:
| Tool | GitHub Stars | Features | Link |
|---|---|---|---|
| Deep-Live-Cam | 80k+ | Real-time webcam face swap, one-click deepfake | github.com/hacksider/Deep-Live-Cam |
| InsightFace | 28k+ | Core face analysis library, ArcFace, inswapper | github.com/deepinsight/insightface |
| FaceFusion | 27k+ | Next-gen face swapper (roop successor), web GUI | github.com/facefusion/facefusion |
| Rope | 5.3k+ | GUI-based face swap tool, easy to use | github.com/Hillobar/Rope |
| VisoMaster | 1.8k+ | New SOTA face swap, VR180 support | github.com/visomaster/VisoMaster |
How this skill differs:
- Designed for AI agents (Claude Code, Cursor) — not just manual GUI use
- Zero-config —
uv runhandles all dependencies automatically - Combined workflow — face swap + enhancement + cloud generation in one package
- Lightweight — no heavy GUI frameworks, just Python scripts
🤖 Using with AI Agents
This skill is designed to work seamlessly with AI coding agents. Once installed, your AI agent can:
- Swap faces between photos with a natural language request
- Enhance blurry or old photos automatically
- Generate AI portraits from text descriptions
Claude Code
# Install the skill
npx skills add ristponex/ai-face-swap-alternative-skill
# Then just ask Claude:
# "S