ID Verification:FACE_IDU_MIN

Name

Type

Required

Description

Example

ProductCode

String

Yes

Product code: FACE_IDU_MIN.

FACE_IDU_MIN

SceneCode

String

No

The custom authentication scenario ID.

1234567890

MerchantBizId

String

Yes

A custom unique business ID used to track and troubleshoot issues. It can be a combination of letters and digits up to 32 characters long. Make sure the ID is unique.

e0c34a77f5ac40a5aa5e6ed20c35****

MerchantUserId

String

Yes

A custom user ID or another identifier for a specific user, such as a mobile phone number or email address. We strongly recommend that you desensitize the value of this field in advance, for example, by hashing the value.

123456789

VerifyModel

String

Yes

Verification type:

• 0: Search mode

  • Function: Pass a face database and a user's face image (SourceFacePicture/SourceFacePictureUrl). The system automatically searches the face database to check if the face image already exists. You can enable passive liveness detection for the user's face image.

  • Recommended scenario: A real person creates an account, and duplicate registrations are not allowed.

• 1: Verification mode (default)

  • Function: Pass a specified face image (SourceFacePicture/SourceFacePictureUrl) and a stored face image (TargetFacePicture/TargetFacePictureUrl). The system automatically verifies if the face information in both images is consistent. You can enable passive liveness detection for the specified face image.

  • Recommended scenario: Verify if an operation, such as changing logon credentials or account information, is performed by the account owner.

• 2: Comprehensive mode

  • Function: Pass a face database, a specified face image (SourceFacePicture/SourceFacePictureUrl), and a stored face image (TargetFacePicture/TargetFacePictureUrl). The system automatically searches the face database to check if the specified face image exists and if it is consistent with the stored face. You can enable passive liveness detection for the specified face image.

  • Recommended scenario: Verify that a user is a new user and that the operation is performed by that user.

0

Liveness

String

No

Specifies whether to enable passive liveness detection.

• 0: Disable

• 1: Enable

0

FaceGroupCodes

String

No

The codes of the face databases. You can obtain the codes when you create the face databases in the ID Verification console. You can query up to 10 face databases at a time. If you specify multiple face database codes, separate them with commas.

1232344,23444

SourceFacePicture

String

No

The Base64-encoded portrait image.

base64

SourceFacePictureUrl

String

No

The URL of the portrait image. The URL must be an HTTP or HTTPS link accessible over the public network.

https://***face1.jpeg

TargetFacePicture

String

No

The Base64-encoded portrait image.

base64

TargetFacePictureUrl

String

No

The URL of the portrait image. The URL must be an HTTP or HTTPS link accessible over the public network.

https://***face2.jpeg

AutoRegistration

String

No

Specifies whether to automatically register a face to the specified face database if the face is not found during the search.

• 0: Automatically register

• 1: Do not register (default)

0

FaceRegisterGroupCode

String

No

The face database for registration.

0e0c34a77f

SaveFacePicture

String

No

This is a reserved field and is not yet in use.

FaceVerifyThreshold

String

No

This is a reserved field and is not yet in use.

ReturnFaces

String

No

If multiple faces are found that meet the matching threshold, you can use this parameter to specify the number of faces to return.

• The default value is 1.

• The maximum value is 5.

1

Name

Type

Description

Example

HTTP Status Code

Integer

The HTTP status code.

200

HTTP Body

RequestId

String

The ID of the request.

130A2C10-B9EE-4D84-88E3-5384FF0****

Code

String

Return to Code

Success

Message

String

A detailed description of the response code.

success

Result.FacePassed

String

The final result of the authentication. Valid values:

• Yes: Pass

• N: The authentication fails.

Y

Result.FaceComparisonScore

String

The score of the 1:1 face comparison. This parameter is returned when `VerifyModel` is set to 1 or 2. The value ranges from 0 to 100.

98

Result.DuplicateFace

String

If a duplicate face is found, the face ID and user ID from the face database are returned.

[
  {
    "faceGroupCode": "sg7****uzt",
    "faceId": "f5a921*******9e792ec84c8f0ca592a",
    "merchantUserId":"face0001"
  }
]

Result.FaceRegistrationResult

String

The result of the face registration.

• 0: Failed

• 1: Success

1

Result.FaceRegistrationId

String

The face ID that is returned when automatic registration is enabled and the face is successfully registered.

9e792******a592a

Result.FaceAttack

String

Indicates whether the captured face is involved in a liveness attack. Y: Attack detected. N: No attack detected. This parameter is returned when passive liveness detection is enabled.

N

Result.FaceAttackScore

String

The probability that the face is involved in a passive liveness detection attack. The value ranges from 0 to 100. This parameter is returned when passive liveness detection is enabled.

99

Result.FaceAge

String

The predicted reference age of the face. This parameter may not be returned if the prediction fails.

30

Result.FaceGender

String

The predicted gender from the face image. This parameter may not be returned if the prediction fails.

• M: Male

• F: Female

M

Result.SubCode

String

The description of the authentication result. For more information, see SubCode.

200

Result.TransactionId

String

The unique ID of the authentication request.

4ab0b***cbde97