Face Swap API Overview

Comprehensive guide to the Face Swap API

The resources (image, video, voice) generated by our API are valid for 7 days. Please save the relevant resources as soon as possible to prevent expiration.

Experience our face swap technology in action by exploring our interactive demo on GitHub: AKool Face Swap Demo.

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

Please note that if the value of the response code is not equal to 1000, the request has failed or encountered an error.

Code	Description
1000	Success
1003	Parameter error or Parameter cannot be empty
1005	Operation is too frequent
1006	Your quota is not enough
1007	The number of people who can have their faces changed cannot exceed 8
1101	Invalid authorization or The request token has expired
1102	Authorization cannot be empty
1200	The account has been banned

Face Swap Status Codes

When checking results, the faceswap_status field indicates the current state:

Status	Description
1	In Queue - Your request is waiting to be processed
2	Processing - Face swap is currently being generated
3	Success - Face swap completed, result URL is available
4	Failed - Face swap failed, please check your input images

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)

Use the Face Swap Pro API for the most realistic and similar results with the simplest implementation:

{
  "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)

Use the V3 Image Faceswap API when you need to swap multiple faces in one image:

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

Use the Video Faceswap API for video content:

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

For additional help and examples, check out our:

• GitHub Demo
• Authentication Guide
• Webhook Documentation