Introduction
Visual face is a credential that captures the user's face with a visual camera. It is different from face information captured with an infrared camera and is only available on devices that support visual face.
Currently, FaceStation F2, BioStation 3, BioEntry W3 supports visual face as user credential.
There are 3 different ways to add a visual face credential to a user.
1) Scan your face on a device.
2) Upload an image.
3) Register via email.
This article will guide you through adding a visual face credential by uploading an image via BioStar 2 API.
If you'd like to learn about how to add visual face by other methods via BioStar 2 API, please check out the following articles.
Adding visual face credential by scanning face on a device - [BioStar 2 API] Add Visual Face Credential by Scanning Face on a Device
Adding visual face credential by registering via email - BioStar 2 New Local API - Registering Visual Face(2) via send_email
Adding a visual face credential by uploading an image require 2 steps.
1) Detect face and retrieve template from image.
2) Add the extracted template to a user.
PREREQUISITE : You need to have a picture that has a user's face and meets the below requirements.
- Supported image file formats are JPG, JPEG, and PNG.
- Supported image file size: minimum 250 x 250, maximum 10MB.
- From BioStar 2.8.10, the minimum size limit is removed.
- You must convert the image file to BASE64 format. (You can easily find websites that convert images to BASE64)
- BASE64 format looks like this: “/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAMCAgMCAgMDA…”
Step 1. Detect Face and Retrieve Template from Image
This API is used to check whether the image that will be uploaded is according to specification or not and provide template.
Supported image file size is up to 10 MB.
PUT /api/users/check/upload_picture
Body Parameters:
| Parameters | Type | Required | Description |
|---|---|---|---|
| template_ex_picture | Base64 | Y | Image that will be checked and uploaded for visual face credential |
[Request Body]
{ "template_ex_picture": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAMCAgMCAgMDA…" } |
[Response Body]
* NOTE : The response body is going to be different based on the BioStar 2 version. *
v2.9.7 ~
{ "image" : "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQE...", <== A "image_template" : "AAACAAAAAAAAAAAB5dIlykmKEbYJpb5JvkoiNiGtqe...", <== B "image_template_2" : "AAADAAAAAAAAAB4gXh8dXOFaoRlepN6lHeJbnF2hpJXf4...", <== C "Response" : { "code": "0", "link": "https://support.supremainc.com/en/support/home", "message": "Success" } } |
v2.9.1 ~ v2.9.6
{ "image" : "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQE...", <== A "image_template" : "AAACAAAAAAAAAAAB5dIlykmKEbYJpb5JvkoiNiGtqe...", <== B "Response" : { "code": "0", "link": "https://support.supremainc.com/en/support/home", "message": "Success" } } |
~ v2.9.0
{ "image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQE...", <== A "Response": { "code": "0", "link": "https://support.supremainc.com/en/support/home", "message": "Success" } } |
Please take note of the values found in the response body of Step 1. These values will be used in Step 2 when adding visual face credential to user.
Step 2. Add the Extracted Template to a User
This API is used to update a user. There are a lot more body parameters you can add depending on what user information you want to edit. In this article, I will only display the parameters that are related to visual face credential.
PUT /api/users/<id>
Path Variable:
Input the id of the user you want to add the visual face in <id>.
Body Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| visualFaces | Array | Y | Main container of Visual Face Credential |
| :template_ex_normalized_image | Base64 | Y | Cropped image ready for visual face extraction |
| :templates | Array | Y | Container of the templates |
| ::credential_bin_type | Number | Y | UNKNOWN = -1 FACE_TEMPLATE = 0 FACE_TEMPLATE_IMAGE = 1 FACE_RAW_IMAGE = 2 FACE_TEMPLATE_EX_VER_2 = 5 (For FaceStation F2) FACE_TEMPLATE_EX_VER_3 = 9 (For BioStation 3 and W3) FACE_TEMPLATE_EX_NORMALIZED = 7 FACE_TEMPLATE_EX_PICTURE = 8 |
| ::template_ex | Raw | Y | Visual face template data |
| ::templateEx | Raw | Y | Visual face template data removed in v2.9.6 |
| ::template_ex_ir | Raw | Y | removed in v2.9.6 |
| ::templateExIr | Raw | Y | removed in v2.9.6 |
| ::template_ex_picture | Base64 | Y | Parameter for uploading picture raw data (ONLY required if you are uploading image) |
| :useProfile | Boolean | N | true to use image as profile |
Data for the parameters can be found from the response body in Step 1.
Please pay careful attention in the following request body information to learn how to construct the request body.
Specifically, pay close attention to the version, parameter names and data.
Find and match the color & letter ("A", "B", "C") of the data from Step 1's response body to Step 2's request body.
For example, for v2.9.7~, "image" value (indicated in red, "A") from Step 1's response body needs to be put in "template_ex_normalized_image" value (also indicated in red, "A") in Step 2's request body.
[Request Body]
* NOTE : The request body is going to be different based on the BioStar 2 version. *
v2.9.7 ~
{ "User": { "credentials": { "visualFaces": [ { "template_ex_normalized_image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQE...", <== A "templates" : [ { "credential_bin_type" : "5", "template_ex" : "AAACAAAAAAAAAAAB5dIlykmKEbYJpb5JvkoiNiGtqe...", <== B }, { "credential_bin_type" : "9", "template_ex" : "AAADAAAAAAAAAB4gXh8dXOFaoRlepN6lHeJbnF2hpJXf4...", <== C } ] } ] } } } |
v2.9.1 ~ v2.9.6
{ "User": { "credentials": { "visualFaces": [ { "template_ex_normalized_image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQE...", <== A "templates" : [ { "credential_bin_type" : "5", "template_ex" : "AAACAAAAAAAAAAAB5dIlykmKEbYJpb5JvkoiNiGtqe...", <== B } ] } ] } } } |
~ v2.9.0
{ "User": { "credentials": { "visualFaces": [ { "template_ex_picture": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQE...", <== A } ] } } } |
[Response Body]
{ "Response": { "code": "0", "link": "https://support.supremainc.com/en/support/home", "message": "Success" } } |