Overview

Our Face API is a complete interface for the operation of face recognition. With just a few simple lines of code provided by Alchera, you can bring fully functioning face recognition to your own service.

The Alchera Face API will empower you and your service with the most up-to-date face detection and matching technologies.

/faces

• By passing an image containing multiple faces, the result of detecting faces in the image is obtained. Landmark points are extracted from the detected faces, and face images are aligned based on the landmark points.

/alignedfaces

• Based on the detected face, the face image is transformed to facilitate feature point vector extraction.

/similarity/v2

• By comparing two aligned images of faces with a threshold, the similarity percentage between the two faces is determined.

/liveness/multiframe

• The algorithm detects whether the visual input is from a real, physically present person at the point of capture.
  
  
  

System-related Information

• Support OS: Ubuntu 16.04, Ubuntu 18.04, CentOS 7, CentOS 8
• Minimum System Requirements: According to the minimum specifications of FaceSDK
• FaceSDK Version: 0.9.5.2
  
  
  

API List

No	Method	URI	Explanation
1	POST	/faces	Request for face detection results
2	POST	/alignedfaces	Face detection result and ordered face image request
3	POST	/similarity/v2	Request for face similarity measurement results
4	POST	/liveness/multiframe	Request for face liveness results

Response Code List

HTTP 1.1 When the method is called, the result_code and result_msg fields are added to the response body. It is used independently of the HTTP Status Code.

return_code	return_msg	Explanation
INF-00	OK.	Success
INF-01	Request body is invalid.	HTTP Request Body is incorrect
INF-02	Request URL Query failed.	HTTP Request URL query failure
INF-03	Cannot find uploaded image file (Invalid request body)	No image file uploaded
INF-04	Content of the image is missing, broken, or incorrect	Decoding failure due to missing, broken, or incorrect image content
INF-05	Image to extract feature size not equal with 112x112x3	Image size for feature point extraction is not 112x112x3
INF-06	FaceSDK - Initialize Error.	Face recognition engine initialization failure
INF-07	FaceSDK - Feature extension Initialize Error.	Face recognition engine initialization failure
INF-08	FaceSDK not ready.	Face recognition engine not ready before inference
INF-09	FaceSDK - Set max detectable count failed.	Recognition engine - failed to set the maximum number of face detection
INF-10	FaceSDK - Set min/max detectable size failed.	Recognition engine - failed to set minimum/maximum face detection size
INF-11	FaceSDK - Run DetectInSingleImage failed.	Recognition engine - error during face detection
INF-12	FaceSDK - Run ExtractFeature failed.	Recognition engine - Error extracting facial feature points
INF-13	Face count unmatched between Detect and AlignFace	Recognition engine - Error while extracting aligned face image
INF-14	FaceSDK - Make Aligned face image failed.	Recognition engine - Error while extracting aligned face image
INF-15	FaceSDK - Deinitialize Error.	Recognition engine shutdown failure
INF-16	FaceSDK - Face Validation Checking Error.	Recognition engine - failure to check reliability when detecting faces
INF-17	FaceSDK - Face not found.	Face detection for similarity calculation failed
INF-18	FaceSDK - Compute feature distance failed.	Error calculating similarity
INF-19	FaceSDK - Check face liveness error.	Recognition engine - Error verifying face authenticity
INF-20	FaceSDK - Check face occlusions error.	Recognition engine - error checking face occulsion
INF-21	FaceSDK - Check if face wearing a mask error.	Recognition engine - Error checking for face mask
INF-22	FaceSDK - Multiframe liveness: Cannot unzip requested zip file.	Recognition engine - Unable to release zip compression file of Multi frame lifetime request
INF-23	FaceSDK - Multiframe liveness: Invalid image filenames in zip.	Recognition engine - Multi frame liveness request Error acquiring images in compressed file
INF-24	FaceSDK - Multiframe liveness: Invalid image files count	Recognition engine - Multi frame liveness requests vary the number of images in the compressed file
INF-25	API is restricted	Use of that API is restricted
INF-26	API Server has expired	The API server has expired

