Al Tools

Face Swap

The resources (image, video) generated by our API are valid for 7 days. Please save the relevant resources as soon as possible to prevent expiration.

Get File Upload URL

Start by getting the upload endpoint for a local file.

POST https://devapi.vidnoz.com/v1/source/upload-url

Body Attributes application/json

Parameter	Type	Required	Description
file_name	string	true	You need to specify the file name, the API will respond with an url to upload file and unique key representing your asset

Response Attributes

Parameter	Type	Description
upload_url	string	An url to upload file
key	string	An unique key representing your asset

Example

Request Attributes

{
    "file_name": "demo.jpg",
}

Response

{
    "code": 200,
    "message": "ok",
    "data": {
        "upload_url": "https://r2-aiautodelete-000-test.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/temporary/20240816/3620/1723807527474-df2da456-b92b-b339-3bee-76365268665a.jpg?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240816%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240816T112527Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Signature=53c3b909f9b8bb32d3d1df88a885eda63037cf468eab3503e4462517c2b4e36b",
        "key": "temporary/20240816/3620/1723807527474-df2da456-b92b-b339-3bee-76365268665a.jpg"
    }
}

Upload File

Start by uploading a local file to Vidnoz using the upload endpoint.

PUT upload_url returned from “Get File Upload URL”

Get Access URL

Use the endpoint to access the file

POST https://devapi.vidnoz.com/v1/source/access-url

Body Attributes application/json

Parameter	Type	Required	Description
key	string	true	An unique key representing your asset

Response Attributes

Parameter	Type	Description
url	string	An endpoint to access the file

Example

Request Attributes

{
    "key": "Your unique key representing your file",
}

Response

{
    "code": 200,
    "message": "ok",
    "data": {
        "url": "https://r2-aiautodelete-000-test.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/temporary/20240816/3620/1723785587958-0908b324-2aa6-7dc9-3bd6-4f75c0d9d7f1.mp4?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240816%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240816T113218Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=ac5d20c4f62f6a82ab3b04980c5f6917d97e4abd19b4fa4e9255fa3c27b01a8b"
    }
}

Image Face Swap

Upload image to swap a face.

POST https://devapi.vidnoz.com/v1/task/face-swap

Body Attributes application/json

Parameter	Type	Required	Description
main_key	string	true	An unique key representing your original face image
target_key	string	true	An unique key representing your target face image
is_hd	init	false	High quality mode 1: Enable 2: Disable

Response Attributes

Parameter	Type	Description
task_id	int	An unique id representing your faceswap task

Example

Request Attributes

{
    "key": "An unique key representing your original face image",
    "target_key": "An unique key representing your target face image",
    "is_hd": 2,
}

Response

{
    "code": 200,
    "message": "ok",
    "data": {
        "task_id": 1
    }
}

Video Face Swap

Upload video to swap a face.

POST https://devapi.vidnoz.com/v1/task/video-face-swap

Body Attributes application/json

Parameter	Type	Required	Description
main_key	string	true	An unique key representing your original face video
target_key	string	true	An unique key representing your target face image
is_hd	init	false	High quality mode 1: Enable 2: Disable

Response Attributes

Parameter	Type	Description
task_id	int	An unique id representing your faceswap task

Example

Request Attributes

{
    "key": "An unique key representing your original face video",
    "target_key": "An unique key representing your target face image",
    "is_hd": 2,
}

Response

{
    "code": 200,
    "message": "ok",
    "data": {
        "task_id": 2
    }
}

Get Multiple Faces

Get multiple faces from a image or video to specify what targets to be swapped.

POST https://devapi.vidnoz.com/v1/task/get-face

Body Attributes application/json

Parameter	Type	Required	Description
main_key	string	true	Your unique key representing your original face image or video

Response Attributes

Parameter	Type	Description
task_id	int	Your unique key representing your original face image or video

Example

Request Attributes

{
    "main_key": "An unique key representing your original face image",
}

Response

{
    "code": 200,
    "message": "ok",
    "data": {
        "task_id": 3
    }
}

Multiple Image Face Swap

Change faces on group images with target faces.

POST https://devapi.vidnoz.com/v1/task/multiple-face-swap

Body Attributes application/json

Parameter	Type	Required	Description
avatar_key	array	true	Face swap task data consists of original face and target face
target_part_key	string	true	An unique key representing your original face
avatar_part_key	string	true	An unique key representing your target face
get_face_id	int	true	An unique id representing your faceswap task
is_hd	int	true	High quality mode 1: Enable 2: Disable

Response Attributes

Parameter	Type	Description
task_id	int	An unique id representing your faceswap task

Example

