Generated resources (images, videos, audio) 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"
    }'

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

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.

Generated resources (images, videos, audio) 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"
    }'

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

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.