com.tencentcloudapi.iai.v20200303

Class IaiClient

java.lang.Object

com.tencentcloudapi.common.AbstractClient

com.tencentcloudapi.iai.v20200303.IaiClient

public class IaiClient
extends AbstractClient

Field Summary

Fields inherited from class com.tencentcloudapi.common.AbstractClient

gson, HTTP_RSP_OK, SDK_VERSION

Constructor Summary

Constructors

Constructor and Description
IaiClient(Credential credential, String region)
IaiClient(Credential credential, String region, ClientProfile profile)

Method Summary

Modifier and Type	Method and Description
AnalyzeFaceResponse	AnalyzeFace(AnalyzeFaceRequest req) This API is used to perform facial feature localization (aka facial keypoint localization) on a given image and calculate 90 facial keypoints that make up the contour of the face, including eyebrows (8 points on the left and 8 on the right), eyes (8 points on the left and 8 on the right), nose (13 points), mouth (22 points), face contour (21 points), and eyeballs or pupils (2 points).
CompareFaceResponse	CompareFace(CompareFaceRequest req) This API is used to calculate the similarity of faces in two images and return the face similarity score.
CopyPersonResponse	CopyPerson(CopyPersonRequest req) This API is used to copy a person in a group to another group (without copying the description).
CreateFaceResponse	CreateFace(CreateFaceRequest req) This API is used to add a set of face images to a person.
CreateGroupResponse	CreateGroup(CreateGroupRequest req) This API is used to create an empty group.
CreatePersonResponse	CreatePerson(CreatePersonRequest req) This API is used to create a person and add face, name, gender, and other related information.
DeleteFaceResponse	DeleteFace(DeleteFaceRequest req) This API is used to delete the face images of a person.
DeleteGroupResponse	DeleteGroup(DeleteGroupRequest req) This API is used to delete a group and all persons in it.
DeletePersonResponse	DeletePerson(DeletePersonRequest req) This API is used to delete a person from all groups.
DeletePersonFromGroupResponse	DeletePersonFromGroup(DeletePersonFromGroupRequest req) This API is used to remove a person from a specified group.
DetectFaceResponse	DetectFace(DetectFaceRequest req) This API is used to detect the position, attributes, and quality information of a face in the given image.
DetectLiveFaceResponse	DetectLiveFace(DetectLiveFaceRequest req) This API is used to detect the liveness of a user with a user-uploaded image.
GetGroupInfoResponse	GetGroupInfo(GetGroupInfoRequest req) This API is used to get the group information.
GetGroupListResponse	GetGroupList(GetGroupListRequest req) This API is used to get the list of groups.
GetPersonBaseInfoResponse	GetPersonBaseInfo(GetPersonBaseInfoRequest req) This API is used to get the information of a specified person, including name, gender, face, etc.
GetPersonGroupInfoResponse	GetPersonGroupInfo(GetPersonGroupInfoRequest req) This API is used to get the information of a specified person, including group, description, etc.
GetPersonListResponse	GetPersonList(GetPersonListRequest req) This API is used to get the list of persons in a specified group.
GetPersonListNumResponse	GetPersonListNum(GetPersonListNumRequest req) This API is used to get the number of persons in a specified group.
ModifyGroupResponse	ModifyGroup(ModifyGroupRequest req) This API is used to modify the name, tag, and custom description field of a group.
ModifyPersonBaseInfoResponse	ModifyPersonBaseInfo(ModifyPersonBaseInfoRequest req) This API is used to modify the information of a person, including name, gender, etc.
ModifyPersonGroupInfoResponse	ModifyPersonGroupInfo(ModifyPersonGroupInfoRequest req) This API is used to modify the description of a specified person in a group.
SearchFacesResponse	SearchFaces(SearchFacesRequest req) This API is used to recognize top K persons in one or more groups who are similar to the person in a given image and rank the similarity in a descending order.
SearchFacesReturnsByGroupResponse	SearchFacesReturnsByGroup(SearchFacesReturnsByGroupRequest req) This API is used to recognize top K persons in one or more groups who are similar to the person in a given image, display the results **by group**, and rank the similarity within each group in a descending order.
SearchPersonsResponse	SearchPersons(SearchPersonsRequest req) This API is used to recognize top K persons in one or more groups who are similar to the person in a given image and rank the similarity in a descending order.
SearchPersonsReturnsByGroupResponse	SearchPersonsReturnsByGroup(SearchPersonsReturnsByGroupRequest req) This API is used to recognize top K persons in one or more groups who are similar to the person in a given image, display the results **by group**, and rank the similarity within each group in a descending order.
VerifyFaceResponse	VerifyFace(VerifyFaceRequest req) This API is used to judge whether a person in an image corresponds to a given `PersonId`.
VerifyPersonResponse	VerifyPerson(VerifyPersonRequest req) This API is used to judge whether a person in an image corresponds to a given `PersonId`.

