Active Liveness

Active liveness detection requires a user to intentionally confirm his or her presence by performing actions such as close eyes, making a certain hand gesture or face pose.

Active Liveness Object

Name
status
Type
string
Description
A short string indicating the status of the result.
1. success
2. failed

Name

result

Type

object

Description

The result of active liveness.

Name
gesture_status
Type
number
Description
Enum code indicating the gesture status.
1. MATCH
2. NOT_MATCH
3. face not detected
4. hand not detected
5. too many faces detected
6. too many hand detected

Name

detected_gesture

Type

string

Description

Enum code indicating the detection result.

// TODO: give meaningful enum code instead of using bitmask

Hand:

No	Gesture Code	Desc
1.	`HAND_00000`	Close all fingers
2.	`HAND_01000`	Show index finger
3.	`HAND_01100`	Show index and middle fingers
4.	`HAND_01110`	Show index, middle, and ring fingers
5.	`HAND_01111`	Show index, middle, ring, and pinky fingers
6.	`HAND_10000`	Raise only thumb
7.	`HAND_11000`	Show thumb and index fingers
8.	`HAND_11001`	Show thumb, index, and pinky fingers
9.	`HAND_11111`	Show all fingers

Head:

No	Gesture Code	Desc
1.	`HEAD_00`	Close both eyes
2.	`HEAD_01`	Close right eye
3.	`HEAD_10`	Close left eye
4.	`HEAD_11`	Open both eyes
5.	`HEAD_LEFT`	Turn left
6.	`HEAD_OPEN_MOUTH`	Open mouth
7.	`HEAD_RIGHT`	Turn right eye
8.	`HEAD_UP`	Look up
9.	`HEAD_CLOSE_MOUTH`	Close mouth
10.	`HEAD_DOWN`	Look down

Hand Gesture - UI Interface Example

Head Gesture - UI Interface Example

POST/face/v1/active-liveness

Active Liveness

Detect someone's active liveness.

Required parameter

Name
image
Type
file (.png, .jpg, .jpeg)
Description
The image file to be detected.
Name
gesture-code
Type
string
Description
What gesture to check.

Sample Request

POST

/face/v1/active-liveness


    1
2
3
4
5

    import { Vision } from '@glair/vision';

const vision = new Vision({ apiKey: 'api-key', username: 'username', password: 'password' });

await vision.faceBio.activeLiveness({ image: '/path/to/image/Face.jpg', gestureCode: 'HEAD_LEFT' });

Response


    1
2
3
4
5
6
7

    {
  "status": "success",
  "result": {
    "gesture_status": "MATCH",
    "detected_gesture": "HEAD_LEFT"
  }
}

Request ID

An associated request identifier is generated for every request made to this endpoint. This value can be found in the response headers under Request-Id

Responses

Various responses for this endpoint, in addition to general responses specified in Errors.

`200 - OK`

Success, gesture match

Response


    1
2
3
4
5
6
7

    {
  "status": "success",
  "result": {
    "gesture_status": "MATCH",
    "detected_gesture": "HEAD_LEFT"
  }
}

`200 - OK`

Success, gesture not match

Response


    1
2
3
4
5
6
7

    {
  "status": "success",
  "result": {
    "gesture_status": "NOT_MATCH",
    "detected_gesture": "HEAD_LEFT"
  }
}

`200 - OK`

Failed, no face detected.

Response


    1
2
3
4
5
6
7

    {
  "status": "failed",
  "result": {
    "gesture_status": "face not detected",
    "detected_gesture": ""
  }
}

`200 - OK`

Failed, no hand detected.

Response


    1
2
3
4
5
6
7

    {
  "status": "failed",
  "result": {
    "gesture_status": "hand not detected",
    "detected_gesture": ""
  }
}

`200 - OK`

Failed, too many faces.

Response


    1
2
3
4
5
6
7

    {
  "status": "failed",
  "result": {
    "gesture_status": "too many faces detected",
    "detected_gesture": ""
  }
}

`200 - OK`

Failed, too many hand.

Response


    1
2
3
4
5
6
7

    {
  "status": "failed",
  "result": {
    "gesture_status": "too many hand detected",
    "detected_gesture": ""
  }
}

`400 - Bad Request`

Invalid file format for captured_image.

// TODO: no captured image

Response


    1
2
3
4

    {
  "status": "failed",
  "error_message": "enter valid base64 for captured image",
}

`400 - Bad Request`

Invalid file format for stored_image.

// TODO: no captured image

Response


    1
2
3
4

    {
  "status": "failed",
  "error_message": "enter valid format image for captured image",
}

`500 - Internal Server Error`

GLAIR Vision API server error.

Response


    1
2
3
4

    {
  "status": "failed",
  "error_message": "internal server error"
}