Face Swap Plus (Image & Video)

curl --request POST \
  --url https://openapi.akool.com/api/open/v4/faceswap/faceswapPlusByImage \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "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"
      }
    }
  ]
}
'

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "_id": "6593c94c0ef703e8c055e3c8",
    "job_id": "20240102082900592-5653"
  }
}

POST

api

open

faceswap

faceswapPlusByImage

curl --request POST \
  --url https://openapi.akool.com/api/open/v4/faceswap/faceswapPlusByImage \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "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"
      }
    }
  ]
}
'

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "_id": "6593c94c0ef703e8c055e3c8",
    "job_id": "20240102082900592-5653"
  }
}

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.

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 to get face_url and bbox for each face
For highest quality image face swap (single face only), use Face Swap Pro
Video Faceswap API is a V3 legacy API. For new projects, we recommend using this API instead

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
Multi-face swap (image/video)	Face Swap Plus ✅
Video face swap	Face Swap Plus ✅ (Recommended)
V3 compatibility required	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
`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

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

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

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

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

Video face swap is an async operation. Use webhookUrl or poll the Get Result API to check processing status.

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

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

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

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

Authorizations

x-api-key

string

header

required

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.

Body

application/json

source_url

string

required

Source (new) face image URL

target_url

string

required

Target material URL (image or video)

webhookUrl

string

Callback URL for result notification

face_enhance

boolean

default:false

Whether to enable face enhancement (default false)

model_style

enum<string>

default:realistic

Model style: realistic (default), beautify, or lossless

Available options:

realistic,

beautify,

lossless

face_mapping

object[]

Face mapping array for multi-face swap (required when single_face_mode is false). Each item maps one source face to one target face.

Show child attributes

single_face_mode

boolean

default:false

When true, enables single-face mode for simplified single-face swap. When false (default), uses face_mapping for multi-face swap.

Response

200 - application/json

Faceswap request submitted successfully

code

integer

required

Interface returns business status code (1000: success)

Example:

1000

msg

string

required

Interface returns status information

Example:

"OK"

data

object

Show child attributes

Face Swap API Overview Face Swap Pro

Authentication

Face Swap

Streaming Avatar

Talking Photo

Video Translation

Face Detection

Character Swap

Image Generate

Image to Video

Head Swap

AI Tools Suite

Features

Which API Should I Use?

Parameters

Core Parameters

Multi-Face Mode (default)

Single Face Mode

When is bbox required?

Image Face Swap

Example: Simple Single Face Image Swap

Example: Multi-Face Image Swap with face_urls (no bbox needed)

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

Video Face Swap

Video Requirements

Example: Single Face Video Swap

Example: Multi-Face Video Swap

Example: Video Swap with Webhook

Checking Results

Authorizations

Body

Response

​Features

​Which API Should I Use?

​Parameters

​Core Parameters

​Multi-Face Mode (default)

​Single Face Mode

​When is bbox required?

​Image Face Swap

​Example: Simple Single Face Image Swap

​Example: Multi-Face Image Swap with face_urls (no bbox needed)

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

​Video Face Swap

​Video Requirements

​Example: Single Face Video Swap

​Example: Multi-Face Video Swap

​Example: Video Swap with Webhook

​Checking Results

Authorizations

Body

Response

Features

Which API Should I Use?

Parameters

Core Parameters

Multi-Face Mode (default)

Single Face Mode

When is bbox required?

Image Face Swap

Example: Simple Single Face Image Swap

Example: Multi-Face Image Swap with face_urls (no bbox needed)

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

Video Face Swap

Video Requirements

Example: Single Face Video Swap

Example: Multi-Face Video Swap

Example: Video Swap with Webhook

Checking Results