Face Swap API Overview

​

API Endpoints

​

Face Swap Operations

• Face Swap Plus - ⭐ Recommended Unified API for image and video face swap, supports multi-face
• Face Swap Pro - ⭐ Highest quality image face swap (single face)
• Image Faceswap - Swap faces in images with high quality (V3)
• Video Faceswap - Swap faces in videos with high quality (V3)

​

Result Management

• Get Faceswap Result List - Retrieve faceswap results by IDs
• Delete Faceswap Results - Delete faceswap results by IDs

​

Account Management

• Get User Credit Info - Get faceswap user credit information

​

Utilities

• Face Detect - Detect faces in images and get landmark information (required for v3 APIs)

​

Getting Started

​

Basic Workflow

1. For V3 APIs (Image/Video Faceswap):
   • Use the Face Detect API to detect faces and get landmark data
   • Use the landmarks_str value from the response as the opts parameter
   • Call the Image Faceswap or Video Faceswap API
2. For Face Swap Pro (V4 API) - More Realistic, More Similar:
   • Directly call the Face Swap Pro API without face detection
   • Delivers more realistic and more similar face swap results
   • Only supports single face swapping
3. For Face Swap Plus (V4 API) - Recommended, supports image + video, supports multi-face:
   • Call the Face Swap Plus API
   • Supports both images and videos
   • Supports multiple faces via face_mapping
   • Supports single-face mode via single_face_mode
4. Check Results:
   • Use the Get Result API to check the status of your face swap job
   • Download the result URL when the status is “Success” (status = 3)

​

Response Code Description

​

Face Swap Status Codes

​

Best Practices

​

Image Requirements

• Quality: Use high-resolution images for better results
• Face Visibility: Ensure faces are clearly visible and not obscured
• Lighting: Well-lit images produce better face swap results
• Angle: Frontal or slight angle faces work best

​

Video Requirements

• Duration: Keep videos under 60 seconds for optimal processing time
• Face Count: For best results, limit to 8 or fewer faces
• Resolution: Higher resolution videos may take longer to process
• Encoding: Use standard encoding formats (H.264 recommended)

​

API Usage Tips

• Webhook: Use the webhookUrl parameter to receive notifications when processing is complete
• Face Enhancement: Enable face_enhance for better quality results (may increase processing time)
• Credit Management: Check your credit balance regularly using the Get Credit API
• Result Cleanup: Delete old results using the Delete Result API to keep your account organized

​

Common Use Cases

​

Face Swap Pro - Highest Quality (Image Only)

{
  "sourceImage": [{ "path": "https://example.com/new-face.jpg" }],
  "targetImage": [{ "path": "https://example.com/original.jpg" }],
  "model_name": "akool_faceswap_image_hq",
  "face_enhance": false
}

​

Face Swap Plus - Multi-Face, Image + Video

{
  "source_url": "https://example.com/new-face.jpg",
  "target_url": "https://example.com/group-photo.jpg",
  "model_style": "realistic",
  "face_enhance": false,
  "single_face_mode": false,
  "face_mapping": [
    {
      "source_face_info": { "face_url": "https://example.com/source-1.jpg" },
      "target_face_info": { "face_url": "https://example.com/target-1.jpg" }
    },
    {
      "source_face_info": { "face_url": "https://example.com/source-2.jpg" },
      "target_face_info": { "face_url": "https://example.com/target-2.jpg" }
    }
  ]
}

​

Multiple Face Swap (V3 Required)

1. Detect all faces using Face Detect API
2. Provide the opts parameter for each face
3. Ensure source and target arrays are properly aligned

​

Video Face Swap

1. Detect faces in a representative frame
2. Provide face landmarks for both source and target
3. Monitor processing status as video face swaps take longer

​

Support

• GitHub Demo
• Authentication Guide
• Webhook Documentation