## 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 ```bash curl -X POST http://127.0.0.1:9297/faces --data-binary '@test.jpg' ``` ```json { "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 ```bash curl -X POST http://127.0.0.1:9297/alignedfaces --data-binary '@test.jpg' ``` ```json { "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 | First face image to measure similarity | | image_b | JPEG file data | Y | Second face image to measure similarity |
#### 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 ```bash curl -X POST http://127.0.0.1:9297/similarity --form 'image_a=@feature_test_a.jpg' --form 'image_b=@feature_test_b.jpg' ``` ```json { "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." }} ```