Live Face Swap
Real-time Face Swap API Documentation
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.
Request Headers
Parameter | Value | Description |
---|---|---|
Content-Type | application/json | Request content type |
Request Body
Parameter | Type | Description |
---|---|---|
clientId | String | Client ID |
clientSecret | String | Client secret |
Example Request
Face Detection
Detect faces in an image and get facial landmarks coordinates.
Request Headers
Parameter | Value | Description |
---|---|---|
Authorization | Bearer token | API key for request authorization |
Content-Type | application/json | Request content type |
Request Body
Parameter | Type | Description |
---|---|---|
single_face | Boolean | Whether to detect single face only |
image_url | String | Image URL for face detection |
img | String | Base64 encoded image (optional) |
Example Request
Response
Parameter | Type | Description |
---|---|---|
error_code | int | Error code (0: success) |
error_msg | String | Error message |
landmarks | Array | Facial landmarks coordinates array |
landmarks_str | Array | Facial landmarks coordinates string array |
region | Array | Face region coordinates |
seconds | float | Processing time in seconds |
trx_id | String | Transaction ID |
Response Example
Create Real-time Face Swap Session
Create a new real-time face swap session.
Request Headers
Parameter | Value | Description |
---|---|---|
Authorization | Bearer token | API key for request authorization |
Content-Type | application/json | Request content type |
Request Body
Parameter | Type | Description |
---|---|---|
sourceImage | Array | Source image information array, each element contains path and opts properties |
Example Request
Response
Parameter | Type | Description |
---|---|---|
code | int | API response business status code (1000: success) |
msg | String | API response status information |
data | Object | Response data object |
Response Example
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.
Request Headers
Parameter | Value | Description |
---|---|---|
Authorization | Bearer token | API key for request authorization |
Content-Type | application/json | Request content type |
Request Body
Parameter | Type | Description |
---|---|---|
_id | String | Session ID |
sourceImage | Array | Source image information array, each element contains path and opts properties |
Example Request
Response Example
Close Real-time Face Swap Session
Close the specified real-time face swap session.
Request Headers
Parameter | Value | Description |
---|---|---|
Authorization | Bearer token | API key for request authorization |
Content-Type | application/json | Request content type |
Request Body
Parameter | Type | Description |
---|---|---|
_id | String | Session ID |
Example Request
Response Example
Code Examples
Important Notes
- Resource Validity: Generated resources are valid for 7 days, please save them promptly
- Face Detection: Use the face-detect API to get face landmarks coordinates before creating face swap sessions
- Status Monitoring: After creating a session, you need to monitor the
faceswap_status
status - Real-time Connection: When the status is 2, you can connect to Agora’s server for real-time face swap
- Session Management: Please close sessions promptly after use to release resources
- 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
- GitHub Repository: https://github.com/AgoraIO/API-Examples-Web/tree/main/src/example/basic/basicVideoCall
Recommended Track Configuration
For optimal performance in live face swap scenarios, it’s recommended to use the following track configurations:
Audio Track Configuration
Video Track Configuration
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.