name: ai-face-swap-alternative description: "Free AI face swap + cloud AI generation. Local tools: face swap between images using InsightFace (100% free, offline, no API key), face enhance using Real-ESRGAN. Cloud tools: API face swap and AI portrait generation via Atlas Cloud (optional, requires API key). Use when user asks to swap faces, replace faces, face merge, or enhance face quality."

AI Face Swap Alternative — Free & Open Source

2 free local tools + cloud AI features (optional, via Atlas Cloud API).

Local tools run 100% on your machine — no API keys, no cloud, no cost.

Prerequisites

• Python 3.10 - 3.12 installed (3.13 not yet supported by some dependencies)
• uv installed

Available Tools

| Tool | Script | What It Does | API Key? | |------|--------|-------------|----------| | Face Swap | scripts/face-swap.py | Swap faces between images (InsightFace) | No (FREE) | | Face Enhance | scripts/face-enhance.py | Enhance face quality (Real-ESRGAN) | No (FREE) | | Cloud Swap | scripts/cloud-generate.py swap | Cloud face swap via API | Yes | | Cloud Generate | scripts/cloud-generate.py generate | AI portrait generation | Yes |

Usage

Free Local Face Swap (no API key needed)

uv run scripts/face-swap.py source_face.jpg target_image.jpg -o output.jpg

Free Local Face Enhancement

uv run scripts/face-enhance.py input.jpg -o enhanced.jpg

Cloud Face Swap (requires API key)

uv run scripts/cloud-generate.py swap source.jpg target.jpg

Cloud AI Portrait Generation (requires API key)

uv run scripts/cloud-generate.py generate "professional headshot of a person" --model black-forest-labs/flux-2-pro

🔄 AI Face Swap Alternative — Free & Open Source

Free local face swap (InsightFace) + AI enhancement (Real-ESRGAN) + Cloud AI generation (Atlas Cloud)

English | 中文 | 日本語 | 한국어

✨ 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 run and 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: uv will 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

1. Detects all faces in both source and target images
2. Extracts the face embedding from the source image
3. Replaces the selected face in the target image using the inswapper_128 model
4. 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 run handles 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