App-GetBizToken

App-GetBizToken

Version

1.0.0

Description

Configure the identity verification function of Face Comparing, support non-data-source comparison (compare portrait to be verified and reference portrait without sources). You can pass the liveness detection configuration to FaceID server for the initialization of the FaceID MegLiveStill SDK. The biz_token will be returned after verification is valid.

Note：

Only FaceID MegLiveStill SDK Version 3.0 or above can access biz_token for initialization.

Under FaceID MegLiveStill SDK Version 3.0, please refer to the document “Verify 2.0.6” under “Face Verification API”.

Request URL

Singapore:  POST https://api-sgp.megvii.com/faceid/v3/sdk/get_biz_token
Indonesia:  POST https://api-idn.megvii.com/faceid/v3/sdk/get_biz_token

Note:

Use HTTPS method in a production environment. Please avoid using HTTP methods as it is an unsecure link which remains security risks. If HTTP methods are used in a production environment, service reliability will not be guaranteed.

Permission

The FaceID Web APIs can only be called when accessing FaceID product first. Please contact our sales for the accessing process.

Parameters

Required／Optional

Parameter

Type Description
Required sign String

The signature when calling the API.

For specific signature generation method, please refer to "App-Authentication" documentation.

Required sign_version String

Signature algorithm version.

Please pass hmac_sha1.

Required liveness_type String

Choice of liveness detection process, see values below:

  • meglive: motion-based liveness detection
  • still: still liveness detection
  • flash: flash liveness detection
  • raw_image: no liveness detection, the image uploaded will be used in the following comparison
Required comparison_type String

Define the comparison type.

The value can only be 0, otherwise it will cause error 400(BAD_ARGUMENTS ).

“0” presents non-data-source comparison. The photo provided by the user will be taken as a reference portrait.

Required uuid String

Upload this field if not to use data sources for face comparing.

The field, which should not be longer than 128 bytes, marks the user corresponding to the detection with a unique ID.

It is recommended to use the same ID for the same user's requests, since it is very convenient to check the verification results and acquire a better experience in monitoring report.

Required image_ref1 File

Reference portrait provided by client.

If no face is detected in any of image_ref1, image_ref2, Error 400 (NO_FACE_FOUND) will be returned. If multiple faces are found in the two images, the biggest face will be chosen for comparison.

Optional image_ref2 File

Reference portrait provided by client.

If no face is detected in any of image_ref1, image_ref2, Error 400 (NO_FACE_FOUND) will be returned. If multiple faces are found in the two images, the biggest face will be chosen for comparison.

Optional biz_no String

Business serial number. The default value is empty.

It is recommended to be set related to your business and uniquely. It will be returned to your server when execute “return” value, which helps you confirm the attribution of the corresponding business. This field does not exceed 128 bytes.

Optional liveness_timeout String

The timeout after one enters the liveness detection process.

The verification will be failed if it is not completed within the set time.

Timeout setting: unit seconds, ∈ [5, 60]

  • meglive: set the timeout for each action, the default is 10.
  • still: set the timeout for the mirror, the default is 60.
Optional flash_liveness_timeout String

The timeout after one enters the flash liveness detection process.

The verification will be failed if it is not completed within the set time.

Timeout setting: unit seconds, ∈ [60, 180]

Optional maximum_brightness String

Indicates whether the screen brightness should be adjusted to the maximum when the live SDK is activated, with the following values:

  • 0: Default value, the feature is inactive.
  • 1: Automatically adjust the screen to maximum brightness.

This parameter is only effective for SDK version 3.3.3 and above

liveness_type = meglive

Optional

liveness_action_count String

The number of actions when configuring Motion-based liveness detection.

The default is 3 actions; the default is 3, ∈ [1,3]

liveness_type = still、flash

Optional

eyes_close_detection String

Wether execute eye close detection in still liveness detection.

The value is 1 or 0:

“0”: default value, no eye blinking detection

“1”: eye blinking detection mode. *The liveness detection will be failed if one keeps eyes-closed states.

liveness_type = raw_image

Required

image File

Portrait to be compared.

This method will detect all the faces in the image, and evaluate the quality of the biggest face.

You can set the optional parameters "fail_when_multiple_faces" and "face_quality_threshold" to define the detection standard.

Optional

fail_when_multiple_faces String

Whether returns error or continues comparing when multiple faces are detected.


The value is 1 or 0:
1: error 400 (MULTIPLE_FACES) returned
0: continues comparing with the biggest face detected

Optional

face_quality_threshold String

The quality threshold of the biggest face within the image. The default value is 30.

When the quality of a detected face is lower than the threshold, error 400 (LOW_QUALITY) will be returned.

Only an integer parameter between 0 to 100 is allowed, or error 400 (BAD_ARGUMENTS) will be returned.

Optional

return_faces String

Returns the detection result. The value can only be 1 or 0.

1: returns the detection result

0: only returns the comparison result

other values: error 400 (BAD_ARGUMENTS) occurs

Attention: When the set value is 1, even if error 400 (LOW_QUALITY), 400 (MULTIPLE_FACES), 400 (NO_FACE_FOUND) returned, the result still contains "faces" string.

Optional verbose String

The extent of detail of the returned data.

