Face

Compare Face

This method helps you to compare face between 2 images <br> You will receive a response consists of message and an error code if the request fails to process. The following is a list of error codes. <br>

Error status	Error code	Description
200	FAIL_ON_1	fail on liveness
200	FAIL_ON_2	fail on attribute
200	FAIL_ON_3	fail on liveness and attribute
200	FAIL_ON_4	fail on quality
200	FAIL_ON_5	fail on liveness and quality
200	FAIL_ON_6	fail on attribute and quality
200	FAIL_ON_7	fail on liveness, attribute, and quality
200	FAIL_ON_8	fail on number of face (nface)
200	FAIL_ON_9	fail on number of face (nface) and liveness
200	FAIL_ON_10	fail on number of face (nface) and attribute
200	FAIL_ON_11	fail on number of face (nface), attribute, and liveness
200	FAIL_ON_12	fail on number of face (nface) and quality
200	FAIL_ON_13	fail on number of face (nface), quality, and liveness
200	FAIL_ON_14	fail on number of face (nface), quality, and attribute
200	FAIL_ON_15	fail on number of face (nface), quality, attribute, and liveness
200	FAIL_ON_16	fail on similarity status
400	INVALID_PAYLOAD	no value in payload or empty string more than 1
400	INVALID_PAYLOAD_IMAGE_1_MISSING	invalid payload image 1 not a standard b64/url or image empty string
400	INVALID_PAYLOAD_IMAGE_2_MISSING	invalid payload image 2 not a standard b64/url or image empty string
400	INVALID_PAYLOAD_IMAGE_1_SIZE	invalid payload image 1 size too large
400	INVALID_PAYLOAD_IMAGE_2_SIZE	invalid payload image 2 size too large
400	MISSING_PAYLOAD_IMAGE_1	missing payload image 1
400	MISSING_PAYLOAD_IMAGE_2	missing payload image 2
400	INVALID_PAYLOAD_IMAGE_1_TIMEOUT	timeout getting image 1 from url in 15 seconds
400	INVALID_PAYLOAD_IMAGE_2_TIMEOUT	timeout getting image 2 from url in 15 seconds
400	INVALID_PAYLOAD_IMAGE_1_FORMAT	image unable to be decoded/got from url OR invalid image 1 extension
400	INVALID_PAYLOAD_IMAGE_2_FORMAT	image unable to be decoded/got from url OR invalid image 2 extension
400	FACE_NOT_DETECTED	face not detected from image
400	INVALID_PAYLOAD_QUALITY_VALIDATION_DEPENDENCY	is_quality must be true if validate_quality true
400	INVALID_PAYLOAD_ATTRIBUTE_VALIDATION_DEPENDENCY	is_attribute must be true if validate_attribute true
400	INVALID_PAYLOAD_LIVENESS_VALIDATION_DEPENDENCY	is_liveness must be true if validate_liveness true
400	INVALID_PAYLOAD_THRESHOLD_MISSING	threshold must be basic/moderate/high
403	INSUFFICIENT_QUOTA_COMPARE	usage reach it quota limit for compare (only appears on testing mode)
403	INSUFFICIENT_QUOTA_LIVENESS	usage reach it quota limit for liveness (only appears on testing mode)
500	INTERNAL_SERVER_ERROR	internal server error

post/v1/face/compare

Request

Base URL
https://api.verihubs.com
URL
https://api.verihubs.com/v1/face/compare
Auth
none declared. Required headers: App-ID, API-Key

Headers

App-IDstring required

API-Keystring required

Request body

image_1string required

An image file, base64 or URL of the first person.

image_2string required

An image file, base64 or URL of the second person.

is_qualityboolean

A flag to determine whether Image Quality (blur, dark, grayscale) will be computed and return as result. Quality will be computed for both image_1 and image_2 when set as true

is_attributeboolean

A flag to determine whether Image Attribute (sunglasses, mask, veil, hat) will be detected and return as result. Attribute will be computed for both image_1 and image_2 when set as true

is_livenessboolean

A flag to determine whether Passive Liveness will be computed and return as result. Liveness will be computed for both image_1 and image_2 when set as true. When is_liveness is set to true, it is best that validate_quality is set to true, as liveness is influenced by Quality.

validate_qualityboolean

Determines whether Quality validation will be executed. The validation consists of checking blur and dark with threshold, and also checking whether the image is a black & white image (grayscale is true).

validate_attributeboolean

Determines whether attribute validation will be executed. The validation consists of checking whether sunglasses or mask is detected in the input image.

validate_livenessboolean

Determines whether Liveness validation will be executed. The validation checks whether input image is live / spoof.

thresholdstring

Determines which threshold level will be used. The threshold either basic/moderate/high

validate_nfaceboolean

Determines whether the number of faces validation will be executed. The validation checks whether the input image consists of more than one face.

Response

Successful Response

status_codestring

Status Code

messagestring required

Message

session_idstring

unique id to represent transaction record

similarity_statusboolean

Shows similarity result

timestampnumber

Shows time which face compared successfully

Example response

{
  "status_code": "FACE-1",
  "message": "Face compared successfully",
  "image_1": {
    "liveness": {
      "probability": "100"
    },
    "nface": 1,
    "bounding_box": {
      "TopLeftX": "0.9",
      "TopLeftY": "0.9",
      "BottomRightX": "0.9",
      "BottomRightY": "0.9",
      "Width": "0.9",
      "Height": "0.9"
    },
    "face_landmark": {
      "LeftEyeX": "0.9",
      "LeftEyeY": "0.9",
      "RightEyeX": "0.9",
      "RightEyeY": "0.9",
      "NoseX": "0.9",
      "NoseY": "0.9",
      "MouthLeftX": "0.9",
      "MouthLeftY": "0.9",
      "MouthRightX": "0.9",
      "MouthRightY": "0.9"
    }
  },
  "image_2": {
    "liveness": {
      "probability": "100"
    },
    "nface": 1,
    "bounding_box": {
      "TopLeftX": "0.9",
      "TopLeftY": "0.9",
      "BottomRightX": "0.9",
      "BottomRightY": "0.9",
      "Width": "0.9",
      "Height": "0.9"
    },
    "face_landmark": {
      "LeftEyeX": "0.9",
      "LeftEyeY": "0.9",
      "RightEyeX": "0.9",
      "RightEyeY": "0.9",
      "NoseX": "0.9",
      "NoseY": "0.9",
      "MouthLeftX": "0.9",
      "MouthLeftY": "0.9",
      "MouthRightX": "0.9",
      "MouthRightY": "0.9"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.