API Detail

POST /faces

API Summary

By delivering an image containing multiple faces, the result of detecting faces within the image is obtained. You can specify the minimum and maximum size and maximum number of face detections respectively. If not specified otherwise, the default values specified below are applied to detect faces.

Request Query

Item	Explanation	Example
minsize	Minimum face detection size	/faces?minsize=48
maxsize	Maximum face detection size	/faces?maxsize=150
detectcount	Maximum number of face detections	/faces?detectcount=5

If minsize is not specified, it defaults to 48.
If maxsize is larger than the requested image, set the size of the image to maxsize.
If detectcount is not specified, it defaults to 10.

Request Header

Item	Contents	Notes
Content-type	image/jpeg	If the MIME type is not specified, image/jpeg is used as the default.

Request Body

Item	Type	Required	Explanation
-	JPEG file data	Y	Image to extract face

Response Status Code

Status Code	Condition	Explanation
200	Success
400	Input processing failure	If there is no Request Body or an error occurs while reading
500	Failure	Server encountered an error while processing

Response Header

Item	Value	Notes
Content-type	application/json	Response code and execution result are delivered together When execution fails, only response code is delivered (refer to API Response Example)

Response Body

The face detection result includes box information (x, y, width, height), 106 point landmark information, and face angle (yaw, pitch, roll) information.

Item	Type	Explanation
count	integer	Number of faces detected
faces	JSON Object	Face detection result (refer to Request and Response Examples)
return_msg	JSON Object	Result response code and message (refer to INF-03 in Response Code List)

Request and Response Examples

curl -X POST http://127.0.0.1:9297/faces --data-binary '@test.jpg'

{
    "count": 5,
    "faces": [
        {
            "box": {
                "x": 117.23624,
                "y": 247.9227,
                "width": 202.05891,
                "height": 202.05891
            },
            "landmark": {
                "lm_points": [
                    {
                        "x": 111.12232,
                        "y": 277.64584
                    },
                    ...
                ]
            },
            "pose": {
                "yaw": -3.6446712,
                "pitch": 14.918827,
                "roll": 0.8090107
            }
        },
        ...
    ],
    "return_msg": {
        "return_code": "INF-00",
        "return_msg": "OK."
    }
}

POST /alignedfaces

API Summary

By delivering an image containing multiple faces, the result of detecting faces in the image and each aligned face image are obtained simultaneously. You can specify the minimum and maximum size and maximum number of face detections respectively. If not specified otherwise, the default values specified below are applied to detect faces. The aligned face image is a 112 x 112 x 3 RGB image, which is base64 decoded and returned.

Request Query

Item	Explanation	Example
minsize	Minimum face detection size	/faces?minsize=48
maxsize	Maximum face detection size	/faces?maxsize=150
detectcount	Maximum number of face detections	/faces?detectcount=5

• If minsize is not specified, it defaults to 48.
• If maxsize is larger than the requested image, set the size of the image to maxsize.
• If detectcount is not specified, it defaults to 10.

Request Header

Item	Contents	Notes
Content-type	image/jpeg	If the MIME type is not specified, image/jpeg is used as the default.

Request Body

Item	Type	Required	Explanation
-	JPEG file data	Y	Image to perform face detection and feature point extraction

Response Status Code

Status Code	Condition	Explanation
200	Success
400	Input processing failure	If there is no Request Body or an error occurs while reading
500	Failure	Server encountered an error while processing

Response Header

Item	Value	Notes
Content-type	application/json	Response code and execution result are delivered together. When execution fails, only the response code is delivered (refer to API Response Example)

Response Body

Only box information (x, y, width, height) is provided for the face detection result, and the size information of the aligned face image and image data decoded to base64 are transmitted together.

Item	Type	Explanation
count	integer	Number of faces detected
aligned_faces	JSON Array	Face detection and each aligned image result (refer to Request and Response Example)
return_msg	JSON Object	Result response code and message (refer to INF-03 in Response Code List)

Request and Response Examples

curl -X POST http://127.0.0.1:9297/alignedfaces --data-binary '@test.jpg'

