Skip to main content
POST
/
api
/
open
/
v4
/
faceswap
/
faceswapByImage
Face Swap Pro
curl --request POST \
  --url https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "sourceImage": [
    {
      "path": "https://example.com/new-face.jpg"
    }
  ],
  "targetImage": [
    {
      "path": "https://example.com/original.jpg"
    }
  ],
  "model_name": "akool_faceswap_image_hq",
  "face_enhance": false
}
'
{
  "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 Pro (akool_faceswap_image_hq)

Face Swap Pro delivers the highest quality face swap results for images:
  • More Realistic: Advanced algorithm produces natural and lifelike face swaps
  • More Similar: Enhanced matching ensures high similarity to the source face
  • Simplified Integration: opts parameter is optional, no face detection step required
  • Batch Support: Supports up to 50 sourceImage / targetImage pairs per request
  • Optional Face Landmarks: Provide opts from the Face Detection API for improved accuracy

​
Parameters

ParameterTypeRequiredDescription
sourceImagearrayYesSource (new) face image URLs. Each item: { "path": "url", "opts": "landmarks" }. Min 1, Max 50 items.
sourceImage[].pathstringYesValid URL of the source face image. Must be a valid HTTP/HTTPS URL.
sourceImage[].optsstringConditionalFace landmark string from crop_landmarks of Face Detection API. Required when sourceImage or targetImage array length > 1. Optional when both arrays have exactly 1 element.
targetImagearrayYesTarget face image URLs. Each item: { "path": "url", "opts": "landmarks" }. Min 1, Max 50 items.
targetImage[].pathstringYesValid URL of the target face image. Must be a valid HTTP/HTTPS URL.
targetImage[].optsstringConditionalFace landmark string from crop_landmarks of Face Detection API. Required when sourceImage or targetImage array length > 1. Optional when both arrays have exactly 1 element.
model_namestringNoDefault: akool_faceswap_image_hq
webhookUrlstringNoCallback URL for result notification
face_enhancebooleanNoEnable face enhancement (default: false)
single_face_modebooleanNoWhen true, enables single face mode (default: false)

​
Getting opts Value

The opts parameter provides face landmark coordinates for improved face alignment accuracy. To get the opts value:
  1. Call the Face Detection API with your image URL
  2. Use the crop_landmarks value from the response as the opts parameter
  3. Format: colon-separated coordinate pairs, e.g. "262,175:363,175:313,215:272,279"

​
Important Notes

​
Parameter Validation Rules

  • path validation: Each path must be a valid HTTP/HTTPS URL. Invalid URLs will be rejected.
  • opts conditional requirement:
    • When both sourceImage and targetImage arrays have exactly 1 element each: opts is optional for all elements
    • When either sourceImage or targetImage array has more than 1 element: opts is required for every element in both arrays
    • If any element is missing opts when required, the request will be rejected with a validation error

​
Usage Guidelines

  • For single face swap (1 source + 1 target): opts is optional but recommended for better accuracy
  • For batch face swap (multiple faces): opts is required for all elements to ensure proper face mapping
  • For multi-face swap, image + video support, or video segment swap, use Face Swap Plus

​
Example: Single Face Swap (opts Optional)

When both arrays have exactly 1 element, opts is optional: 
{
  "sourceImage": [
    { 
      "path": "https://example.com/new-face.jpg"
    }
  ],
  "targetImage": [
    { 
      "path": "https://example.com/original.jpg"
    }
  ],
  "model_name": "akool_faceswap_image_hq",
  "face_enhance": false,
  "single_face_mode": false
}

{
  "sourceImage": [
    {
      "path": "https://example.com/new-face.jpg",
      "opts": "239,364:386,366:317,472:266,539"
    }
  ],
  "targetImage": [
    {
      "path": "https://example.com/original.jpg",
      "opts": "262,175:363,175:313,215:272,279"
    }
  ],
  "model_name": "akool_faceswap_image_hq",
  "face_enhance": false,
  "single_face_mode": false
}

​
Example: Batch Face Swap (opts Required)

When either array has more than 1 element, opts is required for all elements: 
{
  "sourceImage": [
    {
      "path": "https://example.com/new-face-1.jpg",
      "opts": "239,364:386,366:317,472:266,539"
    },
    {
      "path": "https://example.com/new-face-2.jpg",
      "opts": "150,200:250,200:200,250:180,300"
    }
  ],
  "targetImage": [
    {
      "path": "https://example.com/original.jpg",
      "opts": "262,175:363,175:313,215:272,279"
    },
    {
      "path": "https://example.com/original-2.jpg",
      "opts": "100,150:200,150:150,200:120,250"
    }
  ],
  "model_name": "akool_faceswap_image_hq",
  "face_enhance": false,
  "single_face_mode": false
}

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
​
sourceImage
object[]
required

Source (new) face image URL array. Each item contains path (required, must be valid URL) and opts (conditional).

opts requirement:

  • Required when sourceImage or targetImage array length > 1 (all elements must have opts)
  • Optional when both sourceImage and targetImage arrays have exactly 1 element each

The opts value comes from the crop_landmarks field returned by the Face Detection API.

Required array length: 1 - 50 elements
​
targetImage
object[]
required

Target face image URL array. Each item contains path (required, must be valid URL) and opts (conditional).

opts requirement:

  • Required when sourceImage or targetImage array length > 1 (all elements must have opts)
  • Optional when both sourceImage and targetImage arrays have exactly 1 element each

The opts value comes from the crop_landmarks field returned by the Face Detection API.

Required array length: 1 - 50 elements
​
model_name
enum<string>
default:akool_faceswap_image_hq

Model name (default: akool_faceswap_image_hq)

Available options:
akool_faceswap_image_hq
​
webhookUrl
string

Callback URL for result notification

​
face_enhance
boolean
default:false

Whether to enable face enhancement (default false)

​
single_face_mode
boolean
default:false

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

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