Generated resources (images, videos) are valid for 7 days. Please save related resources promptly to prevent expiration.

​
Overview

Live Face Swap API provides real-time face swap functionality, supporting real-time face swap operations during live streaming.

​
Get Access Token

Before calling other APIs, you need to obtain an access token first. 
POST https://openapi.akool.com/api/open/v3/getToken
Request Headers
ParameterValueDescription
Content-Typeapplication/jsonRequest content type
Request Body
ParameterTypeDescription
clientIdStringClient ID
clientSecretStringClient secret
Example Request 
{
    "clientId": "AKX5brZQ***XBQSk=",
    "clientSecret": "tcMhvgV0fY***WQ2eIoEY70rNi"
}

​
Face Detection

Detect faces in an image and get facial landmarks coordinates. 
POST https://sg3.akool.com/detect
Request Headers
ParameterValueDescription
AuthorizationBearer tokenAPI key for request authorization
Content-Typeapplication/jsonRequest content type
Request Body
ParameterTypeDescription
single_faceBooleanWhether to detect single face only
image_urlStringImage URL for face detection
imgStringBase64 encoded image (optional)
Example Request 
{
    "single_face": false,
    "image_url": "https://d21ksh0k4smeql.cloudfront.net/1745579943557-yr5w-crop_1728989585247-3239-0-1728989585409-9277.png"
}
Response
ParameterTypeDescription
error_codeintError code (0: success)
error_msgStringError message
landmarksArrayFacial landmarks coordinates array
landmarks_strArrayFacial landmarks coordinates string array
regionArrayFace region coordinates
secondsfloatProcessing time in seconds
trx_idStringTransaction ID
Response Example 
{
    "error_code": 0,
    "error_msg": "SUCCESS",
    "landmarks": [
        [
            [249, 510],
            [460, 515],
            [343, 657],
            [255, 740],
            [0, 0],
            [0, 0]
        ]
    ],
    "landmarks_str": [
        "249,510:460,515:343,657:255,740"
    ],
    "region": [
        [150, 264, 437, 657]
    ],
    "seconds": 0.6554102897644043,
    "trx_id": "64498285-446f-462d-9470-fe36c36c6eac"
}

​
Create Real-time Face Swap Session

Create a new real-time face swap session. 
POST https://openapi.akool.com/api/open/v3/faceswap/live/create
Request Headers
ParameterValueDescription
AuthorizationBearer tokenAPI key for request authorization
Content-Typeapplication/jsonRequest content type
Request Body
ParameterTypeDescription
sourceImageArraySource image information array, each element contains path and opts properties
Example Request 
{
    "sourceImage": [
        {
            "path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695201165222-7514-0-1695201165485-8149.png",
            "opts": "262,175:363,175:313,215:272,279"
        }
    ]
}
Response
ParameterTypeDescription
codeintAPI response business status code (1000: success)
msgStringAPI response status information
dataObjectResponse data object
Response Example 
{
    "code": 1000,
    "msg": "OK",
    "data": {
        "_id": "684f8fb744b8795862e45cbe",
        "faceswap_status": 1,
        "front_user_id": "1",
        "algorithm_user_id": "3",
        "front_rtc_token": "007eJxTYFj/uGvaue3C3/VlOLdFmM5UuffmzHGhszbnTSqs3or94HNRYEhNNElJM0oxMkg1MTYxMklMMkm0MDCySDW0sDBOMjRP297vnyHAx8Bw6YAZIyMDIwMLAyMDiM8EJpnBJAuYFGMwMjAyNTAzNDMwNrI0tTQ0MIy3MDIyYWQwBADtwSJM",
        "channel_id": "20250616032959101_8224",
        "app_id": ""
    }
}
Status Code Description
  • faceswap_status:
    • 1: Queuing
    • 2: Processing (when this value is 2, the frontend can connect to Agora’s server)
    • 3: Success
    • 4: Failed

​
Update Real-time Face Swap Session

Update existing real-time face swap session configuration. 
POST https://openapi.akool.com/api/open/v3/faceswap/live/update
Request Headers
ParameterValueDescription
AuthorizationBearer tokenAPI key for request authorization
Content-Typeapplication/jsonRequest content type
Request Body
ParameterTypeDescription
_idStringSession ID
sourceImageArraySource image information array, each element contains path and opts properties
Example Request 
{
    "sourceImage": [
        {
            "path": "https://d21ksh0k4smeql.cloudfront.net/1745579943557-yr5w-crop_1728989585247-3239-0-1728989585409-9277.png",
            "opts": "249,510:460,515:343,657:255,740"
        }
    ],
    "_id": "685ea0bb5aa150dd8b7116b1"
}
Response Example 
{
    "code": 1000,
    "msg": "OK"
}