Request Attributes

{
    "avatar_key": [
        {
            "target_part_key": "temporary/20240816/3620/1723785653905-459ed35e-e4b0-9ff6-3441-49289f82115e.jpg",
            "avatar_part_key": "temporary/20240816/6332581/172379952540-129237d8-e142-fd39-bfa1-00eeb15b98e9.png"
        },
        {
            "target_part_key": "temporary/20240816/6332581/1723799530615-fb873456-dd7b-2f89-a1d6-3633bb52cedc.png",
            "avatar_part_key": "temporary/20240816/6332581/1723799530615-fb873456-dd7b-2f89-a1d6-3633bb52cedc.png"
        }
    ],
    "get_face_id": "105267189",
    "is_hd": "1"
}

Response

{
    "code": 200,
    "message": "ok",
    "data": {
        "task_id": 458
    }
}

Multiple Video Face Swap

Change faces on group video with target faces.

POST https://devapi.vidnoz.com/v1/task/multiple-video-face-swap

Body Attributes application/json

Parameter	Type	Required	Description
avatar_key	array	true	Face swap task data consists of original face and target face
target_part_key	string	true	An unique key representing your original face
avatar_part_key	string	true	An unique key representing your target face
get_face_id	int	true	An unique id representing your faceswap task
is_hd	int	true	High quality mode 1: Enable 2: Disable

Response Attributes

Parameter	Type	Description
task_id	int	An unique id representing your faceswap task

Example

Request Attributes

{
    "avatar_key": [
        {
            "target_part_key": "temporary/20240816/3620/1723785653905-459ed35e-e4b0-9ff6-3441-49289f82115e.jpg",
            "avatar_part_key": "temporary/20240816/6332581/172379952540-129237d8-e142-fd39-bfa1-00eeb15b98e9.png"
        },
        {
            "target_part_key": "temporary/20240816/6332581/1723799530615-fb873456-dd7b-2f89-a1d6-3633bb52cedc.png",
            "avatar_part_key": "temporary/20240816/6332581/1723799530615-fb873456-dd7b-2f89-a1d6-3633bb52cedc.png"
        }
    ],
    "get_face_id": "105267190",
    "is_hd": "1"
}

Response

{
    "code": 200,
    "message": "ok",
    "data": {
        "task_id": 458
    }
}

Get Task Detail

Get the status and results of the task after it has been created.

GET https://devapi.vidnoz.com/v1/task/detail?id=459

Body Attributes

Parameter	Type	Required	Description
id	int	true	An unique id representing your faceswap task

Response Attributes

Parameter	Type	Description
id	int	An unique id representing your faceswap task
message	string	The detail information of faceswap task
status	int	Task status 1: Waiting 2: Processing
additional_data	object/array	The data of face swap result

Example

Request Attributes

{
    "id": "106927142",
}

Response

{
    "code": 200,
    "message": "",
    "data": {
        "id": 106927142,
        "message": "",
        "status": 0,
        "additional_data": {}
    }
}

Image Face Swap

Parameter	Type	Description
size	int	The size of the result image
width	int	The width of the result image
height	int	The height of the result image
merge_key	string	An unique id representing your result image
merge_url	string	The signatured url of the result image
thumbnail_key	string	An unique id representing your result image thumbnail
thumbnail_url	string	The signatured url of the result image thumbnail
thumbnail_width	int	The width of the result image thumbnail
thumbnail_height	int	The height of the result image thumbnail

Response

 "additional_data": {
    "size": 678609,
    "width": 512,
    "height": 768,
    "merge_key": "133902/asset/202408/1724032662728-494206dc-1475-7b96-c685-ee2095cac850.png",
    "merge_url": "https://r2-aivid-000-prod.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/133902/asset/202408/1724032662728-494206dc-1475-7b96-c685-ee2095cac850.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240819%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240819T015742Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=47bd8316b7b013c51ce993781efec2f07c54c444f5b7a2bbe0f4e2fb1e4d36fd",
    "thumbnail_key": "133902/asset/202408/1724032661400-b67c7abe-1ac4-9551-eeaf-bcd6c2419f28.png",
    "thumbnail_url": "https://r2-aivid-000-prod.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/133902/asset/202408/1724032661400-b67c7abe-1ac4-9551-eeaf-bcd6c2419f28.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240819%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240819T015741Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=e8da3e7f4b448a3b5e5779829eff82626852c4f3f87908898735735358bde2c5",
    "thumbnail_width": 1080,
    "thumbnail_height": 540
}

Video Face Swap

