Most matching candidate recognized
Used by actions: SearchFaces, SearchFacesReturnsByGroup, SearchPersons, SearchPersonsReturnsByGroup.
| Name | Type | Description |
|---|---|---|
| PersonId | String | Person ID |
| FaceId | String | Face ID |
| Score | Float | Match score of candidate. In a face base library containing 10,000 faces, the 1%, 0.1%, and 0.01% FARs correspond to scores of 70, 80, and 90, respectively; In a face base library containing 100,000 faces, the 1%, 0.1%, and 0.01% FARs correspond to scores of 80, 90, and 100, respectively; In a face base library containing 300,000 faces, the 1% and 0.1% FARs correspond to scores of 85 and 95, respectively. Generally, the score of 80 is suitable for most scenarios. We recommend choosing an appropriate score based on the actual situation, preferably no more than 90. |
| PersonName | String | Person name Note: this field may return null, indicating that no valid values can be obtained. |
| Gender | Integer | Person gender Note: this field may return null, indicating that no valid values can be obtained. |
| PersonGroupInfos | Array of PersonGroupInfo | List of groups containing this person and their description fields Note: this field may return null, indicating that no valid values can be obtained. |
Face attributes, including gender, age, expression,
beauty, glass, mask, hair, and pose (pitch, roll, yaw). Valid information will be returned only if NeedFaceAttributes is set to 1. The face attribute information of up to 5 largest faces in the image will be returned, and FaceAttributesInfo of the 6th and rest faces is meaningless.
Used by actions: DetectFace.
| Name | Type | Description |
|---|---|---|
| Gender | Integer | Gender. The gender is female for the value range [0,49] and male for the value range [50,100]. The closer the value to 0 or 100, the higher the confidence. If NeedFaceAttributes is not 1 or more than 5 faces are detected, this parameter will still be returned but meaningless. |
| Age | Integer | Age. Value range: [0,100]. If NeedFaceAttributes is not 1 or more than 5 faces are detected, this parameter will still be returned but meaningless. |
| Expression | Integer | Expression. Value range: [0 (normal)–50 (smile)–100 (laugh)]. If NeedFaceAttributes is not 1 or more than 5 faces are detected, this parameter will still be returned but meaningless. |
| Glass | Boolean | Whether glasses are present. Valid values: true, false. If NeedFaceAttributes is not 1 or more than 5 faces are detected, this parameter will still be returned but meaningless. |
| Pitch | Integer | Vertical offset in degrees. Value range: [-30,30]. If NeedFaceAttributes is not 1 or more than 5 faces are detected, this parameter will still be returned but meaningless. We recommend selecting images in the [-10,10] range for adding faces. |
| Yaw | Integer | Horizontal offset in degrees. Value range: [-30,30]. If NeedFaceAttributes is not 1 or more than 5 faces are detected, this parameter will still be returned but meaningless. We recommend selecting images in the [-10,10] range for adding faces. |
| Roll | Integer | Horizontal rotation in degrees. Value range: [-180,180]. If NeedFaceAttributes is not 1 or more than 5 faces are detected, this parameter will still be returned but meaningless. We recommend selecting images in the [-20,20] range for adding faces. |
| Beauty | Integer | Beauty. Value range: [0,100]. If NeedFaceAttributes is not 1 or more than 5 faces are detected, this parameter will still be returned but meaningless. |
| Hat | Boolean | Whether hat is present. Valid values: true, false. If NeedFaceAttributes is not 1 or more than 5 faces are detected, this parameter will still be returned but meaningless.Note: this field may return null, indicating that no valid values can be obtained. |
| Mask | Boolean | Whether mask is present. Valid values: true, false. If NeedFaceAttributes is not 1 or more than 5 faces are detected, this parameter will still be returned but meaningless.Note: this field may return null, indicating that no valid values can be obtained. |
| Hair | FaceHairAttributesInfo | Hair information, including length, bang, and color. If NeedFaceAttributes is not 1 or more than 5 faces are detected, this parameter will still be returned but meaningless.Note: this field may return null, indicating that no valid values can be obtained. |
| EyeOpen | Boolean | Whether the eyes are open. Valid values: true, false. As long as there is more than one eye closed, false will be returned. If NeedFaceAttributes is not 1 or more than 5 faces are detected, this parameter will still be returned but meaningless.Note: this field may return null, indicating that no valid values can be obtained. |
Hair information in face attributes.
Used by actions: DetectFace.
| Name | Type | Description |
|---|---|---|
| Length | Integer | 0: shaved head, 1: short hair, 2: medium hair, 3: long hair, 4: braid Note: this field may return null, indicating that no valid values can be obtained. |
| Bang | Integer | 0: with bangs, 1: no bangs Note: this field may return null, indicating that no valid values can be obtained. |
| Color | Integer | 0: black, 1: golden, 2: brown, 3: gray Note: this field may return null, indicating that no valid values can be obtained. |
Face information list.
Used by actions: DetectFace.
| Name | Type | Description |
|---|---|---|
| X | Integer | Horizontal coordinate of the top-left vertex of the face frame. The face frame encompasses the facial features and is extended accordingly. If it is larger than the image, the coordinates will be negative. If you want to capture a complete face, you can set the negative coordinates to 0 if the completeness score meets the requirement. |
| Y | Integer | Vertical coordinate of the top-left vertex of the face frame. The face frame encompasses the facial features and is extended accordingly. If it is larger than the image, the coordinates will be negative. If you want to capture a complete face, you can set the negative coordinates to 0 if the completeness score meets the requirement. |
| Width | Integer | Face frame width. |
| Height | Integer | Face frame height. |
| FaceAttributesInfo | FaceAttributesInfo | Face attributes, including gender, age, expression, beauty, glass, mask, hair, and pose (pitch, roll, yaw). Valid information will be returned only if NeedFaceAttributes is set to 1. |
| FaceQualityInfo | FaceQualityInfo | Face quality information, including score, sharpness, brightness, and completeness. Valid information will be returned only if NeedFaceDetection is set to 1.Note: this field may return null, indicating that no valid values can be obtained. |
Completeness of facial features, which assesses the completeness of the eyebrows, eyes, nose, cheeks, mouth, and chin.
Used by actions: DetectFace.
| Name | Type | Description |
|---|---|---|
| Eyebrow | Integer | Eyebrow completeness. Value range: [0,100]. The higher the score, the higher the completeness. Reference range: [0,80], which means incomplete. Note: this field may return null, indicating that no valid values can be obtained. |
| Eye | Integer | Eye completeness. Value range: [0,100]. The higher the score, the higher the completeness. Reference range: [0,80], which means incomplete. Note: this field may return null, indicating that no valid values can be obtained. |
| Nose | Integer | Nose completeness. Value range: [0,100]. The higher the score, the higher the completeness. Reference range: [0,60], which means incomplete. Note: this field may return null, indicating that no valid values can be obtained. |
| Cheek | Integer | Cheek completeness. Value range: [0,100]. The higher the score, the higher the completeness. Reference range: [0,70], which means incomplete. Note: this field may return null, indicating that no valid values can be obtained. |
| Mouth | Integer | Mouth completeness. Value range: [0,100]. The higher the score, the higher the completeness. Reference range: [0,50], which means incomplete. Note: this field may return null, indicating that no valid values can be obtained. |
| Chin | Integer | Chin completeness. Value range: [0,100]. The higher the score, the higher the completeness. Reference range: [0,70], which means incomplete. Note: this field may return null, indicating that no valid values can be obtained. |
Face quality information, including score, sharpness, brightness, and completeness. Valid information will be returned only if NeedFaceDetection is set to 1.
Used by actions: DetectFace.
| Name | Type | Description |
|---|---|---|
| Score | Integer | Quality score. Value range: [0,100]. It comprehensively evaluates whether the image quality is suitable for face recognition; the higher the score, the higher the quality. In normal cases, you only need to use Score as the overall quality standard score. Specific item scores such as Sharpness, Brightness, Completeness are for reference only.Reference range: [0,40]: poor; [40,60]: fine; [60,80]: good; [80,100]: excellent. We recommend selecting images with a score above 70 for adding faces. Note: this field may return null, indicating that no valid values can be obtained. |
| Sharpness | Integer | Sharpness. Value range: [0,100]. It evaluates the sharpness of the image. The higher the score, the sharper the image. Reference range: [0,40]: very blurry; [40,60]: blurry; [60,80]: fine; [80,100]: sharp. We recommend selecting images with a score above 80 for adding faces. Note: this field may return null, indicating that no valid values can be obtained. |
| Brightness | Integer | Brightness. Value range: [0,100]. The brighter the image, the higher the score. Reference range: [0,30]: dark; [30,70]: normal; [70,100]: bright. We recommend selecting images in the [30,70] range for adding faces. Note: this field may return null, indicating that no valid values can be obtained. |
| Completeness | FaceQualityCompleteness | Completeness of facial features, which assesses the completeness of the eyebrows, eyes, nose, cheeks, mouth, and chin. Note: this field may return null, indicating that no valid values can be obtained. |
Position of detected face frame
Used by actions: CreateFace, CreatePerson, SearchFaces, SearchFacesReturnsByGroup, SearchPersons, SearchPersonsReturnsByGroup.
| Name | Type | Description |
|---|---|---|
| X | Integer | Horizontal coordinate of the top-left vertex of face frame. The face frame encompasses the facial features and is extended accordingly. If it is larger than the image, the coordinates will be negative. If you want to capture a complete face, you can set the negative coordinates to 0 if the completeness score meets the requirement. |
| Y | Integer | Vertical coordinate of the top-left vertex of face frame. The face frame encompasses the facial features and is extended accordingly. If it is larger than the image, the coordinates will be negative. If you want to capture a complete face, you can set the negative coordinates to 0 if the completeness score meets the requirement. |
| Width | Integer | Face width |
| Height | Integer | Face height |
Specific information of facial feature localization (facial keypoints).
Used by actions: AnalyzeFace.
| Name | Type | Description |
|---|---|---|
| FaceProfile | Array of Point | 21 points that describe the face contour. |
| LeftEye | Array of Point | 8 points that describe the left eye. |
| RightEye | Array of Point | 8 points that describe the right eye. |
| LeftEyeBrow | Array of Point | 8 points that describe the left eyebrow. |
| RightEyeBrow | Array of Point | 8 points that describe the right eyebrow. |
| Mouth | Array of Point | 22 points that describe the mouth. |
| Nose | Array of Point | 13 points that describe the nose. |
| LeftPupil | Array of Point | 1 point that describes the left pupil. |
| RightPupil | Array of Point | 1 point that describes the right pupil. |
Recognition result items by group
Used by actions: SearchFacesReturnsByGroup, SearchPersonsReturnsByGroup.
| Name | Type | Description |
|---|---|---|
| GroupId | String | Group ID. |
| Candidates | Array of Candidate | Most matching candidate recognized |
Custom description field of the group to be modified, which is a key-value pair.
Used by actions: ModifyGroup.
| Name | Type | Required | Description |
|---|---|---|---|
| GroupExDescriptionIndex | Integer | Yes | Custom group description field index, whose value starts from 0. Note: this field may return null, indicating that no valid values can be obtained. |
| GroupExDescription | String | Yes | Content of the custom group description field to be updated |
Returned group information
Used by actions: GetGroupList.
| Name | Type | Description |
|---|---|---|
| GroupName | String | Group name |
| GroupId | String | Group ID |
| GroupExDescriptions | Array of String | Custom group description field Note: this field may return null, indicating that no valid values can be obtained. |
| Tag | String | Group remarks Note: this field may return null, indicating that no valid values can be obtained. |
| FaceModelVersion | String | Algorithm model version used for face recognition. Note: this field may return null, indicating that no valid values can be obtained. |
| CreationTimestamp | Integer | Group creation time and date (CreationTimestamp), whose value is the number of milliseconds between the UNIX epoch time and the group creation time. The UNIX epoch time is 00:00:00, Thursday, January 1, 1970, Coordinated Universal Time (UTC). For more information, please see the UNIX time document. Note: this field may return null, indicating that no valid values can be obtained. |
Custom description field of the person to be modified, which is a key-value pair.
Used by actions: CreatePerson, ModifyPersonGroupInfo.
| Name | Type | Required | Description |
|---|---|---|---|
| PersonExDescriptionIndex | Integer | Yes | Person description field index, whose value starts from 0. Note: this field may return null, indicating that no valid values can be obtained. |
| PersonExDescription | String | Yes | Content of the person description field to be updated |
List of groups containing this person and their description fields
Used by actions: GetPersonGroupInfo, SearchFaces, SearchFacesReturnsByGroup, SearchPersons, SearchPersonsReturnsByGroup.
| Name | Type | Description |
|---|---|---|
| GroupId | String | ID of the group that contains this person |
| PersonExDescriptions | Array of String | Content of person description field |
Returned person information
Used by actions: GetPersonList.
| Name | Type | Description |
|---|---|---|
| PersonName | String | Person name |
| PersonId | String | Person ID |
| Gender | Integer | Person gender |
| PersonExDescriptions | Array of String | Content of person description field |
| FaceIds | Array of String | List of contained face images |
| CreationTimestamp | Integer | Person creation time and date (CreationTimestamp), whose value is the number of milliseconds between the UNIX epoch time and the group creation time. The UNIX epoch time is 00:00:00, Thursday, January 1, 1970, Coordinated Universal Time (UTC). For more information, please see the UNIX time document. |
Coordinates
Used by actions: AnalyzeFace.
| Name | Type | Description |
|---|---|---|
| X | Integer | X coordinate |
| Y | Integer | Y coordinate |
Face recognition result
Used by actions: SearchFaces, SearchPersons.
| Name | Type | Description |
|---|---|---|
| Candidates | Array of Candidate | Most matching candidate recognized |
| FaceRect | FaceRect | Position of detected face frame |
| RetCode | Integer | Status return code of detected face image. 0: normal. -1601: the image quality control requirement is not met; in this case, Candidate is empty. |
Recognition result.
Used by actions: SearchFacesReturnsByGroup, SearchPersonsReturnsByGroup.
| Name | Type | Description |
|---|---|---|
| FaceRect | FaceRect | Position of detected face frame |
| GroupCandidates | Array of GroupCandidate | Recognition result. |
| RetCode | Integer | Status return code of detected face image. 0: normal. -1601: the image quality control requirement is not met; in this case, Candidate is empty. |
Was this page helpful?