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
}
'
import requests

url = "https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage"

payload = {
"sourceImage": [{ "path": "https://example.com/new-face.jpg" }],
"targetImage": [{ "path": "https://example.com/original.jpg" }],
"model_name": "akool_faceswap_image_hq",
"face_enhance": False
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
sourceImage: [{path: 'https://example.com/new-face.jpg'}],
targetImage: [{path: 'https://example.com/original.jpg'}],
model_name: 'akool_faceswap_image_hq',
face_enhance: false
})
};

fetch('https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'sourceImage' => [
[
'path' => 'https://example.com/new-face.jpg'
]
],
'targetImage' => [
[
'path' => 'https://example.com/original.jpg'
]
],
'model_name' => 'akool_faceswap_image_hq',
'face_enhance' => false
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage"

payload := strings.NewReader("{\n \"sourceImage\": [\n {\n \"path\": \"https://example.com/new-face.jpg\"\n }\n ],\n \"targetImage\": [\n {\n \"path\": \"https://example.com/original.jpg\"\n }\n ],\n \"model_name\": \"akool_faceswap_image_hq\",\n \"face_enhance\": false\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"sourceImage\": [\n {\n \"path\": \"https://example.com/new-face.jpg\"\n }\n ],\n \"targetImage\": [\n {\n \"path\": \"https://example.com/original.jpg\"\n }\n ],\n \"model_name\": \"akool_faceswap_image_hq\",\n \"face_enhance\": false\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"sourceImage\": [\n {\n \"path\": \"https://example.com/new-face.jpg\"\n }\n ],\n \"targetImage\": [\n {\n \"path\": \"https://example.com/original.jpg\"\n }\n ],\n \"model_name\": \"akool_faceswap_image_hq\",\n \"face_enhance\": false\n}"

response = http.request(request)
puts response.read_body
{
  "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