Request Example:

curl -X POST "https://api.advance.ai/intl/openapi/face-identity/v1/face-comparison" \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: multipart/form-data" \
-F "firstImage=@/Users/lby/Desktop/firstImage.jpg" \
-F "secondImage=@/Users/lby/Desktop/secondImage.jpg" \
-D "region": "VN"

Request Url

https://api.advance.ai/intl/openapi/face-identity/v1/face-comparison
POST (multipart/form-data)

https://sg-api.advance.ai/intl/openapi/face-identity/v1/face-comparison
POST (multipart/form-data)

https://th-api.advance.ai/intl/openapi/face-identity/v1/face-comparison
POST (multipart/form-data)

https://ph-api.advance.ai/intl/openapi/face-identity/v1/face-comparison
POST (multipart/form-data)

https://mex-api.advance.ai/intl/openapi/face-identity/v1/face-comparison
POST (multipart/form-data)

https://nga-api.advance.ai/intl/openapi/face-identity/v1/face-comparison
POST (multipart/form-data)

https://my-api.advance.ai/intl/openapi/face-identity/v1/face-comparison
POST (multipart/form-data)

Request Header Parameters

Parameter	Description
X-ACCESS-TOKEN	`string` Please use Token Authentication API to get your access token.

Request Parameters

Parameter	Description
firstImage	`file` or `string`The first image for comparison. Supports file upload or Base64-encoded string. Refer to Image Quality Requirements.
secondImage	`file` or `string` The second image for comparison. Supports file upload or Base64-encoded string. Refer to Image Quality Requirements.
region	`string` The region that the faces belongs to. Refer to ISO ALPHA-3 Country Code.

Note:

Added support for flip angle photos. Supported flip angles include: 90°, 180°, 270°. If the image is flipped, it will have a certain impact on the accuracy.

If there are multiple faces in the photo, the largest face will be selected for comparison.

Image Quality Requirements

The services check and extract the necessary information from the uploaded images, hence please ensure the uploaded images satisfy the following criteria:

Is in one of the following image formats: PNG / JPG / JPEG
Below 2 MB file size
Minimum resolution of 256 x 256
Maximum resolution of 4096 x 4096

Response Description

Parameter	Description
code	`enum` Response's Status Code.
transactionId	`string` The request id, the max length is 64.
pricingStrategy	`enum` Whether the request will be charged, enum type: `FREE`, `PAY`
message	`string` Status Code Explanation.
data	`object` The result of the comparison.
extra	`object` Extra response info (Exception Message).

Response.code

Status Code	Message
SUCCESS	`pay` OK
NO_FACE_DETECTED_FROM_FIRST_IMAGE	`pay` No Face detected from the uploaded first picture.
NO_FACE_DETECTED_FROM_SECOND_IMAGE	`pay` No Face detected from the uploaded second picture.
FIRST_IMAGE_LOW_QUALITY_FACE	`pay` Face quality is too low of the uploaded first picture.
SECOND_IMAGE_LOW_QUALITY_FACE	`pay` Face quality is too low of the uploaded second picture.
PARAMETER_ERROR	`free` Invalid image format,image format should be one of jpeg/jpg/png, and request content type should be image/jpeg or image/png.
	`free` Invalid image size,max image size should be less than 2M,and image dimension should be between 256 256 and 4096 4096.
	`free` Invalid base64 image format.
	`free` Parameter should not be empty.
REGION_WRONG	`free` Region is wrong.
ERROR	`free` Server error.

Response.data

Field	Description
similarity	`float` Face similarity rate. Refer to Response.data.similarity
firstFace	`object` The face in the first picture.
secondFace	`object` The face in the second picture.

Response.data.similarity

Face similarity rate between the 2 uploaded pictures, the rate value is always between the number 0-100, the closer the rate to 100, the more similar the two faces are.

If the faces similarity is more than 70, the suggestion is pass.
If the faces similarity is from 55 to 70, the suggestion is manual check.
If the faces similarity is less than 55，the suggestion is rejection or using other methods to verify the user’s identity.

Response.data.firstFace/secondFace

Field	Description
id	`string` The identifier for the face in the picture.
top	`double` The pixel size from the top edge of the picture.
bottom	`double` The pixel size from the bottom edge of the picture.
left	`double` The pixel size from the left edge of the picture.
right	`double` The pixel size from the right edge of the picture.
gender	`string` Gender of the person. `MALE` / `FEMALE`.

Response Examples

SUCCESS

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
            "similarity":87.0,
            "firstFace":{
                "id":"1",
                "top":113.436279296875,
                "bottom":336.11370849609375,
                "left":259.3328552246094,
                "right":415.51715087890625,
                "gender":"MALE"
                },
            "secondFace":{
                "id":"2",
                "top":111.61112976074219,
                "bottom":253.23887634277344,
                "left":171.38746643066406,
                "right":278.3250427246094,
                "gender":"MALE"
        }
    },
    "extra":null,
    "transactionId":"a910b6279667a977",
    "pricingStrategy":"PAY"
}

NO_FACE_DETECTED_FROM_FIRST_IMAGE

{

    "code":"NO_FACE_DETECTED_FROM_FIRST_IMAGE",
    "message":"No Face detected from the uploaded first picture",
    "data":null,
    "extra":null,
    "transactionId":"880463f1b01c449e",
    "pricingStrategy":"PAY"
}

NO_FACE_DETECTED_FROM_SECOND_IMAGE

{
    "code":"NO_FACE_DETECTED_FROM_SECOND_IMAGE",
    "message":"No Face detected from the uploaded second picture",
    "data":null,
    "extra":null,
    "transactionId":"f8585498452aa230",
    "pricingStrategy":"PAY"
}

FIRST_IMAGE_LOW_QUALITY_FACE

{
    "code":"FIRST_IMAGE_LOW_QUALITY_FACE",
    "message":"Face quality is too low of the uploaded first picture",
    "data":null,
    "extra":null,
    "transactionId":"8f678b4a2607ca3c",
    "pricingStrategy":"PAY"
}

SECOND_IMAGE_LOW_QUALITY_FACE

{
    "code":"SECOND_IMAGE_LOW_QUALITY_FACE",
    "message":"Face quality is too low of the uploaded second picture",
    "data":null,
    "extra":null,
    "transactionId":"bd3d550e751424d2",
    "pricingStrategy":"PAY"
}

REGION_WRONG

{
    "code":"REGION_WRONG",
    "message":"Region is wrong",
    "data":null,
    "extra":null,
    "transactionId":"a83fef16ea49b0fb",
    "pricingStrategy":"FREE"
}

PARAMETER_ERROR

{
    "code":"PARAMETER_ERROR",
    "message":"Invalid image size,max image size should be less than 2M,and image dimension should be between 256 * 256 and 4096 * 4096",
    "data":null,
    "extra":null,
    "transactionId":"cd9244088a1be373",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Invalid image format,image format should be one of jpeg/jpg/png,and request content type should be image/jpeg or image/png",
    "data":null,
    "extra":null,
    "transactionId":"9f37bfcdfd00cee8",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Invalid base64 image format",
    "data":null,
    "extra":null,
    "transactionId":"c92f9101481bc77d",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter should not be empty",
    "data":null,
    "extra":null,
    "transactionId":"c92f9101481bc77d",
    "pricingStrategy":"FREE"
}

ERROR

{
    "code":"ERROR",
    "message":"Server error",
    "data":null,
    "extra":null,
    "transactionId":"1deae5a13ef2bd5e",
    "pricingStrategy":"FREE"

}