> ## 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 Plus (Image & Video)

> Multi-face swap for images and videos

<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>

<Tip>
  Face Swap Plus is a unified API that supports both **image** and **video** face swap.

  * **Single Face Mode**: No pre-detection required, just provide source and target URLs
  * **Multi-Face Mode**: Requires [Face Detection API](/ai-tools-suite/face-detection/detect-faces) to get `face_url` and `bbox` for each face
  * For highest quality image face swap (single face only), use [Face Swap Pro](/ai-tools-suite/faceswap/image-faceswap-v4)
  * Video Faceswap API is a V3 legacy API. For new projects, we recommend using this API instead
</Tip>

## Features

Face Swap Plus supports advanced face swapping scenarios:

* **Image and Video**: Unified API for both image and video face swap
* **Multi-Face**: Swap multiple faces at once via `face_mapping`
* **Single Face Mode**: Use `single_face_mode` for simplified single-face swap
* **Style Options**: Choose between `realistic`, `beautify`, or `lossless` styles

## Which API Should I Use?

| Scenario                                      | Recommended API                                             |
| --------------------------------------------- | ----------------------------------------------------------- |
| Highest quality image face swap (single face) | [Face Swap Pro](/ai-tools-suite/faceswap/image-faceswap-v4) |
| Multi-face swap (image/video)                 | Face Swap Plus ✅                                            |
| Video face swap                               | Face Swap Plus ✅ (Recommended)                              |
| V3 compatibility required                     | [Video Faceswap](/ai-tools-suite/faceswap/video-faceswap)   |

## Parameters

### Core Parameters

| Parameter          | Type    | Required | Description                                                        |
| ------------------ | ------- | -------- | ------------------------------------------------------------------ |
| `source_url`       | string  | Yes      | Source (new) face image URL                                        |
| `target_url`       | string  | Yes      | Target material URL (image or video)                               |
| `webhookUrl`       | string  | No       | Callback URL for result notification                               |
| `face_enhance`     | boolean | No       | Enable face enhancement (default: false)                           |
| `model_style`      | string  | No       | `realistic` (default), `beautify`, or `lossless`                   |
| `single_face_mode` | boolean | No       | `false` (default) for multi-face mode, `true` for single-face mode |

### Multi-Face Mode (default)

When `single_face_mode` is `false` (default), use `face_mapping` to define multiple source-target face pairs:

| Parameter                                  | Type      | Required | Description                                                               |
| ------------------------------------------ | --------- | -------- | ------------------------------------------------------------------------- |
| `face_mapping`                             | array     | Yes      | Array of face mapping objects                                             |
| `face_mapping[].source_face_info`          | object    | Yes      | Source face info                                                          |
| `face_mapping[].source_face_info.face_url` | string    | Yes      | Source face image URL                                                     |
| `face_mapping[].source_face_info.bbox`     | number\[] | No       | Bounding box `[x1, y1, x2, y2]`. See [bbox rules](#when-is-bbox-required) |
| `face_mapping[].target_face_info`          | object    | Yes      | Target face info                                                          |
| `face_mapping[].target_face_info.face_url` | string    | No       | Target face image URL                                                     |
| `face_mapping[].target_face_info.bbox`     | number\[] | No       | Bounding box `[x1, y1, x2, y2]`. See [bbox rules](#when-is-bbox-required) |

### Single Face Mode

When `single_face_mode` is `true`, enables simplified single-face swap mode:

| Parameter          | Type    | Required | Description                        |
| ------------------ | ------- | -------- | ---------------------------------- |
| `single_face_mode` | boolean | Yes      | Set to `true` for single-face mode |

### When is bbox required?

The `bbox` parameter in `source_face_info` and `target_face_info` depends on where `face_url` comes from:

| face\_url source                                                                   | bbox required? | Description                                                                                                         |
| ---------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `face_urls` from [Face Detection API](/ai-tools-suite/face-detection/detect-faces) | **No**         | The URL is already a cropped face image, no bbox needed                                                             |
| User-uploaded original image URL                                                   | **Yes**        | Provide `bbox` from `crop_region` of the [Face Detection API](/ai-tools-suite/face-detection/detect-faces) response |

The `crop_region` from Face Detection API returns `[x, y, width, height]`. Convert it to `bbox` format `[x1, y1, x2, y2]`:

* `x1 = x`, `y1 = y`, `x2 = x + width`, `y2 = y + height`

***

## Image Face Swap

### Example: Simple Single Face Image Swap

```json theme={null}
{
  "source_url": "https://example.com/new-face.jpg",
  "target_url": "https://example.com/original.jpg",
  "single_face_mode": true,
  "face_enhance": false,
  "model_style": "realistic"
}
```

### Example: Multi-Face Image Swap with face\_urls (no bbox needed)

When using `face_urls` from the Face Detection API response, bbox is not required:

```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/detected-source-face-1.jpg" },
      "target_face_info": { "face_url": "https://example.com/detected-target-face-1.jpg" }
    },
    {
      "source_face_info": { "face_url": "https://example.com/detected-source-face-2.jpg" },
      "target_face_info": { "face_url": "https://example.com/detected-target-face-2.jpg" }
    }
  ]
}
```

### Example: Multi-Face Image Swap with original URLs (bbox required)

When using user-uploaded original image URLs, provide bbox from `crop_region`:

```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-original.jpg",
        "bbox": [120, 80, 280, 320]
      },
      "target_face_info": {
        "face_url": "https://example.com/target-original.jpg",
        "bbox": [150, 60, 350, 340]
      }
    }
  ]
}
```

***

## Video Face Swap

<Note>
  Video face swap is an async operation. Use `webhookUrl` or poll the [Get Result API](/ai-tools-suite/faceswap/get-result) to check processing status.
</Note>

### Video Requirements

* **Duration**: Keep videos under 60 seconds for optimal processing time
* **Format**: MP4, MOV, AVI supported
* **Resolution**: Higher resolution videos may take longer to process
* **Encoding**: H.264 recommended
* **Face Count**: For best results, limit to 8 or fewer faces

### Example: Single Face Video Swap

```json theme={null}
{
  "source_url": "https://example.com/new-face.jpg",
  "target_url": "https://example.com/video.mp4",
  "single_face_mode": true,
  "face_enhance": false,
  "model_style": "realistic"
}
```

### Example: Multi-Face Video Swap

```json theme={null}
{
  "source_url": "https://example.com/source-face.jpg",
  "target_url": "https://example.com/group-video.mp4",
  "single_face_mode": false,
  "face_enhance": false,
  "model_style": "realistic",
  "face_mapping": [
    {
      "source_face_info": { "face_url": "https://example.com/face-1.jpg" },
      "target_face_info": { "face_url": "https://example.com/target-face-1.jpg" }
    },
    {
      "source_face_info": { "face_url": "https://example.com/face-2.jpg" },
      "target_face_info": { "face_url": "https://example.com/target-face-2.jpg" }
    }
  ]
}
```

### Example: Video Swap with Webhook

```json theme={null}
{
  "source_url": "https://example.com/new-face.jpg",
  "target_url": "https://example.com/video.mp4",
  "single_face_mode": true,
  "webhookUrl": "https://your-server.com/webhook/faceswap-callback",
  "face_enhance": true,
  "model_style": "realistic"
}
```

***

## Checking Results

After submitting a face swap request, use the [Get Result API](/ai-tools-suite/faceswap/get-result) to check the status:

| 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     |


## OpenAPI

````yaml POST /api/open/v4/faceswap/faceswapPlusByImage
openapi: 3.0.3
info:
  title: Face Swap API
  description: API for face swapping in images and videos
  version: 1.0.0
servers:
  - url: https://openapi.akool.com
    description: Production server
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /api/open/v4/faceswap/faceswapPlusByImage:
    post:
      tags:
        - Face Swap
      summary: Face Swap Plus
      description: >
        Face Swap Plus API (`akool_faceswap_classic_plus`) - Multi-face swap for
        images and videos.


        - Supports **multiple faces** via `face_mapping`

        - Supports both **images and videos** (`source_url` / `target_url`)

        - Supports `single_face_mode` for single-face swap

        - Supports `model_style` (realistic / beautify / lossless)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageFaceswapPlusRequest'
            examples:
              multi_face:
                summary: Multi-Face Swap
                value:
                  source_url: https://example.com/new-face.jpg
                  target_url: https://example.com/group-photo.jpg
                  face_enhance: false
                  model_style: realistic
                  single_face_mode: false
                  face_mapping:
                    - source_face_info:
                        face_url: https://example.com/source-face-1.jpg
                      target_face_info:
                        face_url: https://example.com/target-face-1.jpg
                    - source_face_info:
                        face_url: https://example.com/source-face-2.jpg
                      target_face_info:
                        face_url: https://example.com/target-face-2.jpg
              video_segment:
                summary: Video Single Face Swap
                value:
                  source_url: https://example.com/new-face.jpg
                  target_url: https://example.com/video.mp4
                  single_face_mode: true
                  face_enhance: false
      responses:
        '200':
          description: Faceswap request submitted successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/FaceswapV4Result'
              example:
                code: 1000
                msg: OK
                data:
                  _id: 6593c94c0ef703e8c055e3c8
                  job_id: 20240102082900592-5653
components:
  schemas:
    ImageFaceswapPlusRequest:
      type: object
      required:
        - source_url
        - target_url
      properties:
        source_url:
          type: string
          description: Source (new) face image URL
        target_url:
          type: string
          description: Target material URL (image or video)
        webhookUrl:
          type: string
          description: Callback URL for result notification
        face_enhance:
          type: boolean
          default: false
          description: Whether to enable face enhancement (default false)
        model_style:
          type: string
          enum:
            - realistic
            - beautify
            - lossless
          default: realistic
          description: 'Model style: `realistic` (default), `beautify`, or `lossless`'
        face_mapping:
          type: array
          items:
            $ref: '#/components/schemas/FaceMappingItem'
          description: >
            Face mapping array for multi-face swap (required when
            `single_face_mode` is false).

            Each item maps one source face to one target face.
        single_face_mode:
          type: boolean
          default: false
          description: >
            When `true`, enables single-face mode for simplified single-face
            swap.

            When `false` (default), uses `face_mapping` for multi-face swap.
    ApiResponse:
      type: object
      required:
        - code
        - msg
      properties:
        code:
          type: integer
          description: 'Interface returns business status code (1000: success)'
          example: 1000
        msg:
          type: string
          description: Interface returns status information
          example: OK
    FaceswapV4Result:
      type: object
      properties:
        _id:
          type: string
          description: Interface returns data ID
        job_id:
          type: string
          description: Task processing unique ID
    FaceMappingItem:
      type: object
      required:
        - source_face_info
        - target_face_info
      properties:
        source_face_info:
          type: object
          required:
            - face_url
          properties:
            face_url:
              type: string
              description: >
                URL of the source (new) face image.

                Can be a `face_urls` value from the Face Detection API (bbox not
                needed),

                or a user-uploaded original image URL (bbox required).
            bbox:
              type: array
              items:
                type: number
              minItems: 4
              maxItems: 4
              description: >
                Bounding box `[x1, y1, x2, y2]` for the source face (optional).

                Required when `face_url` is a user-uploaded original image URL.

                Get this value from the `crop_region` field of the Face
                Detection API response.

                Not needed when `face_url` comes from `face_urls` in the Face
                Detection API response.
        target_face_info:
          type: object
          properties:
            face_url:
              type: string
              description: >
                URL of the target (original) face image.

                Can be a `face_urls` value from the Face Detection API (bbox not
                needed),

                or a user-uploaded original image URL (bbox required).
            bbox:
              type: array
              items:
                type: number
              minItems: 4
              maxItems: 4
              description: >
                Bounding box `[x1, y1, x2, y2]` for the target face (optional).

                Required when `face_url` is a user-uploaded original image URL.

                Get this value from the `crop_region` field of the Face
                Detection API response.

                Not needed when `face_url` comes from `face_urls` in the Face
                Detection API response.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your API Key used for request authorization. If both Authorization and
        x-api-key have values, Authorization will be used first and x-api-key
        will be discarded.
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your API Key used for request authorization. Get Token from
        authentication/usage#get-the-token

````