Face Swap Plus (Image & Video) - Akool open api documents

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

Documentation Index

​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