ALwrity/docs/image studio/IMAGE_STUDIO_FACE_SWAP_IMPLEMENTATION_PLAN.md

Image Studio Face Swap - Implementation Plan

Date: Current Session
Status: ✅ COMPLETE - Backend & Frontend Implemented
Priority: ⭐ HIGH PRIORITY - COMPLETED

---

🎯 Overview

Implement Face Swap Studio for Image Studio, following the same reusable architecture pattern as Editing feature.

Models Integrated (4 models): ✅ COMPLETE

1. ✅ Image Face Swap Pro ($0.025) - Enhanced quality, realistic blending
2. ✅ Image Head Swap ($0.025) - Full head replacement (face + hair + outline)
3. ✅ Akool Image Face Swap ($0.16) - Multi-face swapping (up to 5 faces)
4. ✅ InfiniteYou ($0.03) - High-quality identity preservation (ByteDance zero-shot)

---

🏗️ Architecture (REUSES EXISTING PATTERNS)

Phase 1: Foundation (Same as Editing)

1. Protocol & Options

   • Create FaceSwapOptions dataclass in base.py
   • Create FaceSwapProvider protocol
   • Follow same pattern as ImageEditProvider

2. Unified Entry Point

   • Add generate_face_swap() to main_image_generation.py
   • REUSE: _validate_image_operation() helper
   • REUSE: _track_image_operation_usage() helper
   • Follow same pattern as generate_image_edit()

3. Provider Implementation

   • Create WaveSpeedFaceSwapProvider in wavespeed_face_swap_provider.py
   • REUSE: WaveSpeedClient for API calls
   • REUSE: Polling and download patterns from editing

---

📋 Implementation Steps

Step 1: Protocol & Options ✅ COMPLETE

File: backend/services/llm_providers/image_generation/base.py

Added:

@dataclass
class FaceSwapOptions:
    base_image_base64: str  # Image to swap face into
    face_image_base64: str  # Face to swap
    model: Optional[str] = None
    target_face_index: Optional[int] = None  # For multi-face images
    target_gender: Optional[str] = None  # "all", "female", "male"
    extra: Optional[Dict[str, Any]] = None

class FaceSwapProvider(Protocol):
    def swap_face(self, options: FaceSwapOptions) -> ImageGenerationResult:
        ...

---

Step 2: WaveSpeedFaceSwapProvider Structure ✅ COMPLETE

File: backend/services/llm_providers/image_generation/wavespeed_face_swap_provider.py

Created:

• SUPPORTED_MODELS dict with 5 models
• _validate_options() method
• _call_wavespeed_face_swap_api() method
• Helper methods: get_available_models(), get_models_by_tier()

---

Step 3: Unified Entry Point ✅ COMPLETE

File: backend/services/llm_providers/main_image_generation.py

Added:

def generate_face_swap(
    base_image_base64: str,
    face_image_base64: str,
    model: Optional[str] = None,
    options: Optional[Dict[str, Any]] = None,
    user_id: Optional[str] = None
) -> ImageGenerationResult:
    # 1. REUSE: Validation helper
    _validate_image_operation(...)
    
    # 2. Get provider
    provider = _get_face_swap_provider("wavespeed")
    
    # 3. Prepare options
    face_swap_options = FaceSwapOptions(...)
    
    # 4. Swap face
    result = provider.swap_face(face_swap_options)
    
    # 5. REUSE: Tracking helper
    if user_id and result and result.image_bytes:
        _track_image_operation_usage(...)
    
    return result

---

Step 4: Service Layer ✅ COMPLETE

File: backend/services/image_studio/face_swap_service.py ✅ CREATED

Created:

class FaceSwapService:
    async def process_face_swap(
        self,
        request: FaceSwapRequest,
        user_id: Optional[str] = None
    ) -> Dict[str, Any]:
        # Use unified entry point
        result = generate_face_swap(...)
        # Return normalized response

---

Step 5: API Endpoint ✅ COMPLETE

File: backend/routers/image_studio.py

Added:

@router.post("/face-swap/process")
async def process_face_swap(
    request: FaceSwapRequest,
    current_user: Dict[str, Any] = Depends(get_current_user),
) -> FaceSwapResponse:
    # Call service

---

Step 6: Frontend ✅ COMPLETE

Files Created:

• ✅ frontend/src/components/ImageStudio/FaceSwapStudio.tsx - Main component
• ✅ frontend/src/components/ImageStudio/FaceSwapImageUploader.tsx - Dual image uploader
• ✅ frontend/src/components/ImageStudio/FaceSwapResultViewer.tsx - Side-by-side comparison viewer

Features Implemented:

• ✅ Image uploader (base image + face image) with previews
• ✅ Model selector (reuses ModelSelector from Edit Studio)
• ✅ Auto-detection and recommendations
• ✅ Result viewer with side-by-side comparison
• ✅ Download and reset functionality
• ✅ Route: /image-studio/face-swap
• ✅ Added to Image Studio Dashboard modules

---

📊 Model Registry Structure

SUPPORTED_MODELS = {
    "image-face-swap": {
        "model_path": "wavespeed-ai/image-face-swap",
        "name": "Image Face Swap",
        "cost": 0.01,
        "tier": "budget",
        "features": ["basic_swap"],
        "max_faces": 1,
    },
    "image-face-swap-pro": {
        "model_path": "wavespeed-ai/image-face-swap-pro",
        "name": "Image Face Swap Pro",
        "cost": 0.025,
        "tier": "mid",
        "features": ["enhanced_blending", "realistic"],
    },
    "image-head-swap": {
        "model_path": "wavespeed-ai/image-head-swap",
        "name": "Image Head Swap",
        "cost": 0.025,
        "tier": "mid",
        "features": ["full_head", "hair_included"],
    },
    "akool-face-swap": {
        "model_path": "akool/image-face-swap",
        "name": "Akool Face Swap",
        "cost": 0.16,
        "tier": "premium",
        "features": ["multi_face", "group_photos"],
        "max_faces": None,  # Unlimited
    },
    "infinite-you": {
        "model_path": "wavespeed-ai/infinite-you",
        "name": "InfiniteYou",
        "cost": 0.05,
        "tier": "mid",
        "features": ["identity_preservation", "high_quality"],
    },
}

---

🔄 Reusability Checklist

• Reuse _validate_image_operation() helper
• Reuse _track_image_operation_usage() helper
• Reuse WaveSpeedClient for API calls
• Reuse polling/download patterns
• Follow same provider protocol pattern
• Follow same service layer pattern
• Follow same API endpoint pattern

---

✅ Implementation Summary

Backend ✅ COMPLETE

• ✅ Protocol & Options (FaceSwapOptions, FaceSwapProvider)
• ✅ WaveSpeedFaceSwapProvider with 4 models integrated
• ✅ Unified entry point (generate_face_swap() in main_image_generation.py)
• ✅ FaceSwapService with auto-detection and recommendations
• ✅ API endpoints: /face-swap/process, /face-swap/models, /face-swap/recommend

Frontend ✅ COMPLETE

• ✅ FaceSwapStudio component with full UI
• ✅ FaceSwapImageUploader for dual image upload
• ✅ FaceSwapResultViewer for side-by-side comparison
• ✅ Model selection with auto-detection
• ✅ Integration with useImageStudio hook
• ✅ Route and dashboard integration

Features

• ✅ 4 AI models integrated (Image Face Swap Pro, Image Head Swap, Akool, InfiniteYou)
• ✅ Auto-detection based on image resolution
• ✅ Smart recommendations with explanations
• ✅ Model selection UI with search and filtering
• ✅ Cost transparency and tier-based filtering

---

📝 Next Steps

Face Swap Studio is complete! ✅

Recommended next feature: See Image Studio Enhancement Proposal for next features:

1. Phase 1 Quick Wins: Image Compression, Format Converter, Image Resizer (Pillow/FFmpeg)
2. Phase 2 WaveSpeed: Enhanced Upscale Studio, Image Translation, 3D Studio