Face Swap API Overview

​

API Endpoints

​

Face Swap Operations

• Image Faceswap - Swap faces in images with high quality (supports multiple faces)
• Face Swap Pro - ⭐ NEW More realistic, more similar - Single face only (V4)
• Video Faceswap - Swap faces in videos with high quality

​

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. 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 - More Realistic, More Similar (Single Face Only)

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

​

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