Parameter	Type	Description
size	int	The size of the result video
duration	float	The duration of the result video
merge_key	string	An unique id representing your result video
merge_url	string	The signatured url of the result video
merge_width	int	The width of the result video
merge_height	int	The height of the result video
cover_key	string	An unique id representing your result video cover
cover_url	string	The signatured url of the result video cover
cover_width	int	The width of the result video cover
cover_height	int	The height of the result video cover
cover_thumbnail_key	int	An unique id representing your result video thumbnail
cover_thumbnail_url	int	The signatured url of the result video thumbnail
thumbnail_width	int	The width of the result video thumbnail
thumbnail_height	int	The height of the result video thumbnail

Response

"additional_data": {
    "size": 7614239,
    "duration": 12.746067,
    "cover_key": "133902/asset/202408/1724035525663-9a94c106-b62f-0512-6a6d-5394e348052a.png",
    "cover_url": "https://r2-aivid-000-prod.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/133902/asset/202408/1724035525663-9a94c106-b62f-0512-6a6d-5394e348052a.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240819%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240819T024525Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=0859318be5b893fdd21da3994fcf35b95af361e4b66eb32d04b985163287ea20",
    "merge_key": "133902/asset/202408/1724035528103-780ce768-d5f7-5512-1593-e8918046fd28.mp4",
    "merge_url": "https://r2-aivid-000-prod.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/133902/asset/202408/1724035528103-780ce768-d5f7-5512-1593-e8918046fd28.mp4?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240819%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240819T024528Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=8ab1c24cd09652b4323ab6e82c0c8321621522e0789833805c5f0dcaa0bd67fb",
    "cover_width": 1080,
    "merge_width": 1080,
    "cover_height": 554,
    "merge_height": 554,
    "thumbnail_width": 1080,
    "thumbnail_height": 540,
    "cover_thumbnail_key": "133902/asset/202408/1724035526966-bd9f9b5f-2caf-fa3c-130b-5edf1004c18e.png",
    "cover_thumbnail_url": "https://r2-aivid-000-prod.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/133902/asset/202408/1724035526966-bd9f9b5f-2caf-fa3c-130b-5edf1004c18e.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240819%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240819T024526Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=1444bd85e37f7185469b98110c080b6429d3a74e3f077d6ece2c5550c6a3ef4f"
}

Get Multiple Faces

Parameter	Type	Description
kps	object	The height of the result video thumbnail
x	int	X-point in relation to the face
y	int	Y-point in relation to the face
size	string	The size of the result image
width	string	The width of the result image
height	string	The height of the result image
avatar_part_key	string	An unique key representing your original face
avatar_part_url	int	The signatured url of your original face

Response

 "additional_data": [
    {
        "kps": {
            "1": {
                "x": 27,
                "y": 45
            },
            "2": {
                "x": 67,
                "y": 45
            },
            "3": {
                "x": 49,
                "y": 75
            },
            "4": {
                "x": 24,
                "y": 84
            },
            "5": {
                "x": 65,
                "y": 85
            }
        },
        "size": 17913,
        "width": 87,
        "height": 121,
        "avatar_part_key": "temporary/20240819/133902/1724036183137-329eead9-1ac9-526b-f849-7e57e26b6826.png",
        "avatar_part_url": "https://r2-aisevendaydelete-000-prod.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/temporary/20240819/133902/1724036183137-329eead9-1ac9-526b-f849-7e57e26b6826.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240819%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240819T025623Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=794ece6c5429ac3d46d9f25b0b2f2928e644df0ceee7400bb10d3041766dcfcd"
    },
    {
        "kps": {
            "1": {
                "x": 17,
                "y": 61
            },
            "2": {
                "x": 59,
                "y": 61
            },
            "3": {
                "x": 33,
                "y": 86
            },
            "4": {
                "x": 20,
                "y": 106
            },
            "5": {
                "x": 57,
                "y": 106
            }
        },
        "size": 21322,
        "width": 93,
        "height": 137,
        "avatar_part_key": "temporary/20240819/133902/1724036183705-887bffbf-9f96-9e3a-5d7f-d831e0885790.png",
        "avatar_part_url": "https://r2-aisevendaydelete-000-prod.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/temporary/20240819/133902/1724036183705-887bffbf-9f96-9e3a-5d7f-d831e0885790.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240819%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240819T025623Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=e2e745afca9448810a528828cf8922d7c9378716bdfd9872bb321d06493a7c82"
    }
]

Multiple Image Face Swap

Parameter	Type	Description
size	int	The size of the result image
width	int	The width of the result image
height	int	The height of the result image
merge_key	string	An unique id representing your result image
merge_url	string	The signatured url of the result image
thumbnail_key	string	An unique id representing your result image thumbnail
thumbnail_url	string	The signatured url of the result image thumbnail
thumbnail_width	int	The width of the result image thumbnail
thumbnail_height	int	The height of the result image thumbnail