{
    "count": 5,
    "aligned_faces": [
        {
            "box": {
                "x": 117.23624,
                "y": 247.9227,
                "width": 202.05891,
                "height": 202.05891
            },
            "image_height": 112,
            "image_width": 112,
            "image_channel": 3,
            "image_data": "SVlgTVphS1dfTVxNr..."	# base64 Encoded face image data
        },
        ...
    ],
    "return_msg": {
        "return_code": "INF-00",
        "return_msg": "OK."
    }
}   

POST /similarity/v2

API Summary

By passing two aligned face images, the similarity between the two faces is obtained. Both images must be 112 x 112 x 3, identical to the /feature API.

Request Query

Request Header

Item	Contents	Notes
Content-type	multipart/form-data

Request Body

Item	Type	Required
image_a	JPEG file data	Y
image_b	JPEG file data	Y

Response Status Code

Status Code	Condition	Explanation
200	Success
400	Input processing failure	If there is no Request Body or an error occurs while reading
500	Failure	Server encountered an error while processing

Response Header

Item	Value	Notes
Content-type	application/json	Response code and execution result are delivered together. When execution fails, only the response code is delivered (refer to API Response Example)

Response Body

Similarity is given as a real value between 0 and 1, and the closer to 1, the more similar the faces.

Item	Type	Explanation
similarity	float	Similarity between two faces (refer to Request and Response Example)
return_msg	JSON Object	Result of response code and message (refer to Response Code List)

Request and Response Examples

curl -X POST http://127.0.0.1:9297/similarity --form 'image_a=@feature_test_a.jpg' --form 'image_b=@feature_test_b.jpg'

{
    "similarity": 0.6020877,
    "return_msg": {
        "return_code": "INF-00",
        "return_msg": "OK."
    }
} 

POST /liveness/multiframe

API Summary

• The authenticity of the face is verified by delivering four sequentially taken face images.
• You must have 4 images of the same person.
• You can only request a server with “Liveness Mode” set to MULTI.
• Please refer to GET/version API to check the “Liveness Mode”.

Request Query

Request Header

Item	Contents	Notes
Content-type	multipart/form-data

Request Body

Item	Type	Required	Explanation
images	zip file	Y	A zip file that compresses four images to measure Liveness

You must compress 4 requested images in zip format and transfer the compressed file. The name of the compressed file does not matter. The request images support the png/jpg format, and each name must be 1, 2, 3, and 4.
The number of image will be the processing order. Those images with a time order should be compressed by setting the file names in sequence.

Here are some examples of zip files that can be transmitted.

images1.zip (1.png, 2.png, 3.jpg, 4.jpg)
images2.zip (3.jpg, 4.jpg, 1.jpg, 2.png)

Here are some examples of zip files that cannot be transmitted. (The names are irrecognizable, The total number of images must be four.)

images3.zip (1.png, img2.jpg, test3.jpg, 4.jpg)
images4.zip (1.jpg, 2.jpg, 3.jpg)

Response Status Code

Status Code	Condition	Explanation
200	Success
400	Input processing failure	If there is no Request Body or an error occurs while reading
406	API usage limit	If you call a sever set to Single frame liveness API server has expired
500	Failure	Server encountered an error while processing

Response Header

Item	Value	Notes
Content-type	application/json	Response code and execution results are delivered together Only response code is delivered when execution fails. (refer to Request and Response Examples)
Alchera API Version
Alchera FaceSDK Version	<Alcher FaceSDK version on the current server>

Response Body

Confidence level is a real number between 0 and 1. It is more likely to be judged as a real face if the value is close to 1.

Item	Type	Explanation
confidence	Float	liveness (refer to Request and Response Examples)
return_msg	JSON Object	Result response code and message (refer to Response Code List)

Request and Response Examples

curl -X POST <http://127.0.0.1:9297/liveness/multiframe> --form 'images=@multiframe.zip'

{    "confidence": 0.74912024,    "return_msg": {        "return_code": "INF-00",        "return_msg": "OK."    }}