• Console

›Identity Verification Premium

FaceID service introduction

  • FaceID
  • FaceID-Pro

Identity Verification Basic

  • App-GetBizToken
  • App-Verify
  • App-Authentication
  • H5-Raw-UploadVideo
  • H5-Raw-Verify

Identity Verification Premium

  • APP_Pro-Access-Guide
  • APP_Pro-Authentication
  • APP_Pro-Encrption-Guide
  • APP_Pro-GetBiztoken
  • APP_Pro-Liveness
  • APP_Pro-Verify
  • H5-Lite_Pro-Access-Guide
  • H5-Lite_Pro-GetToken
  • H5-Lite_Pro-Redirect-To-Liveness-URL
  • H5-Lite_Pro-Callbacks
  • H5-Lite_Pro-GetResult
  • H5-Lite_Pro-UsinginAnApp
  • H5-Lite_Pro-UI-Customization
  • H5-Lite_Pro-RTC-Compatibility

OCR

  • Indonesian_ID_Card
H5-Lite_Pro-GetResult

Describe

This API returns liveness detection results. You can use biz_id as the index to search for the FaceID H5 verification results. The results are only stored for one day and can only be obtained through this API 3 times. If you call this API to obtain the results the 4th time or the results have expired, an error is returned. Make sure you obtain the data for each service before it expires.

Call URL

Indonesia region :https://api-idn.megvii.com/faceid/lite/get_result

Note : Please use HTTPS in production environments. HTTP communication is not secure, poses risks, and is not recommended for production environments. If you use HTTP in production environments, service reliability cannot be guaranteed.

Call method

Get

Permissions

Only when the user accesses the FaceID product can the FaceID Web APIs be called. Please consult FaceID business personnel for the process of accessing FaceID.

Parameter

Required/optionalparametertypeParameter Description
Requiredapi_keyStringThe api_key used to call this API.
Requiredapi_secretStringThe secret of the api_key used to call this API.
Requiredbiz_noStringThe serial number of the customer business. The value of this parameter must be unique. This number is returned to your server in notify and return to help you confirm business relationships. The length of the value cannot exceed 128 bytes.
Optionalreturn_verify_timeStringThis parameter specifies whether to return the verification time. Valid values include 0: Do not return the verification time; 1: Return the verification time.
Optionalreturn_imageStringThis parameter is optional and specifies whether to return the image data of the liveness detection.
Valid values:
0: Do not return image (default).
1: Return the best-quality image (image_best).

Return value description

ParameterTypeDescriptionExample
request_idStringThe serial number of the API call."1462259763,e2d2f8d6-204b-4c43-92ea-1d62b071f83c"
statusStringThe status of FaceID Lite. Valid values:
  • NOT_STARTED: The do method is not called after get_token. The verification is not started.
  • PROCESSING: The FaceID Lite verification is in progress.
  • WEBRTC_UNSUPPORTED: This indicates that the browser is not supported, which leads to a failed verification.
  •OK: The FaceID Lite verification is completed (OK indicates that the process is completed properly and does not indicate that the user passes the verification).
  •FAILED: The verification process is incomplete or an error has occurred.
    Note: In "flash" mode, if the user does not pass the "look in the mirror" step in 30 seconds, the status of the token changes to FAILED.
  •CANCELLED: The user has canceled the verification process.
  •TIMEOUT: The process has timed out.
(If the status is "NOT_STARTED" or "PROCESSING", the liveness_result and verify_result fields are not returned.)
"OK"
fail_reasonStringIf "get_fail_reason" is set to 1, the value of this field indicates the reason for the "WEBRTC_UNSUPPORTED" failure.
  •NETWORK_ERROR: Network connection issue.
  •PERMISSIONS_ERROR: The user has denied the camera permission or the browser (app) cannot use the camera.
  •SUPPORT_ERROR: The browser does not support WebRTC APIs or other compatibility issues.
"NETWORK_ERROR"
biz_infoJSONThis field contains biz_id, biz_no, and biz_extra_data.
  •biz_id: The business ID used to query comparison results.
  •biz_no: The serial number of the customer business, which is returned in notify and return.
  •biz_extra_data: The additional data returned when notify_url and return_url are invoked.