Response

  "additional_data": {
    "size": 568411,
    "width": 564,
    "height": 846,
    "merge_key": "133902/asset/202408/172403774488-a48671d3-9ced-1db3-545b-c4a578439d84.png",
    "merge_url": "https://r2-aivid-000-prod.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/133902/asset/202408/172403774488-a48671d3-9ced-1db3-545b-c4a578439d84.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240819%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240819T032224Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=510628e424fdc4471de3b030c409d38aad70d1b26b6edc49d3d02eff2b216a21",
    "thumbnail_key": "133902/asset/202408/1724037742729-badda78b-7e93-a551-306f-5da03c6a6026.png",
    "thumbnail_url": "https://r2-aivid-000-prod.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/133902/asset/202408/1724037742729-badda78b-7e93-a551-306f-5da03c6a6026.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240819%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240819T032222Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=f47b55427d813476479fd27df79d4c0dbd87dae26cea782abde0a614e2e35bb2",
    "thumbnail_width": 1080,
    "thumbnail_height": 540
}

Multiple Video Face Swap

Parameter	Type	Description
size	int	The size of the result video
duration	float	The duration of the result video
merge_key	string	An unique id representing your result video
merge_url	string	The signatured url of the result video
merge_width	int	The width of the result video
merge_height	int	The height of the result video
cover_key	string	An unique id representing your result video cover
cover_url	string	The signatured url of the result video cover
cover_width	int	The width of the result video cover
cover_height	int	The height of the result video cover
cover_thumbnail_key	int	An unique id representing your result video thumbnail
cover_thumbnail_url	int	The signatured url of the result video thumbnail
thumbnail_width	int	The width of the result video thumbnail
thumbnail_height	int	The height of the result video thumbnail

Response

"additional_data": {
    "size": 2445521,
    "duration": 7.340667,
    "cover_key": "133902/asset/202408/1724045465751-b700e96f-b0dc-0956-d43d-a5da96404ce3.png",
    "cover_url": "https://r2-aivid-000-prod.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/133902/asset/202408/1724045465751-b700e96f-b0dc-0956-d43d-a5da96404ce3.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240819%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240819T053105Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=6d3b952800214fec950ca5e77d34bebd03c7ce91d4e0e65e8ceebc6dcd8fe5e0",
    "merge_key": "133902/asset/202408/1724045468726-9601be56-b0c9-62b8-6d3e-5aae88d50fbb.mp4",
    "merge_url": "https://r2-aivid-000-prod.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/133902/asset/202408/1724045468726-9601be56-b0c9-62b8-6d3e-5aae88d50fbb.mp4?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240819%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240819T053108Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=bfc2a035c0df2bd5af633dcd18485026df6756b8afedc2b3f3a4060cde6b3596",
    "cover_width": 1080,
    "merge_width": 1080,
    "cover_height": 608,
    "merge_height": 608,
    "thumbnail_width": 1080,
    "thumbnail_height": 540,
    "cover_thumbnail_key": "133902/asset/202408/1724045467156-a97f8e8b-b723-7c99-d6ef-8eb9c17fa598.png",
    "cover_thumbnail_url": "https://r2-aivid-000-prod.214dcedd27630abef236dcb67de0ce92.r2.cloudflarestorage.com/133902/asset/202408/1724045467156-a97f8e8b-b723-7c99-d6ef-8eb9c17fa598.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=91ac9d3ee865be05c575d38c9bdd1275%2F20240819%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20240819T053107Z&X-Amz-SignedHeaders=host&X-Amz-Expires=259200&X-Amz-Signature=d3e83c701ae19ea516d72a0fbe056b5b744d059806f2ee566df5adb3f4186645"
}

Response Code Description

Please note that if the value of the response code is not equal to 200, the request is failed or wrong

Parameter	Type	Description
code	200	Success
code	400	Request parameter error
code	401	Authorization failed(e.g. The token is invalid or expired)
code	500	Server exception occurred
code	601	Task exception occurred
code	602	No face detected
code	603	Multiple faces detected
code	604	The file may not meet our policy requirement(e.g. NSFW)
code	605	The target photo may not meet our policy requirement(e.g. The celebrities)
code	701	File exception occurred(e.g. File upload error)
code	702	The source file for the key was not found
code	703	Only supported formats: JPG, PNG, WEBP, GIF, M4V, MP4, MOV and WEBM
code	704	Only supported files: Max 500 MB
code	801	Not enough credits
code	802	Not enough requests