ID Verification:FACE_IDU_MIN

Name

Type

Required

Description

Example

ProductCode

String

Yes

The product code. Set the value to FACE_IDU_MIN.

FACE_IDU_MIN

MerchantBizId

String

Yes

A custom business-unique identifier used for subsequent issue locating and troubleshooting. The value supports a combination of letters and digits with a length of 32 characters. Make sure that the value is unique.

e0c34a77f5ac40a5aa5e6ed20c35****

MerchantUserId

String

Yes

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

123456789

VerifyModel

String

Yes

The verification mode:

• 0: Search mode

  • Function: Pass in a face group and a user face image (SourceFacePicture/SourceFacePictureUrl/FacePictureFile). The system automatically searches the face group to determine whether the face image already exists. The user face image supports silent liveness detection.

  • Recommended scenario: Registering real-person accounts where duplicate registration is not allowed.

• 1: Verification mode (default)

  • Function: Pass in a specified face image (SourceFacePicture/SourceFacePictureUrl/FacePictureFile) and a reference face image (TargetFacePicture/TargetFacePictureUrl/TargetFacePictureFile). The system automatically verifies whether the face information of the two images matches. The specified face image supports silent liveness detection.

  • Recommended scenario: Scenarios where you need to verify the operator's identity when modifying login credentials, account information, etc.

• 2: Comprehensive mode

  • Function: Pass in a face group, a specified face image (SourceFacePicture/SourceFacePictureUrl/FacePictureFile), and a reference face image (TargetFacePicture/TargetFacePictureUrl/TargetFacePictureFile). The system automatically searches the face group for the specified face image, checks whether it matches the reference face image, and supports silent liveness detection for the specified face image.

  • Recommended scenario: Scenarios where you need to verify that the user is both new and the legitimate operator.

0

FaceGroupCodes

String

No

Obtain the corresponding code when you create a face group in the ID Verification console. You can query up to 10 face groups at the same time. Separate multiple face group codes with commas (,).

1232344,23444

SourceFacePicture

String

No

The Base64-encoded face image.

base64

SourceFacePictureUrl

String

No

The URL of the face image, which must be publicly accessible over HTTP or HTTPS.

https://***face1.jpeg

SourceFacePictureFile

String

No

The face image file stream.

Face image file stream 1

TargetFacePicture

String

No

The Base64-encoded reference (target) face image.

base64

TargetFacePictureUrl

String

No

The URL of the reference (target) face image, which must be publicly accessible over HTTP or HTTPS.

https://***face2.jpeg

TargetFacePictureFile

String

No

The reference (target) face image file stream.

Face image file stream 2

AutoRegistration

String

No

Specifies whether to automatically register the face to a specified face group when the face is not found during search.

• 0: Automatic registration

• 1: Do not register (default)

0

FaceRegisterGroupCode

String

No

The face group for registration.

0e0c34a77f

ReturnFaces

String

No

The number of faces to return when multiple faces exist above the matching threshold.

• Default value: 1

• Maximum value: 5

1

FaceQualityCheck

String

No

N

FaceAttributeCheck

String

No

N

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 code: For more information, see Server-side HTTP status codes.

Success

Message

String

This section provides detailed descriptions of the return codes.

success

Result.FacePassed

String

The final authentication result. Valid values:

• Y: Passed.

• N: Failed.

Y

Result.FaceComparisonScore

Double

Returned when VerifyModel is set to 1 or 2. The comparison score of 1:1 verification. Valid values: 0 to 100.

98

Result.DuplicateFace

String

Returned when a duplicate face is found during search. The face ID, user ID, and comparison score of the corresponding face in the face group are returned.

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

Result.FaceRegistrationResult

Integer

The face registration result.

• 0: Failed

• 1: Successful

1

Result.FaceRegistrationId

String

Returned when automatic registration is enabled and the face is successfully registered. The corresponding FACEID is returned.

9e792******a592a

Result.FaceAttack

String

Indicates whether the captured face involves a liveness attack. Y indicates an attack, and N indicates no attack. Returned when silent liveness detection is enabled.

N

Result.FaceAttributeInfo

String

{
        gender: 1
        glasses: 0
        hat: 1
        mask: 1
        tattoo: 0
        smoking: 0
        others: 1
        env：office
        expression：1
        age：16
}

Result.SubCode

String

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

200

Result.TransactionId

String

The unique identifier of the authentication request.

4ab0b***cbde97

Result.ExtFaceInfo

Object

The liveness detection result information. For the JSON format, see the example on the right. For more information, see the ExtFaceInfo section.

{
  "FaceQualityScore": 66.3,
  "OcclusionScore": 100,
  "SharpnessScore": 70.3,
  "KaOcclusionScore": 80,
  "IlluminationScore": 90.79
}

Name

Type

Description

Example

FaceQualityScore

Double

The liveness face quality score. Valid values: 0 to 100. A higher value indicates better quality.

88.62

OcclusionScore

Double

A quality assessment sub-dimension: the occlusion score. Valid values: 0 to 100. A higher value indicates better quality.

99.99

KaOcclusionScore

Double

A quality assessment sub-dimension: the key area occlusion score. Valid values: 0 to 100. A higher value indicates better quality.

100

IlluminationScore

Double

A quality assessment sub-dimension: the illumination score. Valid values: 0 to 100. A higher value indicates better quality.

97.43

SharpnessScore

Double

A quality assessment sub-dimension: the image sharpness score. Valid values: 0 to 100. A higher value indicates better quality.

60.78