The values are below:
0: default value, only returns conclusion
1: returns conclusion and summary

Optional security_level String

The strictness of the comparison result.

Please select the security rule based on your scenario. The higher the stricture is, the higher the accuracy requires, and the lower the pass rate becomes.


  • 1: loose
  • 2: regular (default)
  • 3: strict
  • 4: very strict
Optional force_compare String

Whether comparison is still performed after a fake face is determined.

0: Default value, no comparison. When a fake face is determined, the result will be directly returned without performing comparison, which can save your costs.

1: Perform comparison. After a fake face is determined, comparison is still performed. It will not return fake face result, but the comparison result. The risk situation can be checked by verification (need to set verbose=1).

Attention: The record will be included in the billing logic when comparison is turned on.

Optional multi_oriented_detection String

Decide wether the image corresponding to the image_ref[x] parameter needs rotation (90 degrees, 180 degrees, 270 degrees) for a re-detection when no face detected.

The value can only be 1 or 0:

1: default value, rotation

0: no rotation

Other values: Error 400 (BAD_ARGUMENTS) occurs

Attention: Set this parameter to 1 may slightly increase the probability of misdetection. It is recommended not to set this parameter if you are clear that there does not exist non-axial face image or an extremely low-probability in your business.

Optional get_liveness_video String

This parameter is used to control whether to save the video and photos during the liveness detection phase. The available settings for the optional parameter are as follows:

  • 0: default value, do not save videos and photos.
  • 1: save videos and photos.
  • 2: save videos
  • 3: save photos

Note：the saved videos and photos are encrypted and stored on the SDK side. After calling the verify interface, the encryption key is returned to the customer's server side, and the key field is named "video_key".

Optional device_risk String

Enable Device Risk Detection:

  • 0: default value, do not detect.
  • 1:detect device risk

Note：This feature is effective with SDK configurations above version 3.5.7

Return Values

Field

Type

Description

request_id String

Unique ID of each request.

This string can be used for subsequent data check. This field must be returned.

time_used

Int

Time that the whole request takes.

Unit: millisecond. This field must be returned.

biz_token String

Information passed when the SDK is called.

Note: biz_token is unique and can only be used once. One biz_token is valid for 1 hour.

error

String

This string will not be returned unless request fails. For more details, please see the error message.

Sample Response

Sample response when request has succeeded:

{
   "biz_token":"1531397038,f0b9eea0-6a2d-486c-a1ba-42fdf843e8cc",
   "time_used":18,
   "request_id":"1531397037,c1223c5b-c2f6-4bb7-8cbb-8993497ddbe0"
}

Sample response when request has failed:

{
    "error": "BAD_ARGUMENTS: sign_version"
}

ERROR Message

Status Code

Error Message

Description

400 MISSING_ARGUMENTS: <key>

Some required arguments missed.

400 BAD_ARGUMENTS: <key>

Error while parsing some arguments. This error may be caused by illegal type or length of argument.

400 IMAGE_ERROR_UNSUPPORTED_FORMAT:<param>

The image which <param> indicates can not be resolved. The file format may not be supported or the file is damaged. <param> is one of image_ref1 and image_ref2. Please note that <param> has only one item, that is, the first one that satisfies the condition.

400 NO_FACE_FOUND:<param>

No face is detected in any of image_ref1, image_ref2. <param> is one of image_ref1 and image_ref2. Please note that <param> has only one item, that is, the first one that satisfies the condition.


400 INVALID_IMAGE_SIZE<param>

The size of uploaded image is too large, which is over the 4096x4096 pixel limit. <param> is one of image_ref1, image_ref2.Please note that <param> has only one item, that is, the first one that satisfies the condition.

400 LOW_QUALITY

The image quality is low.

400 MULTIPLE_FACES

The image contains multiple faces.

403

AUTHENTICATION_ERROR

Invalid signature.

403

AUTHORIZATION_ERROR: <reason>

api_key is discontinued, rate limit has been exceeded, no permission to call the API, or no permission to call the API according to current method.

Values of <reason> are below:

  • API_KEY_BE_DISCONTINUED：api_key is discontinued
  • IP_NOT_ALLOWED：IP is not allowed
  • LIMIT_REACHED：the limit of API calls for the api_key(only for test api_key) has been exceeded
  • MORE_RETRY_TIMES：comparison retry limit is reached
  • NO_VERIFY_PERMISSION：no permission for non-data-source comparison, but still calls
  • NO_DATA_SOURCE_PERMISSION：no permission for data-source comparison, but still calls

  • DENIED：no permission to call the API

  • EXPIRED_SIGN：sign is expired

  • INVALID_SIGN：invalid sign

  • Please prepare reservation schemes for other results

403 CONCURRENCY_LIMIT_EXCEEDED

The rate limit for this API Key has been exceeded.

404

API_NOT_FOUND

Requested API can not be found.

413 Request Entity Too Large

The request entity has exceeded the limit (5MB). This error message will be returned in plain text, instead of JSON.

500

INTERNAL_ERROR

Internal error. Please retry the request.

If this error keeps occurring, please contact our support team.

© 2012-2021 北京旷视科技有限公司 版权所有 | 京ICP备12036813号-6

京公网安备 11010802025957号