​
Close Real-time Face Swap Session

Close the specified real-time face swap session. 
POST https://openapi.akool.com/api/open/v3/faceswap/live/close
Request Headers
ParameterValueDescription
AuthorizationBearer tokenAPI key for request authorization
Content-Typeapplication/jsonRequest content type
Request Body
ParameterTypeDescription
_idStringSession ID
Example Request 
{
    "_id": "685ea0bb5aa150dd8b7116b1"
}
Response Example 
{
    "code": 1000,
    "msg": "OK"
}

​
Code Examples

# Get token
curl -X POST "https://openapi.akool.com/api/open/v3/getToken" \
    -H "Content-Type: application/json" \
    -d '{
        "clientId": "AKX5brZQ***XBQSk=",
        "clientSecret": "tcMhvgV0fY***WQ2eIoEY70rNi"
    }'

# Face detection
curl -X POST "https://sg3.akool.com/detect" \
    -H "Authorization: Bearer token" \
    -H "Content-Type: application/json" \
    -d '{
        "single_face": false,
        "image_url": "https://d21ksh0k4smeql.cloudfront.net/1745579943557-yr5w-crop_1728989585247-3239-0-1728989585409-9277.png"
    }'

# Create session
curl -X POST "https://openapi.akool.com/api/open/v3/faceswap/live/create" \
    -H "Authorization: Bearer token" \
    -H "Content-Type: application/json" \
    -d '{
        "sourceImage": [
            {
                "path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695201165222-7514-0-1695201165485-8149.png",
                "opts": "262,175:363,175:313,215:272,279"
            }
        ]
    }'

# Update session
curl -X POST "https://openapi.akool.com/api/open/v3/faceswap/live/update" \
    -H "Authorization: Bearer token" \
    -H "Content-Type: application/json" \
    -d '{
        "sourceImage": [
            {
                "path": "https://d21ksh0k4smeql.cloudfront.net/1745579943557-yr5w-crop_1728989585247-3239-0-1728989585409-9277.png",
                "opts": "249,510:460,515:343,657:255,740"
            }
        ],
        "_id": "685ea0bb5aa150dd8b7116b1"
    }'

# Close session
curl -X POST "https://openapi.akool.com/api/open/v3/faceswap/live/close" \
    -H "Authorization: Bearer token" \
    -H "Content-Type: application/json" \
    -d '{
        "_id": "685ea0bb5aa150dd8b7116b1"
    }'

​
Response Code Description

Note: If the code value in the response is not 1000, the request has failed or is incorrect.
ParameterValueDescription
code1000Success
code1003Parameter error or parameter cannot be empty
code1101Invalid authorization or the request token has expired
code1102Authorization cannot be empty
code1104Insufficient quota

​
Important Notes

  1. Resource Validity: Generated resources are valid for 7 days, please save them promptly
  2. Face Detection: Use the face-detect API to get face landmarks coordinates before creating face swap sessions
  3. Status Monitoring: After creating a session, you need to monitor the faceswap_status status
  4. Real-time Connection: When the status is 2, you can connect to Agora’s server for real-time face swap
  5. Session Management: Please close sessions promptly after use to release resources
  6. Error Handling: Please handle API error codes and error messages properly

​
Push and pull stream Demo References

For implementing real-time video communication with Agora SDK, you can refer to the following resources:

​
Basic Video Calling Demo Parameter Description

Basic Video Calling Demo Parameter Description As shown in the figure above, channel_id, front_user_id, and front_rtc_token correspond to the Channel, User ID, and Token input fields on the page respectively. These parameters can be obtained after creating a session through the Live Face Swap API. After filling them in, you can experience push/pull streaming and real-time face swap effects.

​
Demo Page

​
Source Code

For optimal performance in live face swap scenarios, it’s recommended to use the following track configurations:

​
Audio Track Configuration

const audioTrack = await AgoraRTC.createMicrophoneAudioTrack({
  encoderConfig: "music_standard",
});

​
Video Track Configuration

const videoTrack = await AgoraRTC.createCameraVideoTrack({
  encoderConfig: {
    width: 640,
    height: 480,
    frameRate: {max: 20, min: 20},
    bitrateMin: 5000,
    bitrateMax: 5000,
  },
});
These configurations are optimized for:
  • Audio: Using music_standard encoder for better audio quality
  • Video: Fixed frame rate at 20fps with controlled bitrate for stable performance
  • Resolution: 640x480 resolution suitable for face swap processing
These resources provide complete examples of how to integrate Agora’s real-time video communication SDK, which can be used as a reference for implementing the video streaming part of the live face swap functionality.