Skip to main content
POST
Face Swap Pro
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

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:

Example: Batch Face Swap (opts Required)

When either array has more than 1 element, opts is required for all elements:

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