tencent cloud

APIs

DocumentaçãoAPIsFace RecognitionPersonnel Database Management APIsCreatePerson

CreatePerson

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

1. API Description

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

Create a person and add a human face, name, sex, and other information related to the person.

  • Please use the V3 version of the signature method in public parameters. In other words, set the SignatureMethod parameter to TC3-HMAC-SHA256.
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: CreatePerson.
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.
GroupId Yes String

ID of the personnel database to be added, which is the GroupId in the API for creating a personnel database.
PersonName Yes String

Person name. [1, 60] characters, modifiable, repeatable.
PersonId Yes String

Person ID.

  • Cannot be modified or repeated under a single Tencent Cloud account.
  • Supports English letters, digits, -%@#&_, length limited to 64B.
Gender No Integer

Gender.

  • Value range: 0 represents empty, 1 represents man, 2 represents woman.
PersonExDescriptionInfos.N No Array of PersonExDescriptionInfo

Person description field content, key-value. [0, 60] characters, modifiable, repeatable.
Image No String

base64 image data.

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

Image Url.

  • The corresponding Image size 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 not be less than 64.
  • Either Url or Image must be provided. If both are provided, only Url is used.
  • Images stored in Tencent Cloud's 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. GIF images are not supported.
UniquePersonControl No Integer

This parameter is used to control whether the human face contained in the image specified by Image or Url is determined to be a suspected duplicate person already existing in the person library.

  • If determined to be the same person already in the person library, no new person will be created, and the personnel information of the suspected duplicate person will be returned.
  • If not, the person will be created.
  • Value range:
    0: No judgment is performed, and the person will be stored regardless of whether there is a suspected duplicate person in the library;
    1: Low duplicate person judgment requirement (1% false recognition rate);
    2: Normal duplicate person judgment requirement (0.1% false recognition rate);
    3: High duplicate person judgment requirement (0.01% false recognition rate);
    4: Very high duplicate person judgment requirement (0.001% false recognition rate).
  • Default value: 0.
  • Note: The higher the requirement, the lower the probability of suspected duplicate persons. The false recognition rates for different requirements are for reference only and can be adjusted according to the actual situation.
QualityControl No Integer

Image quality control.

  • Value range:
    0: no control;
    1: low quality requirement, where the image is very blurry, or at least one or more of the eyes, nose, or mouth are occluded;
    2: general quality requirement, where 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, where 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, where 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.
NeedRotateDetection No Integer

Whether to enable image rotation recognition support.

  • Value range: 0 for disabled, 1 for enabled.
  • Default value: 0.
  • This parameter is used to correctly detect and recognize human faces in an image when the faces are rotated and the image has no exif information. If image rotation recognition support is not enabled in this case, the faces cannot be detected or recognized.
  • 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 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
FaceId String

Unique ID of the face image.
FaceRect FaceRect

Position of the detected face frame.
SimilarPersonId String

PersonId of the suspected duplicate person.

  • This parameter is meaningful only when the UniquePersonControl parameter is not 0 and there is a suspected duplicate person in the person library.
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 Successful example of creating a person

Input Example

https://iai.intl.tencentcloudapi.com/?Action=CreatePerson
&GroupId=ZhuYuanDormitoryNo1
&PersonName=Junly
&PersonId=2001
&Gender=1
&Url=http://test.image.myqcloud.com/testB.jpg
&PersonExDescriptionInfos.0.PersonExDescriptionIndex=0
&PersonExDescriptionInfos.0.PersonExDescription=School of Computer Science
&PersonExDescriptionInfos.1.PersonExDescriptionIndex=1
&PersonExDescriptionInfos.1.PersonExDescription=software engineering
&PersonExDescriptionInfos.2.PersonExDescriptionIndex=2
&PersonExDescriptionInfos.2.PersonExDescription=Level 15
&PersonExDescriptionInfos.3.PersonExDescriptionIndex=3
&PersonExDescriptionInfos.3.PersonExDescription=3150808
&<Common request parameters>

Output Example

{
    "Response": {
        "FaceId": "3454816969590585885",
        "SimilarPersonId": "",
        "FaceRect": {
            "X": 172,
            "Y": 122,
            "Width": 178,
            "Height": 228
        },
        "FaceModelVersion": "3.0",
        "RequestId": "738a2fb0-bd4b-4cf6-9c91-18d50978d76b"
    }
}

Example2 Duplicate ID error example when creating a person

Input Example

https://iai.intl.tencentcloudapi.com/?Action=CreatePerson
&GroupId=ZhuYuanDormitoryNo1
&PersonName=Cheng
&PersonId=1001
&Gender=2
&Url=http://test.image.myqcloud.com/testD.jpg
&<Common request parameters>

Output Example

{
    "Response": {
        "Error": {
            "Code": "InvalidParameterValue.PersonIdAlreadyExist",
            "Message": "The person ID already exists. Person IDs cannot be repeated."
        },
        "RequestId": "76dedef7-af27-4a20-9064-c5ef3133926d"
    }
}

Example3 Error example for creating a person when the library ID does not exist

Input Example

https://iai.intl.tencentcloudapi.com/?Action=CreatePerson
&GroupId=ShenZhenCitizen
&PersonName=Siccy
&PersonId=3001
&Gender=2
&Url=http://test.image.myqcloud.com/testC.jpg
&<Common request parameters>

Output Example

{
    "Response": {
        "Error": {
            "Code": "InvalidParameterValue.GroupIdNotExist",
            "Message": "The personnel database ID does not exist."
        },
        "RequestId": "dfa512fc-fd07-4bf1-a292-cb497b620857"
    }
}

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.ConflictOperation Operation conflict. Do not perform simultaneous operations on the same Person.
FailedOperation.CreateFaceConcurrent Adding a face does not support concurrent operations.
FailedOperation.DecryptSystemError Decryption failed.
FailedOperation.DuplicatedGroupDescription Custom description fields in the same person library cannot be repeated.
FailedOperation.FaceQualityNotQualified Face image quality does not meet the requirements.
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.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.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.UniquePersonControlIllegal Invalid UniquePersonControl parameter.
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.
ResourceInsufficient Insufficient resources.
ResourceUnavailable.Delivering The resource is being delivered.
ResourceUnavailable.Freeze The account has been frozen.
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.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: DetectFaceSimilarityPróximo: CreateFace

Ajuda e Suporte

Esta página foi útil?

comentários

Search
    Enter keywords to search documentation