Face Compare

Compare between the two images if the person in the image is the same person.

API Version

Version 1 (Deprecated)Version 2 (Deprecated)Version 3 (Latest)

Image Requirements

Type : JPG (JPEG), PNG
Format : Base64
Size : Must be over 480*480 pixels
Minimum size of face : The bounding size of a detected face should be over than 112 pixels.

POST https://api.aigen.online/aiface/face-compare/v3

Request Parameters

Name	Type	Description
image1*	String	Base64 encoded binary data of the first image.
image2*	String	Base64 encoded binary data of the second image.
threshold	Integer	The similarity threshold [0, 100] determines whether two faces match or not. Setting the threshold to 0 always returns a similarity score. Note: default value is 80.
verified_document	Boolean	Whether or not to verify that the image contains an ID card. Note: default value is False.
image1_is_document	Boolean	To verify whether image1 contains an ID Card. Note: default value is False.
image2_is_document	Boolean	To verify whether image2 contains an ID Card. Note: default value is False.
image1_check_face_quality	Boolean	Set to true to check the quality of image1 with the Face Quality service. The result is returned in face_quality.image1. Note: default value is False. Only the images you enable are sent to Face Quality. If the Face Quality service is unavailable, the request is not rejected and face_quality is omitted from the response.
image2_check_face_quality	Boolean	Same as image1_check_face_quality, for image2. Note: default value is False.
face_quality_threshold	Float	Minimum quality_confidence [0, 1] that an image checked by Face Quality must reach before the comparison runs. The request fails with FACE_QUALITY_TOO_LOW when an image has no face, has more than one face, or scores below this value. Note: default value is 0.6. Applies only to images with the face quality check enabled.

Return Values

Fields	Type	Description
request_id	String	Unique ID for each request.
score	Float	A similarity score [0,100] indicating the similarity of two faces. A higher score indicates a higher possibility that two faces belong to the same person. Note: if no face is detected within the image uploaded or the two faces do not match each other, this field will not be returned.
match	Boolean	A boolean indicating whether the two faces match or not.
time_used	Float	Duration. Unit: second
face_quality	Object	Face Quality result, returned only when image1_check_face_quality or image2_check_face_quality is true and the Face Quality service responded. Contains image1 and/or image2, each with num_faces (Integer, number of faces detected) and quality_confidence (Float [0, 1], higher is better). An image with no detected face is returned as null.
error_message	String	This field will not be returned unless the request fails. For more details, please see the following section on error message.

Error Message

HTTP Status	Error Message	Description
200		Face comparison successful.
400	FACE_NOT_DETECTED	A face was not detected in one or both images.
400	FACE_QUALITY_TOO_LOW: <image>	The image <image> failed the face quality check: no face, more than one face, or quality_confidence below face_quality_threshold. Multiple images are comma-separated.
400	ID_CARD_NOT_DETECTED: <image>	The image <image> does not contain an ID card.
400	ID_CARD_DETECTION_ERROR: <image>	An error occurs during ID card detection.
400	IMAGE_ERROR_UNSUPPORTED_FORMAT: <image>	The image <image> cannot be processed. The file format may not be supported or the file is damaged.
422		The request contains invalid request schema.

Response Examples

200: Match

{
  "request_id": "string",
  "score": 99.80358123779297,
  "match": true,
  "time_used": 2.168225316999724
}

200: Match (with Face Quality)

{
  "request_id": "string",
  "score": 99.80358123779297,
  "match": true,
  "time_used": 2.6511427830001,
  "face_quality": {
    "image1": { "num_faces": 1, "quality_confidence": 0.91 },
    "image2": { "num_faces": 1, "quality_confidence": 0.84 }
  }
}

200: Not Match

{
  "request_id": "string",
  "match": false,
  "time_used": 0.7945219540001744
}

400: Face Not Detected

{
  "request_id": "string",
  "time_used": 5.193959645926952,
  "error_message": "FACE_NOT_DETECTED"
}

400: Face Quality Too Low

{
  "request_id": "string",
  "time_used": 0.5213904720003,
  "error_message": "FACE_QUALITY_TOO_LOW: image2",
  "face_quality": {
    "image1": { "num_faces": 1, "quality_confidence": 0.91 },
    "image2": { "num_faces": 1, "quality_confidence": 0.31 }
  }
}

400: ID Card Not Detected

{
  "request_id": "string",
  "time_used": 0.6722503704950213,
  "error_message": "ID_CARD_NOT_DETECTED: image2"
}

400: ID Card Detection Error

{
  "request_id": "string",
  "time_used": 0.6722503704950213,
  "error_message": "ID_CARD_DETECTION_ERROR: image2"
}

400: Unsupported Format

{
  "request_id": "string",
  "time_used": 0.00041714590042829514,
  "error_message": "IMAGE_ERROR_UNSUPPORTED_FORMAT: image1"
}

422: Unprocessable Entity

{
  "detail": [
    {
      "loc": ["body", "image1"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Code Examples

Python

import requests
import json

api = "https://api.aigen.online/aiface/face-compare/v3"
headers = {"x-aigen-key": "<key>", "content-type": "application/json"}
data = json.dumps({
    "image1": "<base64_string>",
    "image2": "<base64_string>",
    "threshold": 80,
    "image1_check_face_quality": True,
    "image2_check_face_quality": True,
    "face_quality_threshold": 0.6,
})

res = requests.post(api, data=data, headers=headers)
print(res.json())

Nodejs

const axios = require("axios");

const api = "https://api.aigen.online/aiface/face-compare/v3";
const headers = {
  "x-aigen-key": "<key>",
};
const data = {
  image1: "<base64_string>",
  image2: "<base64_string>",
  threshold: 80,
  image1_check_face_quality: true,
  image2_check_face_quality: true,
  face_quality_threshold: 0.6,
};

axios
  .post(api, data, { headers: headers })
  .then((res) => {
    console.log(res.data);
  })
  .catch((err) => {
    console.error(err.response.data);
  });

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.aigen.online/aiface/face-compare/v3',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode([
    'image1' => '<base64_string>',
    'image2' => '<base64_string>',
    'threshold' => 80,
    'image1_check_face_quality' => true,
    'image2_check_face_quality' => true,
    'face_quality_threshold' => 0.6
  ]),
  CURLOPT_HTTPHEADER => array(
    'X-AIGEN-KEY: <aigen-key>',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
?>

cURL

curl --location 'https://api.aigen.online/aiface/face-compare/v3' \
--header 'X-AIGEN-KEY: <aigen-key>' \
--header 'Content-Type: application/json' \
--data '{
  "image1": "<base64_string>",
  "image2": "<base64_string>",
  "threshold": 80,
  "image1_check_face_quality": true,
  "image2_check_face_quality": true,
  "face_quality_threshold": 0.6
}'