You can use this to pass additional information.
"biz_extra_data": "...","biz_id": "1462259748,52b13fb5-8dfb-4537-a62b-a641d5e929f1""biz_no":"cc47190f-5502-44a2-ab74-ea4f0f649f61"
time_usedIntThe time taken by the entire request in milliseconds. This field is always returned.100
liveness_resultJSONThe result of the liveness detection. If the user cancels the liveness detection process before it is completed, this field is not returned.
  •result: The result of the liveness detection. Valid values:
    PASS: The user passes the liveness check.
    FAIL: The user fails to pass the liveness check.
  •procedure_type: The method of the liveness detection. Valid values:
    flash:Flash-based liveness detection.
    distance:3D liveness detection.
    still: Passive liveness detection with a video selfie.
  •details: The detailed result of the liveness detection. Fields include:
    If procedure_type is "flash":
      FACE_NOT_FOUND: The number of times where no face is detected
      SIDE_FACE:The number of times where the user does not face the screen (tilting to the side).
      UPDOWN_FACE:The number of times where the user does not face the screen (tilting upward or downward)
      EYE_OCCLUSION: The number of times where the user's eyes are covered
      MOUTH_OCCLUSION: The number of times where the user's mouth is covered
      AWAY_FROM_CAMERA: The number of times where the user is too far away from the camera
      CLOSE_TO_CAMERA: The number of times where the user is too close to the camera
      FACE_OUT_OF_CAMERA: The number of times where the user's face is out of view
      HIGH_BRIGHTNESS: The number of times where the lighting is too bright
      LOW_BRIGHTNESS: The number of times where the lighting is too dark
      LOW_FACE_QUALITY:The number of times where the face quality of the video is too low
    If procedure_type is "distance":
      FACE_NOT_FOUND: The number of times where no face is detected
      SIDE_FACE:The number of times where the user does not face the screen (tilting to the side).
      UPDOWN_FACE:The number of times where the user does not face the screen (tilting upward or downward)
      EYE_OCCLUSION: The number of times where the user's eyes are covered
      MOUTH_OCCLUSION: The number of times where the user's mouth is covered
      AWAY_FROM_CAMERA: The number of times where the user is too far away from the camera
      CLOSE_TO_CAMERA: The number of times where the user is too close to the camera
      FACE_OUT_OF_CAMERA: The number of times where the user's face is out of view
      HIGH_BRIGHTNESS: The number of times where the lighting is too bright
      LOW_BRIGHTNESS: The number of times where the lighting is too dark
      LOW_FACE_QUALITY:The number of times where the face quality of the video is too low
    If procedure_type is "still":
      UPLOAD_TIMES: The number of video uploads
      FACE_NOT_FOUND: The number of times where no face is detected in the video
      LOW_FACE_QUALITY: The number of times where the face quality of the video is too low
       INVALID_VIDEO_DURATION: The number of times where the video duration is invalid
       SR_ERROR: The number of times where voice recognition results are incorrect (ignore this for passive liveness detection)
       NOT_SYNCHRONIZED: The number of times where lip reading results are incorrect (ignore this for passive liveness detection)
      NO_AUDIO: The number of times where the video has no sound
      VIDEO_FORMAT_UNSUPPORTED: The number of times where the video format is invalid
      VIDEO_FACE_INCONSISTENT: Face inconsistencies in the video
  •face_genuineness: This identifies spoof attacks with four sets of confidence scores and thresholds ranging from 0 to 1. If a confidence score is greater than its threshold, a spoof attack in that category is identified.
    synthetic_face_confidence: The confidence score for synthetic faces
    synthetic_face_threshold: The threshold for synthetic faces
    mask_confidence: The confidence score for masks
    mask_threshold: The threshold for masks
    screen_replay_confidence: The confidence score for screen replays
    screen_replay_threshold: The threshold for screen replays
{ "result": "PASS/FAIL", "procedure_type": "still", "details": { "UPLOAD_TIMES": 5, "FACE_NOT_FOUND": 0, "LOW_FACE_QUALITY": 0, "INVALID_VIDEO_DURATION": 1, "SR_ERROR": 2, "NOT_SYNCHRONIZED": 1, "VIDEO_FORMAT_UNSUPPORTED": 0, "NO_AUDIO": 0 }, "face_genuineness": { "synthetic_face_confidence": 0.88, "synthetic_face_threshold": 0.5, "mask_confidence": 0.32, "mask_threshold": 0.5, "screen_replay_confidence": 0, "screen_replay_threshold": 0.5 } }
verify_resultJSONThe result of the face comparison. If the user interrupts the process of liveness check midway or the comparison_type selected by the user is -1, this field will not be returned.
  •error_message: The error that occurs during face comparison. Valid values:
    null: No error has occurred.NO_FACE_FOUND: No face detected in the image. Fees are incurred even if this error has occurred.
    DATA_SOURCE_ERROR: An error has occurred while comparing data. Generally, this indicates a data error. If this error occurs, please stop the service and contact FaceID customer service or business support. Wait until this issue is addressed to start the service again.
    INTERNAL_ERROR: Internal server error. If this error occurs, send the request again. If this persists, contact FaceID customer service or business support.
  •result_ref[x]: The comparison result between the face collected in liveness detection and the uploaded image_ref[x].
    "confidence": The overall confidence score ranging from 0 to 100 in float. A larger number indicates a lower risk.
    "thresholds": A set of reference thresholds for the confidence score. The value of this field is an object and contains the following four float fields that range from 0 to 100.
      "1e-3": The confidence threshold for a risk level of one in a thousand.
      "1e-4": The confidence threshold for a risk level of one in ten thousand.
      "1e-5": The confidence threshold for a risk level of one in a hundred thousand.
      "1e-6": The confidence threshold for a risk level of one in a million.
  •verify_time: The timestamp of the verification in seconds. This field is returned only if return_verify_time=1.
{ "verify_time": 1462259763, "result_ref1": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } } }
imagesJSONThe image obtained in the liveness detection. The return_image parameter determines whether this field is returned. The value of this field can be an image in JPG format as a base64 string or null. An image is returned only if the status field is "OK".
  •image_best: The best-quality image in the liveness detection.
