tencent cloud

APIs

DocumentaçãoAPIsFace RecognitionFace Search APIsSearchFaces

SearchFaces

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-11-05 17:41:40

1. API Description

Domain name for API request: iai.intl.tencentcloudapi.com.

This API is used to recognize the top K most similar persons in one or more person libraries for a face image to be recognized, and sort the recognition results by similarity in descending order.

This API is used to recognize up to 10 human faces in an image at a time and search across 100 person libraries at a time.

The total number of human faces in a person library for a single search is related to the algorithm model version of the person library. For a person library with algorithm model version 2.0, the total number of human faces in a single search should not exceed 1 million. For a person library with algorithm model version 3.0, the total number of human faces in a single search should not exceed 3 million.

Unlike the Person search and Person search by database return APIs, this API verifies each Face under a Person as a separate individual. The Person search and Person search by database return APIs perform fusion feature processing on all faces under a Person. For example, if a Person has 4 faces, the Person search and Person search by database return APIs will fuse the features of the 4 faces to generate the characteristics of this Person, making the search more accurate.

This interface should be used in conjunction with the personnel database management API (https://www.tencentcloud.com/document/product/867/45015?from_cn_redirect=1).

Note: If a person library has not been called for over 1 year, the platform will delete its resources to ensure user information security.

  • Use the V3 signature method in public parameters. In other words, set the SignatureMethod parameter to TC3-HMAC-SHA256.

-Cannot search person libraries of different algorithm model versions (FaceModelVersion) at the same time.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: SearchFaces.
Version Yes String Common Params. The value used for this API: 2020-03-03.
Region Yes String Common Params. For more information, please see the list of regions supported by the product. This API only supports: ap-beijing, ap-chengdu, ap-chongqing, ap-guangzhou, ap-jakarta, ap-nanjing, ap-shanghai, ap-singapore.
GroupIds.N Yes Array of String

List of person libraries to search, with a maximum of 100.

  • The array element value is the GroupId in the person library creation API.
  • You cannot search person libraries with different algorithm model versions (FaceModelVersion) at the same time.
Image No String

base64 data of the image.

  • base64-encoded data must not exceed 5 MB.
  • For jpg images, the long side pixel cannot exceed 4000. For other formats, the long side pixel cannot exceed 2000.
  • The short side pixel of images in all formats must be at least 64.
  • PNG, jpg, JPEG, and BMP are supported. GIF images are not supported.
Url No String

The Url of the Image.

  • The size of the corresponding Image after base64 encoding must not exceed 5M.
  • The long side pixel of a jpg Image cannot exceed 4000, and that of other formats cannot exceed 2000.
  • The short side pixel of images in all formats must be not less than 64.
  • Either Url or Image must be provided. If both are provided, only Url is used.
  • An Image stored in Tencent Cloud via Url can guarantee higher download speed and stability. It is recommended to store images in Tencent Cloud.
  • The speed and stability of URLs not stored in Tencent Cloud may be affected to a certain extent.
  • PNG, jpg, JPEG, and BMP are supported, while GIF images are not supported.
MaxFaceNum No Integer

Maximum number of faces to be recognized.

  • Default value: 1 (only the face with the maximum area in the image is detected). Maximum value: 10.
  • MaxFaceNum is used to set the number of faces to search when the input image to be recognized contains several faces.
  • For example, if the image in the input Image or Url contains several faces and MaxFaceNum is set to 5, the 5 faces with the maximum area in the image will be recognized.
MinFaceSize No Integer

Minimum size of the face length and width, unit: pixel.

  • Default value: 34.
  • Face images smaller than 34 cannot be recognized.
  • It is recommended to set it to 80.
MaxPersonNum No Integer

Number of most similar persons returned for a single recognized human face.

  • Default value: 5. Maximum value: 100.
  • For example, if MaxFaceNum is 1 and MaxPersonNum is 8, the Top 8 similar personnel information is returned.
  • A larger value means a longer time to process.
  • It is recommended not to exceed 10.
NeedPersonInfo No Integer

Whether to return detailed personnel information.

  • Value range: 0 to disable, 1 to enable.
  • Default value: 0.
  • Other values other than 0 and 1 default to 0.
QualityControl No Integer

Image quality control.

  • Value range:
    0: No control.
    1: Low quality requirement. The image is super blurry, with at least one or more of the following: eye, nose, or mouth occlusion.
    2: General quality requirement. The image is bright, dark, blurry or generally blurry, with at least three of the following: eyebrow occlusion, cheek occlusion, or chin occlusion.
    3: High quality requirement. The image is bright, dark, generally blurry, with one or two of the following: eyebrow occlusion, cheek occlusion, or chin occlusion.
    4: Very high quality requirement. Each dimension is optimal or at most one dimension has a minor problem.
  • Default: 0.
  • If the image quality fails to satisfy the requirement, the returned result will prompt that the image quality detection does not meet the requirement.
FaceMatchThreshold No Float

In the output parameter Score, only results exceeding the FaceMatchThreshold value will be returned. The default is 0.
NeedRotateDetection No Integer

Whether to enable image rotation recognition support.

  • Value range: 0 for not enabled, 1 for enabled.
  • Default value: 0.
  • This parameter is used to correctly detect and recognize human faces in the input image when the faces are rotated and the image has no exif information. If image rotation recognition support is not enabled, the faces cannot be detected or recognized correctly.
  • If you confirm that the image contains exif information or that the human faces in the input image will not be rotated, do not enable this parameter. Once enabled, the overall duration may increase by several hundred milliseconds.
Encryption No Encryption

Whether to encrypt the entire request body. Supported encryption algorithms: AES-256-CBC. Users with encryption requirements can use this parameter.
EncryptedBody No String

Encrypted ciphertext. The data format before encryption is as follows: {"Url":"","Image":""}.

3. Output Parameters

Parameter Name Type Description
Results Array of Result

Recognition result.
FaceNum Integer

Number of faces in the searched group.
FaceModelVersion String

Algorithm model version used for face recognition.
RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Face Search Failure Example

Input Example

https://iai.intl.tencentcloudapi.com/?Action=SearchFaces
&Url=http://test.image.myqcloud.com/testA.jpg
&MaxFaceNum=11
&GroupIds.0=TencentShenZhenEmployee
&<Common request parameters>

Output Example

{
    "Response": {
        "Error": {
            "Code": "FailedOperation.SearchFacesExceed",
            "Message": "The count of retrieved human faces exceeds the limit."
        },
        "RequestId": "f04ba2f3-532c-4207-9caa-6e818ded7fb9"
    }
}

Input Example

https://iai.intl.tencentcloudapi.com/?Action=SearchFaces
&Url=http://test.image.myqcloud.com/testA.jpg
&MaxFaceNum=1
&MinFaceSize=40
&MaxPersonNum=5
&GroupIds.0=TencentShenZhenEmployee
&<Common request parameters>

Output Example

{
    "Response": {
        "Results": [
            {
                "RetCode": 0,
                "Candidates": [
                    {
                        "PersonId": "1001",
                        "FaceId": "2875093635484912302",
                        "PersonName": "Jerry",
                        "Gender": 0,
                        "Score": 100,
                        "PersonGroupInfos": [
                            {
                                "GroupId": "TencentShenZhenEmployee",
                                "PersonExDescriptions": [
                                    "description1",
                                    "description2"
                                ]
                            }
                        ]
                    }
                ],
                "FaceRect": {
                    "X": 370,
                    "Y": 46,
                    "Width": 75,
                    "Height": 75
                }
            }
        ],
        "FaceNum": 1,
        "FaceModelVersion": "3.0",
        "RequestId": "57b42b73-b978-45b9-8095-8f50e9642d35"
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
AuthFailure.InvalidAuthorization Authentication fail.
FailedOperation.AcrossVersionsError This operation does not support cross-algorithm model versions.
FailedOperation.ConflictOperation Operation conflict. Do not perform simultaneous operations on the same Person.
FailedOperation.DecryptSystemError Decryption failed.
FailedOperation.DuplicatedGroupDescription Custom description fields in the same person library cannot be repeated.
FailedOperation.FaceSizeTooSmall Face frame size is less than the MinFaceSize setting. The human face is filtered.
FailedOperation.GroupInDeletedState The current group is being deleted. Please wait.
FailedOperation.GroupPersonMapExist The group already contains the corresponding Personnel Id.
FailedOperation.GroupPersonMapNotExist The group does not include the corresponding personnel Id.
FailedOperation.ImageDecodeFailed Image decoding failed.
FailedOperation.ImageDownloadError Image download error.
FailedOperation.ImageFacedetectFailed Face detection failed.
FailedOperation.ImageResolutionExceed The image resolution is too high.
FailedOperation.ImageResolutionTooSmall The short edge resolution of the image is lower than 64 pixels.
FailedOperation.ImageSizeExceed The size of the image after base64 encoding cannot exceed 5 MB.
FailedOperation.RequestLimitExceeded Request frequency exceeds the limit.
FailedOperation.RequestTimeout The backend service timed out.
FailedOperation.SearchFacesExceed The number of human faces to retrieve exceeds the limit.
FailedOperation.ServerError Algorithm service exception. Retry.
InternalError Internal error.
InvalidParameter.InvalidParameter Invalid parameters.
InvalidParameterValue.AccountFaceNumExceed Number of faces of the account exceeds the limit.
InvalidParameterValue.DeleteFaceNumExceed Number of faces to delete exceeds the limit. Each person must contain at least one face.
InvalidParameterValue.FaceMatchThresholdIllegal Invalid FaceMatchThreshold parameter.
InvalidParameterValue.GroupExDescriptionsExceed The customized description field array of the person library exceeds the length limit. You can create up to 5.
InvalidParameterValue.GroupExDescriptionsNameIdentical The custom description field name in the person library cannot be repeated.
InvalidParameterValue.GroupExDescriptionsNameIllegal The person library custom description field name contains invalid characters. The person library custom description field name supports only Chinese, English, -, _, and digits.
InvalidParameterValue.GroupExDescriptionsNameTooLong The custom description field name of a person library exceeds the length limit.
InvalidParameterValue.GroupFaceNumExceed Number of faces in the person library exceeds the limit.
InvalidParameterValue.GroupIdAlreadyExist Personnel database ID already exists. Personnel database ID cannot be repeated.
InvalidParameterValue.GroupIdIllegal The personnel database ID contains invalid characters. It can only contain letters, digits, and -%@#&_.
InvalidParameterValue.GroupIdNotExist The personnel database ID does not exist.
InvalidParameterValue.GroupIdTooLong Personnel database ID exceeds the length limit.
InvalidParameterValue.GroupIdsExceed The passed-in person library list exceeds the limit.
InvalidParameterValue.GroupNameAlreadyExist Person library name already exists. Person library name cannot be repeated.
InvalidParameterValue.GroupNameIllegal The personnel database name contains invalid characters. It can only contain Chinese characters, English letters, hyphens (-), underscores (_), and digits.
InvalidParameterValue.GroupNameTooLong Personnel database name exceeds the length limit.
InvalidParameterValue.GroupNumExceed The number of face libraries exceeds the limit. To add more, contact us.
InvalidParameterValue.GroupNumPerPersonExceed The number of person libraries exceeds the limit. A single person can be added to up to 100 person libraries.
InvalidParameterValue.GroupTagIllegal Personnel database remarks contain invalid characters. Personnel database remarks support only Chinese, English, -, _, and digits.
InvalidParameterValue.GroupTagTooLong Personnel database remarks exceed the length limit.
InvalidParameterValue.ImageEmpty No image is input.
InvalidParameterValue.InvalidParameter Invalid encryption parameters.
InvalidParameterValue.LimitExceed Number of returned results exceeds the limit.
InvalidParameterValue.NoFaceInGroups The specified group contains no human face.
InvalidParameterValue.NoFaceInPhoto The image contains no human face.
InvalidParameterValue.OffsetExceed Starting number is too large. Please check the required length of the array.
InvalidParameterValue.PersonExDescriptionInfosExceed The customized description field array of a person exceeds the length limit. A maximum of 5 is allowed.
InvalidParameterValue.PersonExDescriptionsNameIdentical The custom description field name of a person cannot be repeated.
InvalidParameterValue.PersonExDescriptionsNameIllegal The custom description field name contains invalid characters. The custom description field name supports only Chinese, English, -, _, and digits.
InvalidParameterValue.PersonExDescriptionsNameTooLong The custom description field name of a person exceeds the length limit.
InvalidParameterValue.PersonExistInGroup The group already contains the corresponding personnel Id.
InvalidParameterValue.PersonFaceNumExceed The number of human faces for a single person exceeds the limit. A single person can include up to five faces.
InvalidParameterValue.PersonGenderIllegal Error in the gender of personnel settings. 0 represents empty, 1 represents man, and 2 represents woman.
InvalidParameterValue.PersonIdAlreadyExist Person ID already exists. Person ID cannot be repeated.
InvalidParameterValue.PersonIdIllegal Person ID contains invalid characters. Person ID supports only English letters, digits, -%@#&_.
InvalidParameterValue.PersonIdNotExist The personnel ID does not exist.
InvalidParameterValue.PersonIdTooLong Person ID exceeds the length limit.
InvalidParameterValue.PersonNameIllegal Person name contains invalid characters. Person name supports only Chinese and English, -, _, and digits.
InvalidParameterValue.PersonNameTooLong Person name exceeds the length limit.
InvalidParameterValue.QualityControlIllegal Invalid QualityControl parameter.
InvalidParameterValue.SearchPersonsExceed The number of search personnel exceeds the limit.
InvalidParameterValue.UploadFaceNumExceed Upload up to four human faces.
InvalidParameterValue.UrlIllegal The URL format is invalid.
LimitExceeded.ErrorFaceNumExceed Human face count exceeds the limit.
MissingParameter.ErrorParameterEmpty The required parameter is empty.
ResourceUnavailable.Delivering The resource is being delivered.
ResourceUnavailable.Freeze The account has been frozen.
ResourceUnavailable.InArrears The account is in arrears.
ResourceUnavailable.NotExist The billing status is unknown. Check whether the service has been activated in the console.
ResourceUnavailable.Recover The resource has been possessed.
ResourceUnavailable.StopUsing Services for the account has been stopped.
ResourceUnavailable.UnknownStatus The billing status is unknown.
ResourcesSoldOut.ChargeStatusException The billing status is abnormal.
UnsupportedOperation.UnknowMethod The method name is unknown.
Anterior: DeleteFacePróximo: SearchPersons

Ajuda e Suporte

Esta página foi útil?

comentários

Search
    Enter keywords to search documentation