Skip to main content
POST
/
api
/
open
/
v4
/
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 (akool_faceswap_classic_plus)

Face Swap Plus supports advanced face swapping scenarios:
  • Multi-Face: Swap multiple faces at once via face_mapping
  • Image and Video: Supports both image and video materials
  • Single Face Mode: Use single_face_mode for simplified single-face swap
  • Style Options: Choose between realistic, beautify, or lossless styles

​
Parameters

​
Core Parameters

ParameterTypeRequiredDescription
source_urlstringYesSource (new) face image URL
target_urlstringYesTarget material URL (image or video)
webhookUrlstringNoCallback URL for result notification
face_enhancebooleanNoEnable face enhancement (default: false)
model_stylestringNorealistic (default), beautify, or lossless
single_face_modebooleanNofalse (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:
ParameterTypeRequiredDescription
face_mappingarrayYesArray of face mapping objects
face_mapping[].source_face_infoobjectYesSource face info
face_mapping[].source_face_info.face_urlstringYesSource face image URL
face_mapping[].source_face_info.bboxnumber[]NoBounding box [x1, y1, x2, y2]. See bbox rules
face_mapping[].target_face_infoobjectYesTarget face info
face_mapping[].target_face_info.face_urlstringNoTarget face image URL
face_mapping[].target_face_info.bboxnumber[]NoBounding box [x1, y1, x2, y2]. See bbox rules

​
Single Face Mode

When single_face_mode is true, enables simplified single-face swap mode:
ParameterTypeRequiredDescription
single_face_modebooleanYesSet 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 sourcebbox required?Description
face_urls from Face Detection APINoThe URL is already a cropped face image, no bbox needed
User-uploaded original image URLYesProvide 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

​
Example: Multi-Face 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 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]
      }
    }
  ]
}

​
Example: Video Single Face Swap (single_face_mode)

{
  "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: Simple Single Face Image Swap

{
  "source_url": "https://example.com/new-face.jpg",
  "target_url": "https://example.com/original.jpg",
  "single_face_mode": false,
  "face_enhance": false,
  "model_style": "realistic"
}

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.

​
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