"image_best":"data:image/jpeg; base64,..."
multifaces_tagStringThis field is returned only if the return_multifaces_tag parameter is 1.
  •0: A single face.
  •1: Multiple faces.
0
multifaces_imageStringIf multifaces_tag is 1, this field is returned with an image that contains multiple faces. The image is a base64 string in JPG format.
If multifaces_tag is 0, this field is empty.
"data:image/jpeg;base64,..."

Return value example

Correct request return example

{
    "request_id": "1462259763,e2d2f8d6-204b-4c43-92ea-1d62b071f83c",
    "status": "OK",
    "biz_info": {
        "biz_extra_data": "...",
        "biz_id": "1462259748,52b13fb5-8dfb-4537-a62b-a641d5e929f1",
        "biz_no": "cc47190f-5502-44a2-ab74-ea4f0f649f61"
    },
    "liveness_result": {
        "procedure_type": "flash",
        "result": "PASS/FAIL/TIMEOUT",
        "details": {
            "UPLOAD_TIMES": 5,
            "FACE_NOT_FOUND": 0,
            "LOW_FACE_QUALITY": 0,
            "INVALID_VIDEO_DURATION": 1,
            "SR_ERROR": 2,
            "NOT_SYNCHRONIZED": 1,
            "VIDEO_FORMAT_UNSUPPORTED": 0,
            "NO_AUDIO": 0
        },
        "face_genuineness": {
            "synthetic_face_confidence": 0.88,
            "synthetic_face_threshold": 0.5,
            "mask_confidence": 0.32,
            "mask_threshold": 0.5,
            "screen_replay_confidence": 0,
            "screen_replay_threshold": 0.5
        }
    },
    "verify_result": {
        "result_ref1": {
            "confidence": 68.918,
            "thresholds": {
                "1e-3": 64,
                "1e-4": 69,
                "1e-5": 74,
                "1e-6": 79.9
            }
        }
    },
    "images": {
        "image_best": "data: image/jpeg;base64,..."
    },
    "time_used": 93
}

Failed request return example

{
    "error_message": "RESULT_NOT_FOUND",
    "request_id": "1462259901,fa79992d-ca61-48de-aa50-ea337c6aad42",
    "time_used": 4
}

Error code list

HTTP status codeerror messageillustrate
400RESULT_NOT_FOUNDThis error indicates that the business ID is incorrect.
400VIDEO_FACE_OCCLUDEThe face in the uploaded video is obstructed.

General ERROR_MESSAGE

HTTP status codeerror messageillustrate
403AUTHENTICATION_ERRORapi_key and api_secret do not match.
403AUTHORIZATION_ERROR:<reason>The api_key is disabled, call limit is reached, no permission to call this API, or no permission to call this API with the current method. Valid values for <reason> include "Denied." (no permission to call this API).
403CONCURRENCY_LIMIT_EXCEEDEDThe concurrency limit is exceeded.
400MISSING_ARGUMENTS:<key>A required parameter is missing.
400BAD_ARGUMENTS:<key>An error occurred while parsing a parameter (for example, a parameter is a number but a non-numeric string is used, or the value is too long).
404API_NOT_FOUNDThe API does not exist.
500INTERNAL_ERRORInternal server error. If this error occurs, send the request again. If this persists, contact FaceID customer service or business support.

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

京公网安备 11010802025957号