Methods inherited from class com.tencentcloudapi.common.AbstractClient

call, getClientProfile, getCredential, getRegion, internalRequest, setClientProfile, setCredential, setRegion

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IaiClient

public IaiClient(Credential credential,
                 String region)

IaiClient

public IaiClient(Credential credential,
                 String region,
                 ClientProfile profile)

Method Detail

AnalyzeFace

public AnalyzeFaceResponse AnalyzeFace(AnalyzeFaceRequest req)
                                throws TencentCloudSDKException

This API is used to perform facial feature localization (aka facial keypoint localization) on a given image and calculate 90 facial keypoints that make up the contour of the face, including eyebrows (8 points on the left and 8 on the right), eyes (8 points on the left and 8 on the right), nose (13 points), mouth (22 points), face contour (21 points), and eyeballs or pupils (2 points). > - Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the `SignatureMethod` parameter to `TC3-HMAC-SHA256`.

Parameters:

req - AnalyzeFaceRequest

Returns:

AnalyzeFaceResponse

Throws:

TencentCloudSDKException

CompareFace

public CompareFaceResponse CompareFace(CompareFaceRequest req)
                                throws TencentCloudSDKException

This API is used to calculate the similarity of faces in two images and return the face similarity score. If you need to judge "whether the person in the image is someone specified" in scenarios such as face login, i.e., checking whether the person in a given image is someone with a known identity, we recommend using the [VerifyFace](https://intl.cloud.tencent.com/document/product/867/44983?from_cn_redirect=1) or [VerifyPerson](https://intl.cloud.tencent.com/document/product/867/44982?from_cn_redirect=1) API. > - Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the `SignatureMethod` parameter to `TC3-HMAC-SHA256`.

Parameters:

req - CompareFaceRequest

Returns:

CompareFaceResponse

Throws:

TencentCloudSDKException

CopyPerson

public CopyPersonResponse CopyPerson(CopyPersonRequest req)
                              throws TencentCloudSDKException

This API is used to copy a person in a group to another group (without copying the description). One person can exist in up to 100 groups at the same time. > - Note: in the case that the version of the algorithm model was 2.0 when the person was created, the copy operation will fail if the target group is not of algorithm model 2.0.

Parameters:

req - CopyPersonRequest

Returns:

CopyPersonResponse

Throws:

TencentCloudSDKException

CreateFace

public CreateFaceResponse CreateFace(CreateFaceRequest req)
                              throws TencentCloudSDKException

This API is used to add a set of face images to a person. One person can have up to 5 images. If a person exists in multiple groups, the images will be added to all those groups for the person. > - Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the `SignatureMethod` parameter to `TC3-HMAC-SHA256`.

Parameters:

req - CreateFaceRequest

Returns:

CreateFaceResponse

Throws:

TencentCloudSDKException

CreateGroup

public CreateGroupResponse CreateGroup(CreateGroupRequest req)
                                throws TencentCloudSDKException

This API is used to create an empty group. If the group already exists, an error will be returned. Custom description fields can be created as needed to describe persons in the group. A maximum of 100,000 groups or 50 million faces can be created under one `APPID`. The maximum number of faces that can be included in one group varies by algorithm model version (`FaceModelVersion`), which is 1 million for v2.0 or 3 million for v3.0.

Parameters:

req - CreateGroupRequest

Returns:

CreateGroupResponse

Throws:

TencentCloudSDKException

CreatePerson

public CreatePersonResponse CreatePerson(CreatePersonRequest req)
                                  throws TencentCloudSDKException

This API is used to create a person and add face, name, gender, and other related information. > - Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the `SignatureMethod` parameter to `TC3-HMAC-SHA256`.

Parameters:

req - CreatePersonRequest

Returns:

CreatePersonResponse

Throws:

TencentCloudSDKException

DeleteFace

public DeleteFaceResponse DeleteFace(DeleteFaceRequest req)
                              throws TencentCloudSDKException

This API is used to delete the face images of a person. If the person has only one face image, an error will be returned.

Parameters:

req - DeleteFaceRequest

Returns:

DeleteFaceResponse

Throws:

TencentCloudSDKException

DeleteGroup

public DeleteGroupResponse DeleteGroup(DeleteGroupRequest req)
                                throws TencentCloudSDKException

This API is used to delete a group and all persons in it. Meanwhile, all face information corresponding to the persons will be deleted. If a person exists in multiple groups at the same time, deleting a group will not delete the person, but the custom description field information in the group will be deleted. Custom description field information in other groups will not be affected.

Parameters:

req - DeleteGroupRequest

Returns:

DeleteGroupResponse

Throws:

TencentCloudSDKException

DeletePerson

public DeletePersonResponse DeletePerson(DeletePersonRequest req)
                                  throws TencentCloudSDKException

This API is used to delete a person from all groups. Meanwhile, all face information of the person will be deleted.

Parameters:

req - DeletePersonRequest

Returns:

DeletePersonResponse

Throws:

TencentCloudSDKException

DeletePersonFromGroup

public DeletePersonFromGroupResponse DeletePersonFromGroup(DeletePersonFromGroupRequest req)
                                                    throws TencentCloudSDKException

This API is used to remove a person from a specified group. This operation only affects the group. If the person exists only in the group, the person will be deleted, and all face information of the person will also be deleted.

Parameters:

req - DeletePersonFromGroupRequest

Returns:

DeletePersonFromGroupResponse

Throws:

TencentCloudSDKException

DetectFace

public DetectFaceResponse DetectFace(DetectFaceRequest req)
                              throws TencentCloudSDKException

This API is used to detect the position, attributes, and quality information of a face in the given image. The position information includes (x, y, w, h); the face attributes include gender, age, expression, beauty, glass, hair, mask, and pose (pitch, roll, yaw); and the face quality information includes the overall quality score, sharpness, brightness, and completeness. The face quality information is mainly used to evaluate the quality of the input face image. When using the Face Recognition service, we recommend evaluating the quality of the input face image first to improve the effects of subsequent processing. Application scenarios of this feature include: 1. [Creating](https://intl.cloud.tencent.com/document/product/867/45014?from_cn_redirect=1)/[Adding](https://intl.cloud.tencent.com/document/product/867/45016?from_cn_redirect=1) a person in a group: this is to ensure the quality of the face information to facilitate subsequent processing. 2. [Face search](https://intl.cloud.tencent.com/document/product/867/44994?from_cn_redirect=1): this is to ensure the quality of the input image to quickly find the corresponding person. 3. [Face verification](https://intl.cloud.tencent.com/document/product/867/44983?from_cn_redirect=1): this is to ensure the quality of the face information to avoid cases where the verification incorrectly fails. 4. Face fusion: this is to ensure the quality of the uploaded face images to improve the fusion effect. > - Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the `SignatureMethod` parameter to `TC3-HMAC-SHA256`.

Parameters:

req - DetectFaceRequest

Returns:

DetectFaceResponse

Throws:

TencentCloudSDKException

DetectLiveFace

public DetectLiveFaceResponse DetectLiveFace(DetectLiveFaceRequest req)
                                      throws TencentCloudSDKException

This API is used to detect the liveness of a user with a user-uploaded image. Its difference from video-based liveness detection lies in that the user does not need to speak, shake their head, or wink for detection. Image-based liveness detection is suitable for scenarios where the image is a selfie or the requirement for attack defense is not high. If you have a higher security requirement for liveness detection, please use [FaceID](https://intl.cloud.tencent.com/product/faceid?from_cn_redirect=1). > - The aspect ratio of the image should be close to 3:4 (width:height); otherwise, the score returned for the image will be meaningless. This API is suitable for selfie scenarios, and the score returned in other scenarios will be meaningless. > - Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the `SignatureMethod` parameter to `TC3-HMAC-SHA256`.

Parameters:

req - DetectLiveFaceRequest

Returns:

DetectLiveFaceResponse

Throws:

TencentCloudSDKException

GetGroupInfo

public GetGroupInfoResponse GetGroupInfo(GetGroupInfoRequest req)
                                  throws TencentCloudSDKException

This API is used to get the group information.

Parameters:

req - GetGroupInfoRequest

Returns:

GetGroupInfoResponse

Throws:

TencentCloudSDKException

GetGroupList

public GetGroupListResponse GetGroupList(GetGroupListRequest req)
                                  throws TencentCloudSDKException

This API is used to get the list of groups.

Parameters:

req - GetGroupListRequest

Returns:

GetGroupListResponse

Throws:

TencentCloudSDKException

GetPersonBaseInfo

public GetPersonBaseInfoResponse GetPersonBaseInfo(GetPersonBaseInfoRequest req)
                                            throws TencentCloudSDKException

This API is used to get the information of a specified person, including name, gender, face, etc.

Parameters:

req - GetPersonBaseInfoRequest

Returns:

GetPersonBaseInfoResponse

Throws:

TencentCloudSDKException

GetPersonGroupInfo

public GetPersonGroupInfoResponse GetPersonGroupInfo(GetPersonGroupInfoRequest req)
                                              throws TencentCloudSDKException

This API is used to get the information of a specified person, including group, description, etc.

Parameters:

req - GetPersonGroupInfoRequest

Returns:

GetPersonGroupInfoResponse

Throws:

TencentCloudSDKException

GetPersonList

public GetPersonListResponse GetPersonList(GetPersonListRequest req)
                                    throws TencentCloudSDKException

This API is used to get the list of persons in a specified group.

Parameters:

req - GetPersonListRequest

Returns:

GetPersonListResponse

Throws:

TencentCloudSDKException

GetPersonListNum

public GetPersonListNumResponse GetPersonListNum(GetPersonListNumRequest req)
                                          throws TencentCloudSDKException

This API is used to get the number of persons in a specified group.

Parameters:

req - GetPersonListNumRequest

Returns:

GetPersonListNumResponse

Throws:

TencentCloudSDKException

ModifyGroup

public ModifyGroupResponse ModifyGroup(ModifyGroupRequest req)
                                throws TencentCloudSDKException

This API is used to modify the name, tag, and custom description field of a group.

Parameters:

req - ModifyGroupRequest

Returns:

ModifyGroupResponse

Throws:

TencentCloudSDKException

ModifyPersonBaseInfo

public ModifyPersonBaseInfoResponse ModifyPersonBaseInfo(ModifyPersonBaseInfoRequest req)
                                                  throws TencentCloudSDKException

This API is used to modify the information of a person, including name, gender, etc. The changes of person name and gender will be synced to all the groups that contain the person.

Parameters:

req - ModifyPersonBaseInfoRequest

Returns:

ModifyPersonBaseInfoResponse

Throws:

TencentCloudSDKException

ModifyPersonGroupInfo

public ModifyPersonGroupInfoResponse ModifyPersonGroupInfo(ModifyPersonGroupInfoRequest req)
                                                    throws TencentCloudSDKException

This API is used to modify the description of a specified person in a group.

Parameters:

req - ModifyPersonGroupInfoRequest

Returns:

ModifyPersonGroupInfoResponse

Throws:

TencentCloudSDKException

SearchFaces

public SearchFacesResponse SearchFaces(SearchFacesRequest req)
                                throws TencentCloudSDKException

This API is used to recognize top K persons in one or more groups who are similar to the person in a given image and rank the similarity in a descending order. Up to 10 faces in an image can be recognized at a time, and up to 100 groups can be searched in at a time. The maximum number of faces in groups that can be searched for at a time is subject to the group's algorithm model version (`FaceModelVersion`), which is 1 million for v2.0 or 3 million for v3.0. This API recognizes each face image of a person as an independent one. By contrast, the [SearchPersons](https://intl.cloud.tencent.com/document/product/867/44992?from_cn_redirect=1) and [SearchPersonsReturnsByGroup](https://intl.cloud.tencent.com/document/product/867/44991?from_cn_redirect=1) APIs fuse the features of all face images of a person; for example, if a person has 4 face images, they will fuse the features of the 4 face images and generate the summarized facial features of the person to make the search more accurate. This API should be used together with [Group Management APIs](https://intl.cloud.tencent.com/document/product/867/45015?from_cn_redirect=1). > - Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the `SignatureMethod` parameter to `TC3-HMAC-SHA256`.

Parameters:

req - SearchFacesRequest

Returns:

SearchFacesResponse

Throws:

TencentCloudSDKException

SearchFacesReturnsByGroup

public SearchFacesReturnsByGroupResponse SearchFacesReturnsByGroup(SearchFacesReturnsByGroupRequest req)
                                                            throws TencentCloudSDKException

This API is used to recognize top K persons in one or more groups who are similar to the person in a given image, display the results **by group**, and rank the similarity within each group in a descending order. Up to 10 faces in the image can be recognized at a time, and cross-group search is supported. The maximum number of faces in groups that can be searched for at a time is subject to the group's algorithm model version (`FaceModelVersion`), which is 1 million for v2.0 or 3 million for v3.0. This API recognizes each face image of a person as an independent one. By contrast, the [SearchPersons](https://intl.cloud.tencent.com/document/product/867/44992?from_cn_redirect=1) and [SearchPersonsReturnsByGroup](https://intl.cloud.tencent.com/document/product/867/44991?from_cn_redirect=1) APIs fuse the features of all face images of a person; for example, if a person has 4 face images, they will fuse the features of the 4 face images and generate the summarized facial features of the person to make the search more accurate. This API should be used together with [Group Management APIs](https://intl.cloud.tencent.com/document/product/867/45015?from_cn_redirect=1). > - Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the `SignatureMethod` parameter to `TC3-HMAC-SHA256`.

Parameters:

req - SearchFacesReturnsByGroupRequest

Returns:

SearchFacesReturnsByGroupResponse

Throws:

TencentCloudSDKException

SearchPersons

public SearchPersonsResponse SearchPersons(SearchPersonsRequest req)
                                    throws TencentCloudSDKException

This API is used to recognize top K persons in one or more groups who are similar to the person in a given image and rank the similarity in a descending order. Up to 10 faces in an image can be recognized at a time, and up to 100 groups can be searched in at a time. The maximum number of faces in groups that can be searched for at a time is subject to the group's algorithm model version (`FaceModelVersion`), which is 1 million for v2.0 or 3 million for v3.0. This API fuses the features of all face images of a person; for example, if a person has 4 face images, it will fuse the features of the 4 face images and generate the summarized facial features of the person to make the person search (i.e., judging whether the face image to be recognized is of a specified person) more accurate. By contrast, the [SearchFaces](https://intl.cloud.tencent.com/document/product/867/44994?from_cn_redirect=1) and [SearchFacesReturnsByGroup](https://intl.cloud.tencent.com/document/product/867/44993?from_cn_redirect=1) APIs recognize each face image of a person as an independent one for search. > - Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the `SignatureMethod` parameter to `TC3-HMAC-SHA256`. - This feature is available only to groups whose algorithm model version (`FaceModelVersion`) is 3.0.

Parameters:

req - SearchPersonsRequest

Returns:

SearchPersonsResponse

Throws:

TencentCloudSDKException

SearchPersonsReturnsByGroup

public SearchPersonsReturnsByGroupResponse SearchPersonsReturnsByGroup(SearchPersonsReturnsByGroupRequest req)
                                                                throws TencentCloudSDKException

This API is used to recognize top K persons in one or more groups who are similar to the person in a given image, display the results **by group**, and rank the similarity within each group in a descending order. Up to 10 faces in the image can be recognized at a time, and cross-group search is supported. The maximum number of faces in groups that can be searched for at a time is subject to the group's algorithm model version (`FaceModelVersion`), which is 1 million for v2.0 or 3 million for v3.0. This API fuses the features of all face images of a person; for example, if a person has 4 face images, it will fuse the features of the 4 face images and generate the summarized facial features of the person to make the person search (i.e., judging whether the face image to be recognized is of a specified person) more accurate. By contrast, the [SearchFaces](https://intl.cloud.tencent.com/document/product/867/44994?from_cn_redirect=1) and [SearchFacesReturnsByGroup](https://intl.cloud.tencent.com/document/product/867/44993?from_cn_redirect=1) APIs recognize each face image of a person as an independent one for search. > - Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the `SignatureMethod` parameter to `TC3-HMAC-SHA256`. - This feature is available only to groups whose algorithm model version (`FaceModelVersion`) is 3.0.

Parameters:

req - SearchPersonsReturnsByGroupRequest

Returns:

SearchPersonsReturnsByGroupResponse

Throws:

TencentCloudSDKException

VerifyFace

public VerifyFaceResponse VerifyFace(VerifyFaceRequest req)
                              throws TencentCloudSDKException

This API is used to judge whether a person in an image corresponds to a given `PersonId`. For more information on `PersonId`, please see [Group Management APIs](https://intl.cloud.tencent.com/document/product/867/45015?from_cn_redirect=1). The `VerifyFace` API judges whether a person is someone specified whose information is stored in a group, and the "someone" may have multiple face images. By contrast, the [CompareFace](https://intl.cloud.tencent.com/document/product/867/44987?from_cn_redirect=1) API judges the similarity between two faces. This API recognizes each face image of a person as an independent one. By contrast, the [VerifyPerson](https://intl.cloud.tencent.com/document/product/867/44982?from_cn_redirect=1) API fuses the features of all face images of a person; for example, if a person has 4 face images, it will fuse the features of the 4 face images and generate the summarized facial features of the person to make the person verification (i.e., judging whether the face image to be recognized is of a specified person) more accurate. > - Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the `SignatureMethod` parameter to `TC3-HMAC-SHA256`.

Parameters:

req - VerifyFaceRequest

Returns:

VerifyFaceResponse

Throws:

TencentCloudSDKException

VerifyPerson

public VerifyPersonResponse VerifyPerson(VerifyPersonRequest req)
                                  throws TencentCloudSDKException

This API is used to judge whether a person in an image corresponds to a given `PersonId`. For more information on `PersonId`, please see [Group Management APIs](https://intl.cloud.tencent.com/document/product/867/45015?from_cn_redirect=1). This API fuses the features of all face images of a person; for example, if a person has 4 face images, it will fuse the features of the 4 face images and generate the summarized facial features of the person to make the person verification (i.e., judging whether the face image to be recognized is of a specified person) more accurate. The face verification APIs judge whether a person is someone specified whose information is stored in a group, and the "someone" may have multiple face images. By contrast, the face comparison APIs judge the similarity between two faces. > - Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the `SignatureMethod` parameter to `TC3-HMAC-SHA256`. - This feature is available only to groups whose algorithm model version (`FaceModelVersion`) is 3.0.

Parameters:

req - VerifyPersonRequest

Returns:

VerifyPersonResponse

Throws:

TencentCloudSDKException