tencent cloud

APIs

DocumentaçãoAPIsFace RecognitionPersonnel Database Management APIsCreateFace

CreateFace

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

1. API Description

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

Add a group of human face images to a person. A person allows up to 5 images. If the person exists across multiple person libraries, the images will be added to the person in ALL libraries.

  • For the signature method in public parameters, please use the V3 version. 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: CreateFace.
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.
PersonId Yes String

Person ID, which is the PersonId in the person creation API.
Images.N No Array of String

base64 data of the image.

  • base64 encoded size must not exceed 5M.
  • For jpg format, the long side pixel must not exceed 4000. For other formats, the image long edge must not exceed 2000. The short side pixel of images in all formats must be not less than 64.
  • The total number of faces must not exceed 5.
  • If the 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.
Urls.N No Array of String

Image Url.

  • The size of the corresponding Image after base64 encoding must not exceed 5M.
  • For jpg format, the long side pixel must not exceed 4000. For other Image formats, the long side pixel must not 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.
  • Images stored in Tencent Cloud URLs can guarantee higher download speed and stability. It is recommended to store images in Tencent Cloud.
  • The speed and stability of non-Tencent Cloud Storage URLs may be affected to a certain extent.
  • PNG, jpg, JPEG, and BMP are supported. GIF images are not supported.
  • The total number of human faces must not exceed 5.
  • If the Image contains several faces, only the face with the maximum area is selected.
FaceMatchThreshold No Float

Only faces with a similarity to the person's existing faces exceeding the FaceMatchThreshold can be added successfully.

  • Default value: 60.
  • Value range: [0,100].
QualityControl No Integer

Image quality control.

  • Value range:
    0: no control;
    1: low quality requirement, where the image is super blurry, or at least one or more of the following exist: eye occlusion, nose occlusion, or mouth occlusion;
    2: normal quality requirement, where the image is bright, dark, blurry or generally blurry, or at least three of the following exist: eyebrow obstruction, cheek obstruction, or chin obstruction;
    3: high quality requirement, where the image is bright, dark, generally blurry, or one to two of the following exist: eyebrow obstruction, cheek obstruction, or chin obstruction;
    4: super high quality requirement, where each dimension is at its best 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 means not enabled, 1 means 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 or 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-body encryption is required for the request information. 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
SucFaceNum Integer

Number of faces that joined successfully.
SucFaceIds Array of String

List of face IDs that joined successfully.
RetCode Array of Integer

Addition result of each face image.

  • Other non-zero values represent algorithm service exceptions, with the following value ranges:
    -1101 represents no face detected.
    -1102 represents image decoding failure.
    -1109 represents image size too large or too small.
    -1601 represents the image quality control requirement is not met.
    -1604 represents face similarity does not exceed FaceMatchThreshold.
  • The order of RetCode is consistent with the sequence of Images or Urls in the input parameters.
SucIndexes Array of Integer

Index of successfully added faces.

  • The index order is consistent with the sequence of Images or Urls in the input parameter.
  • For example, if there are 3 Urls in Urls and the second url fails, the value of SucIndexes is [0,2].
SucFaceRects Array of FaceRect

Face bounding box position of successfully joined faces. The sequence is consistent with the sequence of Images or Urls in the input parameter.
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 Failure Example of Adding a Face

Input Example

https://iai.intl.tencentcloudapi.com/?Action=CreateFace
&PersonId=1001
&Urls.0=http://test.image.myqcloud.com/testB.jpg
&Urls.1=http://test.image.myqcloud.com/testC.jpg
&Urls.2=http://test.image.myqcloud.com/testD.jpg
&Urls.3=http://test.image.myqcloud.com/testE.jpg
&Urls.4=http://test.image.myqcloud.com/testF.jpg
&<Common request parameters>

Output Example

{
    "Response": {
        "Error": {
            "Code": "InvalidParameterValue.UploadFaceNumExceed",
            "Message": "Upload up to four human faces."
        },
        "RequestId": "44506f79-2191-49bc-997b-748a566d781c"
    }
}

Example2 Add Face Successful Example

Input Example

https://iai.intl.tencentcloudapi.com/?Action=CreateFace
&PersonId=1001
&Urls.0=http://test.image.myqcloud.com/testA.jpg
&<Common request parameters>

Output Example

{
    "Response": {
        "SucFaceNum": 1,
        "SucFaceIds": [
            "2875186538564559728"
        ],
        "RetCode": [
            0
        ],
        "SucIndexes": [
            0
        ],
        "SucFaceRects": [
            {
                "X": 135,
                "Y": 42,
                "Width": 98,
                "Height": 136
            }
        ],
        "FaceModelVersion": "3.0",
        "RequestId": "07d63403-a199-4bbe-b9e0-692356ac738d"
    }
}

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.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: CreatePersonPróximo: CreateGroup

Ajuda e Suporte

Esta página foi útil?

comentários

Search
    Enter keywords to search documentation