tencent cloud

APIs

DocumentaçãoAPIsFace RecognitionFace Search APIsSearchPersons

SearchPersons

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

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 them 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 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 faces in a single search should not exceed 1 million. For a person library with algorithm model version 3.0, the total number of faces in a single search should not exceed 3 million.

This API is used to perform fusion feature processing on all faces under a Person. For example, if a Person has 4 faces, this API will fuse the features of the 4 faces to generate the corresponding features of this Person, making Person search (confirming that the Face image to be identified belongs to a certain Person) more accurate. In contrast, Face search and Face search by group return API search for each Face under the Person as a separate individual.
Note: If a person library has no calls for more than 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.
    -Only person libraries with algorithm model version (FaceModelVersion) 3.0 are supported.
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: SearchPersons.
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 query, with a capacity limit of 100. The value of an array element is the GroupId in the person library creation API.
Image No String

Image base64 data.

  • Size after base64 encoding must not exceed 5M.
  • Long side pixel of jpg images cannot exceed 4000, and that of other formats cannot exceed 2000.
  • Short side pixel of images in all formats must not be less than 64.
  • If an image contains several faces, only the face with the maximum area is selected.
  • PNG, jpg, JPEG, and BMP are supported. GIF images are not supported.
Url No String

Image Url.

  • The size of the corresponding Image after base64 encoding must not exceed 5M.
  • For jpg format, 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 not less than 64.
  • Either Url or Image must be provided. If both are provided, only Url is used.
  • Urls of images stored in Tencent Cloud 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. GIF images are not supported.
MaxFaceNum No Integer

Maximum number of human 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 length and width of a human face, unit: pixel.

  • Default value: 34.
  • Less than 34 will affect search accuracy.
  • 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 information of the Top 8 similar persons is returned.
  • A larger value means a longer time to process. It is advisable not to exceed 10.
QualityControl No Integer

Image quality control.

  • Value range:
    0: No control.
    1: Low quality requirement. The image is super blurry, with at least one of the following: eye, nose, or mouth occlusion.
    2: Normal 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 equal to or greater than the FaceMatchThreshold value will be returned.

  • Default value: 0.
  • Value range: [0.0,100.0).
NeedPersonInfo No Integer

Whether to return specific personnel information.

  • Value range: 0 to disable, 1 to enable.
  • Default value: 0.
  • Other values other than 0 and 1 default to 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 when the human face in the image is rotated and the image has no exif information. If image rotation recognition support is not enabled, the human face in the image cannot be correctly detected and recognized.
  • If you confirm that the image contains exif information or that the human face 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 full request body encryption is required. Supported encryption algorithm: 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.
PersonNum Integer

Number of personnel included in the searched group. If all faces in the input image fail to meet the quality requirement, 0 is returned.
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 Person Search Failure Example

Input Example

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

Output Example

{
    "Response": {
        "Error": {
            "Code": "FailedOperation.ImageDownloadError",
            "Message": "Image download error."
        },
        "RequestId": "527ecffe-4c6a-47c9-8217-4dd2e3f018da"
    }
}

Example2 Person Search Successful Example

Input Example

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

Output Example

{
    "Response": {
        "Results": [
            {
                "RetCode": 0,
                "Candidates": [
                    {
                        "PersonId": "person1",
                        "FaceId": "",
                        "Score": 100,
                        "PersonName": null,
                        "Gender": null,
                        "PersonGroupInfos": null
                    },
                    {
                        "PersonId": "person2",
                        "FaceId": "",
                        "Score": 60,
                        "PersonName": null,
                        "Gender": null,
                        "PersonGroupInfos": null
                    },
                    {
                        "PersonId": "person3",
                        "FaceId": "",
                        "Score": 50,
                        "PersonName": null,
                        "Gender": null,
                        "PersonGroupInfos": null
                    }
                ],
                "FaceRect": {
                    "X": 139,
                    "Y": 59,
                    "Width": 124,
                    "Height": 162
                }
            },
            {
                "RetCode": 0,
                "Candidates": [
                    {
                        "PersonId": "person2",
                        "FaceId": "",
                        "Score": 100,
                        "PersonName": null,
                        "Gender": null,
                        "PersonGroupInfos": null
                    },
                    {
                        "PersonId": "person1",
                        "FaceId": "",
                        "Score": 60,
                        "PersonName": null,
                        "Gender": null,
                        "PersonGroupInfos": null
                    },
                    {
                        "PersonId": "person3",
                        "FaceId": "",
                        "Score": 20,
                        "PersonName": null,
                        "Gender": null,
                        "PersonGroupInfos": null
                    }
                ],
                "FaceRect": {
                    "X": 328,
                    "Y": 70,
                    "Width": 119,
                    "Height": 162
                }
            }
        ],
        "PersonNum": 5,
        "FaceModelVersion": "3.0",
        "RequestId": "c4608852-ff60-4a01-8dc3-367f6046baaf"
    }
}

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.DecryptSystemError Decryption failed.
FailedOperation.FaceSizeTooSmall Face frame size is less than the MinFaceSize setting. The human face is filtered.
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.FaceMatchThresholdIllegal Invalid FaceMatchThreshold parameter.
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.ImageEmpty No image is input.
InvalidParameterValue.ImageEmptyError No image is input.
InvalidParameterValue.InvalidParameter Invalid encryption parameters.
InvalidParameterValue.NoFaceInGroups The specified group contains no human face.
InvalidParameterValue.NoFaceInPhoto The image contains no human face.
InvalidParameterValue.QualityControlIllegal Invalid QualityControl parameter.
InvalidParameterValue.SearchPersonsExceed The number of search personnel exceeds the limit.
InvalidParameterValue.UnsupportedGroupFaceModelVersion This operation is not supported for algorithm model version 2.0 and lower versions.
InvalidParameterValue.UrlIllegal The URL format is invalid.
MissingParameter.ErrorParameterEmpty The required parameter is empty.
ResourceUnavailable.ChargeStatusException The account is in arrears.
ResourceUnavailable.Freeze The account has been frozen.
ResourceUnavailable.GetAuthInfoError Failed to obtain the authentication information.
ResourceUnavailable.InArrears The account is in arrears.
ResourceUnavailable.LowBalance Insufficient balance.
ResourceUnavailable.NotExist The billing status is unknown. Check whether the service has been activated in the console.
ResourceUnavailable.NotReady The service is not activated.
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: SearchFacesPróximo: SearchFacesReturnsByGroup

Ajuda e Suporte

Esta página foi útil?

comentários

Search
    Enter keywords to search documentation