> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akool.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Face Swap API Overview

> Comprehensive guide to the Face Swap API

<Warning>
  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.
</Warning>

<Info>
  Experience our face swap technology in action by exploring our interactive demo on GitHub: [AKool Face Swap Demo](https://github.com/AKOOL-Official/akool-face-swap-demo).
</Info>

## API Endpoints

### Face Swap Operations

* [Face Swap Plus](/ai-tools-suite/faceswap/faceswap-plus) - **⭐ Recommended** Unified API for image and video face swap, supports multi-face
* [Face Swap Pro](/ai-tools-suite/faceswap/image-faceswap-v4) - **⭐** Highest quality image face swap (single face)
* [Image Faceswap](/ai-tools-suite/faceswap/image-faceswap) - Swap faces in images with high quality (V3)
* [Video Faceswap](/ai-tools-suite/faceswap/video-faceswap) - Swap faces in videos with high quality (V3)

### Result Management

* [Get Faceswap Result List](/ai-tools-suite/faceswap/get-result) - Retrieve faceswap results by IDs
* [Delete Faceswap Results](/ai-tools-suite/faceswap/delete-result) - Delete faceswap results by IDs

### Account Management

* [Get User Credit Info](/ai-tools-suite/faceswap/get-credit) - Get faceswap user credit information

### Utilities

* [Face Detect](/ai-tools-suite/faceswap/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](/ai-tools-suite/faceswap/face-detect) to detect faces and get landmark data
   * Use the `landmarks_str` value from the response as the `opts` parameter
   * Call the [Image Faceswap](/ai-tools-suite/faceswap/image-faceswap) or [Video Faceswap](/ai-tools-suite/faceswap/video-faceswap) API

2. **For Face Swap Pro (V4 API)** - More Realistic, More Similar:
   * Directly call the [Face Swap Pro API](/ai-tools-suite/faceswap/image-faceswap-v4) 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](/ai-tools-suite/faceswap/faceswap-plus)
   * 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](/ai-tools-suite/faceswap/get-result) to check the status of your face swap job
   * Download the result URL when the status is "Success" (status = 3)

### Response Code Description

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

| 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](/ai-tools-suite/faceswap/get-credit)
* **Result Cleanup**: Delete old results using the [Delete Result API](/ai-tools-suite/faceswap/delete-result) to keep your account organized

## Common Use Cases

### Face Swap Pro - Highest Quality (Image Only)

Use the [Face Swap Pro API](/ai-tools-suite/faceswap/image-faceswap-v4) (`POST /api/open/v4/faceswap/faceswapByImage`) for the highest quality results:

```json theme={null}
{
  "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

Use the [Face Swap Plus API](/ai-tools-suite/faceswap/faceswap-plus) (`POST /api/open/v4/faceswap/faceswapPlusByImage`) for multi-face or video face swap:

```json theme={null}
{
  "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)

Use the [V3 Image Faceswap API](/ai-tools-suite/faceswap/image-faceswap) when you need to swap multiple faces in one image:

1. Detect all faces using [Face Detect API](/ai-tools-suite/faceswap/face-detect)
2. Provide the `opts` parameter for each face
3. Ensure source and target arrays are properly aligned

### Video Face Swap

**We recommend using [Face Swap Plus API](/ai-tools-suite/faceswap/faceswap-plus)** - single face mode requires no pre-detection, multi-face mode uses Face Detection API for face info.

If you need to use the V3 Video Faceswap API:

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](https://github.com/AKOOL-Official/akool-face-swap-demo)
* [Authentication Guide](/authentication/usage)
* [Webhook Documentation](/ai-tools-suite/webhook)