---
updatedAt: 2026-08-07T08:07:19.000Z
agentTools:
projectIndex: https://docs.verihubs.com/llms.txt
---
# Compare Face
This method helps you to compare face between 2 images
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.
| 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 |
# OpenAPI definition
```json
{
"openapi": "3.0.2",
"servers": [
{
"url": "https://api.verihubs.com"
}
],
"info": {
"title": "AI API Documentation",
"version": "2.0.0"
},
"tags": [
{
"name": "Face",
"description": "Get information about Face API"
}
],
"paths": {
"/v1/face/compare": {
"post": {
"tags": [
"Face"
],
"summary": "Compare Face",
"description": "This method helps you to compare face between 2 images\n
\nYou 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.\n
\n\n| Error status | Error code | Description |\n| -----------------------------|:---------------------------------------------|:---------------------------------------------|\n| 200 | FAIL_ON_1 | fail on liveness |\n| 200 | FAIL_ON_2 | fail on attribute |\n| 200 | FAIL_ON_3 | fail on liveness and attribute |\n| 200 | FAIL_ON_4 | fail on quality |\n| 200 | FAIL_ON_5 | fail on liveness and quality |\n| 200 | FAIL_ON_6 | fail on attribute and quality |\n| 200 | FAIL_ON_7 | fail on liveness, attribute, and quality |\n|200 | FAIL_ON_8 | fail on number of face (nface) |\n|200 | FAIL_ON_9 | fail on number of face (nface) and liveness |\n|200 | FAIL_ON_10 | fail on number of face (nface) and attribute |\n|200 | FAIL_ON_11 | fail on number of face (nface), attribute, and liveness |\n|200 | FAIL_ON_12 | fail on number of face (nface) and quality|\n|200 | FAIL_ON_13 | fail on number of face (nface), quality, and liveness |\n|200 | FAIL_ON_14 | fail on number of face (nface), quality, and attribute |\n|200 | FAIL_ON_15 | fail on number of face (nface), quality, attribute, and liveness |\n|200 | FAIL_ON_16 | fail on similarity status |\n| 400 | INVALID_PAYLOAD | no value in payload or empty string more than 1 |\n| 400 | INVALID_PAYLOAD_IMAGE_1_MISSING | invalid payload image 1 not a standard b64/url or image empty string |\n| 400 | INVALID_PAYLOAD_IMAGE_2_MISSING | invalid payload image 2 not a standard b64/url or image empty string |\n| 400 | INVALID_PAYLOAD_IMAGE_1_SIZE | invalid payload image 1 size too large |\n| 400 | INVALID_PAYLOAD_IMAGE_2_SIZE | invalid payload image 2 size too large |\n| 400 | MISSING_PAYLOAD_IMAGE_1 | missing payload image 1 |\n| 400 | MISSING_PAYLOAD_IMAGE_2 | missing payload image 2 |\n| 400 | INVALID_PAYLOAD_IMAGE_1_TIMEOUT | timeout getting image 1 from url in 15 seconds |\n| 400 | INVALID_PAYLOAD_IMAGE_2_TIMEOUT | timeout getting image 2 from url in 15 seconds |\n| 400 | INVALID_PAYLOAD_IMAGE_1_FORMAT | image unable to be decoded/got from url OR invalid image 1 extension |\n| 400 | INVALID_PAYLOAD_IMAGE_2_FORMAT | image unable to be decoded/got from url OR invalid image 2 extension |\n| 400 | FACE_NOT_DETECTED | face not detected from image |\n| 400 | INVALID_PAYLOAD_QUALITY_VALIDATION_DEPENDENCY | is_quality must be true if validate_quality true |\n| 400 | INVALID_PAYLOAD_ATTRIBUTE_VALIDATION_DEPENDENCY | is_attribute must be true if validate_attribute true |\n| 400 | INVALID_PAYLOAD_LIVENESS_VALIDATION_DEPENDENCY | is_liveness must be true if validate_liveness true |\n| 400 | INVALID_PAYLOAD_THRESHOLD_MISSING | threshold must be basic/moderate/high |\n| 403 | INSUFFICIENT_QUOTA_COMPARE | usage reach it quota limit for compare (only appears on testing mode)|\n| 403 | INSUFFICIENT_QUOTA_LIVENESS | usage reach it quota limit for liveness (only appears on testing mode) |\n| 500 | INTERNAL_SERVER_ERROR | internal server error |\n",
"operationId": "compare_face_post",
"parameters": [
{
"required": true,
"schema": {
"title": "App-ID",
"type": "string"
},
"name": "App-ID",
"in": "header"
},
{
"required": true,
"schema": {
"title": "API-Key",
"type": "string"
},
"name": "API-Key",
"in": "header"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompareFace"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseCompareFace"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationError"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationUnauthorized"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationError"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ValidationError": {
"title": "ValidationError",
"required": [
"message",
"error_code"
],
"type": "object",
"properties": {
"message": {
"title": "Message",
"type": "string"
},
"error_code": {
"title": "Error_code",
"type": "string"
}
}
},
"ValidationUnauthorized": {
"title": "ValidationUnauthorized",
"required": [
"message"
],
"type": "object",
"properties": {
"message": {
"title": "Message",
"type": "string",
"example": "Authorization failed"
}
}
},
"CompareFace": {
"title": "CompareFace",
"required": [
"image_1",
"image_2"
],
"type": "object",
"properties": {
"image_1": {
"description": "An image file, base64 or URL of the first person.",
"type": "string"
},
"image_2": {
"description": "An image file, base64 or URL of the second person.",
"type": "string"
},
"is_quality": {
"description": "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",
"type": "boolean",
"default": true
},
"is_attribute": {
"description": "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",
"type": "boolean",
"default": true
},
"is_liveness": {
"description": "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.",
"type": "boolean",
"default": false
},
"validate_quality": {
"description": "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).",
"type": "boolean",
"default": false
},
"validate_attribute": {
"description": "Determines whether attribute validation will be executed. The validation consists of checking whether sunglasses or mask is detected in the input image.",
"type": "boolean",
"default": false
},
"validate_liveness": {
"description": "Determines whether Liveness validation will be executed. The validation checks whether input image is live / spoof.",
"type": "boolean",
"default": false
},
"threshold": {
"description": "Determines which threshold level will be used. The threshold either basic/moderate/high",
"type": "string"
},
"validate_nface": {
"description": "Determines whether the number of faces validation will be executed. The validation checks whether the input image consists of more than one face.",
"type": "boolean",
"default": false
}
}
},
"ResponseCompareFace": {
"title": "ResponseCompareFace",
"required": [
"message"
],
"type": "object",
"properties": {
"status_code": {
"description": "Status Code",
"type": "string",
"example": "FACE-1"
},
"message": {
"description": "Message",
"type": "string",
"example": "Face compared successfully"
},
"session_id": {
"description": "unique id to represent transaction record",
"type": "string"
},
"image_1": {
"description": "Image 1",
"type": "object",
"properties": {
"attributes": {
"type": "object",
"properties": {
"sunglasses_on": {
"type": "boolean"
},
"mask_on": {
"type": "boolean"
},
"veil_on": {
"type": "boolean"
},
"hat_on": {
"type": "boolean"
}
}
},
"liveness": {
"description": "Liveness attribute",
"type": "object",
"properties": {
"status": {
"type": "boolean"
},
"probability": {
"type": "string",
"example": "100"
}
}
},
"image_quality": {
"description": "Shows quality of image",
"type": "object",
"properties": {
"blur": {
"type": "boolean"
},
"dark": {
"type": "boolean"
},
"grayscale": {
"type": "boolean"
}
}
},
"rotation": {
"description": "Shows how many rotations need to be done to detect face in image",
"type": "integer"
},
"nface": {
"description": "Shows how many faces are detected in the input image.",
"type": "integer",
"example": 1
},
"bounding_box": {
"description": "Shows result of bounding box",
"type": "object",
"properties": {
"TopLeftX": {
"type": "string",
"example": "0.9"
},
"TopLeftY": {
"type": "string",
"example": "0.9"
},
"BottomRightX": {
"type": "string",
"example": "0.9"
},
"BottomRightY": {
"type": "string",
"example": "0.9"
},
"Width": {
"type": "string",
"example": "0.9"
},
"Height": {
"type": "string",
"example": "0.9"
}
}
},
"face_landmark": {
"description": "Shows result of face landmark",
"type": "object",
"properties": {
"LeftEyeX": {
"type": "string",
"example": "0.9"
},
"LeftEyeY": {
"type": "string",
"example": "0.9"
},
"RightEyeX": {
"type": "string",
"example": "0.9"
},
"RightEyeY": {
"type": "string",
"example": "0.9"
},
"NoseX": {
"type": "string",
"example": "0.9"
},
"NoseY": {
"type": "string",
"example": "0.9"
},
"MouthLeftX": {
"type": "string",
"example": "0.9"
},
"MouthLeftY": {
"type": "string",
"example": "0.9"
},
"MouthRightX": {
"type": "string",
"example": "0.9"
},
"MouthRightY": {
"type": "string",
"example": "0.9"
}
}
}
}
},
"image_2": {
"description": "Image 1",
"type": "object",
"properties": {
"attributes": {
"type": "object",
"properties": {
"sunglasses_on": {
"type": "boolean"
},
"mask_on": {
"type": "boolean"
},
"veil_on": {
"type": "boolean"
},
"hat_on": {
"type": "boolean"
}
}
},
"liveness": {
"description": "Liveness attribute",
"type": "object",
"properties": {
"status": {
"type": "boolean"
},
"probability": {
"type": "string",
"example": "100"
}
}
},
"image_quality": {
"description": "Shows quality of image",
"type": "object",
"properties": {
"blur": {
"type": "boolean"
},
"dark": {
"type": "boolean"
},
"grayscale": {
"type": "boolean"
}
}
},
"rotation": {
"description": "Shows how many rotations need to be done to detect face in image",
"type": "integer"
},
"nface": {
"description": "Shows how many faces are detected in the input image.",
"type": "integer",
"example": 1
},
"bounding_box": {
"description": "Shows result of bounding box",
"type": "object",
"properties": {
"TopLeftX": {
"type": "string",
"example": "0.9"
},
"TopLeftY": {
"type": "string",
"example": "0.9"
},
"BottomRightX": {
"type": "string",
"example": "0.9"
},
"BottomRightY": {
"type": "string",
"example": "0.9"
},
"Width": {
"type": "string",
"example": "0.9"
},
"Height": {
"type": "string",
"example": "0.9"
}
}
},
"face_landmark": {
"description": "Shows result of face landmark",
"type": "object",
"properties": {
"LeftEyeX": {
"type": "string",
"example": "0.9"
},
"LeftEyeY": {
"type": "string",
"example": "0.9"
},
"RightEyeX": {
"type": "string",
"example": "0.9"
},
"RightEyeY": {
"type": "string",
"example": "0.9"
},
"NoseX": {
"type": "string",
"example": "0.9"
},
"NoseY": {
"type": "string",
"example": "0.9"
},
"MouthLeftX": {
"type": "string",
"example": "0.9"
},
"MouthLeftY": {
"type": "string",
"example": "0.9"
},
"MouthRightX": {
"type": "string",
"example": "0.9"
},
"MouthRightY": {
"type": "string",
"example": "0.9"
}
}
}
}
},
"similarity_status": {
"description": "Shows similarity result",
"type": "boolean"
},
"timestamp": {
"description": "Shows time which face compared successfully",
"type": "number"
}
}
}
}
}
}
```