Face Recognition

Face Recognition
API Documentation
Product Documentation©2013-2022 Tencent Cloud. All rights reserved.

Page 1 of 321

Face Recognition

Copyright Notice©2013-2024 Tencent Cloud. All rights reserved.
Copyright in this document is exclusively owned by Tencent Cloud. You must not reproduce, modify, copy or distributein any way, in whole or in part, the contents of this document without Tencent Cloud's the prior written consent.
Trademark Notice

All trademarks associated with Tencent Cloud and its services are owned by Tencent Cloud Computing (Beijing)
Company Limited and its affiliated companies. Trademarks of third parties referred to in this document are owned bytheir respective proprietors.
Service Statement
This document is intended to provide users with general information about Tencent Cloud's products and services
only and does not form part of Tencent Cloud's terms and conditions. Tencent Cloud's products or services are
subject to change. Specific products and services and the standards applicable to them are exclusively provided for in
Tencent Cloud's applicable terms and conditions.

©2013-2022 Tencent Cloud. All rights reserved.

Page 2 of 321

Face Recognition

Contents
API Documentation
History
Introduction
API Category
Making API Requests
Request Structure
Common Params
Signature v3
Signature
Responses
Face Detection and Analysis APIs
DetectFace
DetectFaceAttributes
Facial Feature Localization APIs
AnalyzeFace
Face Comparison APIs
CompareFace
Group Management APIs
CreateGroup
DeleteGroup
GetGroupInfo
GetGroupList
ModifyGroup
CreatePerson
DeletePerson
DeletePersonFromGroup
GetPersonGroupInfo
GetPersonBaseInfo
GetPersonList
GetPersonListNum
ModifyPersonGroupInfo
ModifyPersonBaseInfo
CopyPerson
CreateFace
DeleteFace©2013-2022 Tencent Cloud. All rights reserved.

Page 3 of 321

Face Recognition

Face Search APIs
SearchFaces
SearchFacesReturnsByGroup
SearchPersons
SearchPersonsReturnsByGroup
Face Verification APIs
VerifyPerson
VerifyFace
Image-based Liveness Detection (High Precision) APIs
DetectLiveFaceAccurate
Data Types
Error Codes©2013-2022 Tencent Cloud. All rights reserved.

Page 4 of 321

Face Recognition

API Documentation
History：

Last updated 2023-02-02 14:52:43

Release 5
Release time: 2023-02-02 14:50:01
Release updates:
Improvement to existing documentation.
New APIs:
DetectLiveFaceAccurate
Deleted APIs:
ModifyPersonBaseInfo

Release 4
Release time: 2022-01-28 15:39:50
Release updates:
Improvement to existing documentation.
New APIs:
DetectFaceAttributes
New data structures:
AttributeItem
Eye
Eyebrow
FaceDetailAttributesInfo
FaceDetailInfo
Hair
Hat

©2013-2022 Tencent Cloud. All rights reserved.

Page 5 of 321

Face Recognition

HeadPose
Mouth

Release 3
Release time: 2021-01-18 14:21:05
Release updates:
Improvement to existing documentation.
Deleted APIs:
AnalyzeDenseLandmarks
DetectFaceAttributes
DetectLiveFaceAccurate
Modified APIs:
VerifyPerson**Modified input parameters:**PersonId
Deleted data structures:
AttributeItem
DenseFaceShapeEye
Eyebrow
FaceDetailAttributesInfo
FaceDetailInfo
Hair
Hat
HeadPose
Mouth

Release 2
Release time: 2020-10-16 18:26:37
Release updates:©2013-2022 Tencent Cloud. All rights reserved.

Page 6 of 321

Face Recognition

Improvement to existing documentation.
New APIs:
DetectLiveFaceAccurate

Existing Release
Release time: 2020-09-03 20:45:30
Existing APIs/data structures are as follows:
Improvement to existing documentation.
Existing APIs:
AnalyzeDenseLandmarks
AnalyzeFace
CompareFace
CopyPerson
CreateFace
CreateGroup
CreatePerson
DeleteFace
DeleteGroup
DeletePerson
DeletePersonFromGroup
DetectFace
DetectFaceAttributes
DetectLiveFace
GetGroupInfo
GetGroupList
GetPersonBaseInfo
GetPersonGroupInfo
GetPersonList
GetPersonListNum
ModifyGroup
ModifyPersonBaseInfo
ModifyPersonGroupInfo
SearchFaces
SearchFacesReturnsByGroup©2013-2022 Tencent Cloud. All rights reserved.

Page 7 of 321

Face Recognition

SearchPersons
SearchPersonsReturnsByGroup
VerifyFace
VerifyPerson
Existing data structures:
AttributeItem
CandidateDenseFaceShapeEye
Eyebrow
FaceAttributesInfo
FaceDetailAttributesInfo
FaceDetailInfo
FaceHairAttributesInfo
FaceInfo
FaceQualityCompleteness
FaceQualityInfo
FaceRect
FaceShapeGroupCandidate
GroupExDescriptionInfo
GroupInfo
Hair
Hat
HeadPose
Mouth
PersonExDescriptionInfo
PersonGroupInfo
PersonInfo
Point
ResultResultsReturnsByGroup©2013-2022 Tencent Cloud. All rights reserved.

Page 8 of 321

Face Recognition

Introduction：

Last updated 2023-02-02 14:52:43

Accurate recognition
Face Recognition has industry-leading accuracy and is record-breaking in international competitions. It achieved
99.80% accuracy in LFW 2017 and ranked 1st in terms of first-attempt recognition rate (83.29%) in the MegaFace
million-scale dataset.

High stability
Face Recognition was tested by Tencent products' massive user base and complex use cases and is proven to behighly reliable and robust with a 99.9% availability rate.

Leading algorithms
Based on the 3rd generation Tencent YouTu Grandmother Model, Face Recognition was optimized by various
training methods such as metric learning, transfer learning, and multi-task learning. Its customized fine-tuning or
distilling models can meet performance and latency requirements in different use cases.

Ease of use
Face Recognition offers multiple APIs and offline SDKs which enable fast applications and devices integration andsatisfy cloud and device demands.

Diverse use cases
Face Recognition is used in a wide variety of use cases such as face recognition access control and attendance,
event sign-in, face recognition payment, and face recognition login.

Real-time response
Face Recognition features high concurrence, high throughput, and low latency. It can search and process millions offaces in hundreds of milliseconds, meeting your needs in real time.

©2013-2022 Tencent Cloud. All rights reserved.

Page 9 of 321

Face Recognition

API Category：

Last updated 2023-02-02 14:52:43

Face Detection and Analysis APIs
API Name

FeatureDetectFace

Detects and analyzes face

DetectFaceAttributes

Detects face and analyzes attributes

Facial Feature Localization APIs
API Name

FeatureAnalyzeFace

Performs facial feature localization

Face Comparison APIs
API Name

FeatureCompareFace

Compares faces

Group Management APIs
API Name

FeatureCreateGroup

Creates group

DeleteGroup

Deletes group

GetGroupInfo

Gets group information

GetGroupList

Gets group list

ModifyGroup

Modifies group©2013-2022 Tencent Cloud. All rights reserved.

Page 10 of 321

Face Recognition

CreatePerson

Creates person

DeletePerson

Deletes person

DeletePersonFromGroup

Deletes person from group

GetPersonGroupInfo

Gets the group information of person

GetPersonBaseInfo

Gets the basic information of person

GetPersonList

Gets person list

GetPersonListNum

Gets person list length

ModifyPersonGroupInfo

Modifies person description

CopyPerson

Copies person

CreateFace

Adds face

DeleteFace

Deletes face

Face Search APIs
API Name

FeatureSearchFaces

Searches for face

SearchFacesReturnsByGroup

Searches for face with results returned by group

SearchPersons

Searches for person

SearchPersonsReturnsByGroup

Searches for person with results returned by group

Face Verification APIs
API Name

FeatureVerifyFace

Verifies face

VerifyPerson

Verifies person©2013-2022 Tencent Cloud. All rights reserved.

Page 11 of 321

Face Recognition

Image-Based Liveness Detection (High Precision) APIs
API Name

FeatureDetectLiveFaceAccurate

Detects the liveness of faces in images (high precision)

Image-based Liveness Detection APIs
API Name

FeatureDetectLiveFace

Detects liveness based on image©2013-2022 Tencent Cloud. All rights reserved.

Page 12 of 321

Face Recognition

Making API Requests
Request Structure：

Last updated 2023-02-27 15:22:45

1. Service Address
The API supports access from either a nearby region (at iai.tencentcloudapi.com) or a specified region (at iai.apguangzhou.tencentcloudapi.com for Guangzhou, for example).
We recommend using the domain name to access the nearest server. When you call an API, the request is
automatically resolved to a server in the region nearest to the location where the API is initiated. For example, when
you initiate an API request in Guangzhou, this domain name is automatically resolved to a Guangzhou server, theresult is the same as that of specifying the region in the domain like "iai.ap-guangzhou.tencentcloudapi.com".
Note: For latency-sensitive businesses, we recommend that you specify the region in the domain name.
Tencent Cloud currently supports the following regions:
Hosted region

Domain nameLocal access region (recommended, only for non-financial availability
zones)

iai.tencentcloudapi.com

South China (Guangzhou)

iai.apguangzhou.tencentcloudapi.com

East China (Shanghai)

iai.ap-shanghai.tencentcloudapi.com

North China (Beijing)iai.ap-beijing.tencentcloudapi.com

Southwest China (Chengdu)

iai.ap-chengdu.tencentcloudapi.com

Southwest China (Chongqing)

iai.apchongqing.tencentcloudapi.com

Hong Kong, Macao, Taiwan (Hong Kong, China)

iai.aphongkong.tencentcloudapi.com

Southeast Asia (Singapore)iai.apsingapore.tencentcloudapi.com

Southeast Asia (Bangkok)

iai.ap-bangkok.tencentcloudapi.com©2013-2022 Tencent Cloud. All rights reserved.

Page 13 of 321

Face Recognition

South Asia (Mumbai)

iai.ap-mumbai.tencentcloudapi.com

Northeast Asia (Seoul)

iai.ap-seoul.tencentcloudapi.com

Northeast Asia (Tokyo)

iai.ap-tokyo.tencentcloudapi.com

U.S. East Coast (Virginia)

iai.na-ashburn.tencentcloudapi.com

U.S. West Coast (Silicon Valley)iai.nasiliconvalley.tencentcloudapi.com

North America (Toronto)

iai.na-toronto.tencentcloudapi.com

Europe (Frankfurt)

iai.eu-frankfurt.tencentcloudapi.com

2. Communications Protocol
All the Tencent Cloud APIs communicate via HTTPS, providing highly secure communication tunnels.

3. Request Methods
Supported HTTP request methods:
POST (recommended)GETThe Content-Type types supported by POST requests:
application/json (recommended). The TC3-HMAC-SHA256 signature algorithm must be used.
application/x-www-form-urlencoded. The HmacSHA1 or HmacSHA256 signature algorithm must be used.
multipart/form-data (only supported by certain APIs). You must use TC3-HMAC-SHA256 to calculate the signature.
The size of a GET request packet is up to 32 KB. The size of a POST request is up to 1 MB when the HmacSHA1 or
HmacSHA256 signature algorithm is used, and up to 10 MB when TC3-HMAC-SHA256 is used.

4. Character Encoding
Only UTF-8 encoding is used.

©2013-2022 Tencent Cloud. All rights reserved.

Page 14 of 321

Face Recognition

Common Params：

Last updated 2023-02-27 15:22:46
Common parameters are used for all APIs authenticating requestors. Common parameters must be included in all API
requests, and they will not be described in individual API documents.
The exact contents of the common parameters will vary depending on the version of the signature method you use.

Common parameters for Signature Algorithm v3
When the TC3-HMAC-SHA256 algorithm is used, the common parameters should be uniformly placed in the HTTP
request header, as shown below:
Parameter
Name

Type

Required

Description
The name of the API for the desired operation. For the specific value, see

X-TC-Action

X-TCRegion

X-TCTimestamp

StringStringYes

Yes

description of common parameter Action in the input parameters in r
documentation. For example, the API for querying the CVM instance list is
DescribeInstances .
Region parameter, which is used to identify the region to which the data ywork with belongs. For values supported for an API, see the description oparameter Region in the input parameters in related API documentati
parameter is not required for some APIs (which will be indicated in related
documentation), and will not take effect even it is passed.

Integer

X-TCVersion

StringAuthorization

StringYes

Yes

The current UNIX timestamp that records the time when the API request w
for example, 1529223702. Note: If the difference between the UNIX times
server time is greater than 5 minutes, a signature expiration error may occ
API version of the action. For the valid values, see the description of the cparameter Version in the API documentation. For example, the versi
2017-03-12.

Yes

The HTTP authentication request header, for example:
TC3-HMAC-SHA256 Credential=AKIDEXAMPLE/Date/service/tc3_requ
SignedHeaders=content-type;host,Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc96317
Here:- TC3-HMAC-SHA256: Signature method, currently fixed as this value;- Credential: Signature credential; AKIDEXAMPLE is the SecretId; Date is
UTC time, and this value must match the value of X-TC-Timestamp (a co©2013-2022 Tencent Cloud. All rights reserved.

Page 15 of 321

Face Recognition

parameter) in UTC time format; service is the name of the product/service
generally a domain name prefix. For example, a domain name cvm.tencen
refers to the CVM product and the value would be cvm;
- SignedHeaders: The headers that contains the authentication informatio
type and host are the required headers;- Signature: Signature digest.

X-TC-Token

String

No

The token used for a temporary certificate. It must be used with a tempora
can obtain the temporary key and token by calling a CAM API. No token ia long-term key.

Assuming you want to query the list of Cloud Virtual Machine instances in the Guangzhou region, the request structurein the form of request URL, request header and request body may be as follows:
Example of an HTTP GET request structure:https://cvm.tencentcloudapi.com/?Limit=10&Offset=0
Authorization: TC3-HMAC-SHA256 Credential=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE/20
18-10-09/cvm/tc3_request, SignedHeaders=content-type;host, Signature=5da7a33f6993
f0614b047e5df4582db9e9bf4672ba50567dba16c6ccf174c474
Content-Type: application/x-www-form-urlencoded
Host: cvm.tencentcloudapi.com
X-TC-Action: DescribeInstances
X-TC-Version: 2017-03-12
X-TC-Timestamp: 1539084154
X-TC-Region: ap-guangzhou
The following example shows you how to structure an HTTP POST (application/json) request:
https://cvm.tencentcloudapi.com/
Authorization: TC3-HMAC-SHA256 Credential=AKIDEXAMPLE/2018-05-30/cvm/tc3_request,
SignedHeaders=content-type;host, Signature=582c400e06b5924a6f2b5d7d672d79c15b1316
2d9279b0855cfba6789a8edb4c
Content-Type: application/json
Host: cvm.tencentcloudapi.com
X-TC-Action: DescribeInstances
X-TC-Version: 2017-03-12
X-TC-Timestamp: 1527672334
X-TC-Region: ap-guangzhou{"Offset":0,"Limit":10}
Example of an HTTP POST (multipart/form-data) request structure (only supported by specific APIs):©2013-2022 Tencent Cloud. All rights reserved.

Page 16 of 321

Face Recognition

https://cvm.tencentcloudapi.com/
Authorization: TC3-HMAC-SHA256 Credential=AKIDEXAMPLE/2018-05-30/cvm/tc3_request,
SignedHeaders=content-type;host, Signature=582c400e06b5924a6f2b5d7d672d79c15b1316
2d9279b0855cfba6789a8edb4c
Content-Type: multipart/form-data; boundary=58731222010402
Host: cvm.tencentcloudapi.com
X-TC-Action: DescribeInstances
X-TC-Version: 2017-03-12
X-TC-Timestamp: 1527672334
X-TC-Region: ap-guangzhou--58731222010402
Content-Disposition: form-data; name="Offset"
0--58731222010402
Content-Disposition: form-data; name="Limit"
10--58731222010402--

Common parameters for Signature Algorithm v1
To adopt the HmacSHA1 and HmacSHA256 signature methods, common parameters must be put into the request
string, as shown below:
Parameter NameType

Required

Description
The name of the API for the desired operation. For the specificvalue, see the description of common parameter Action in the

ActionStringYes

input parameters in related API documentation. For example, theAPI for querying the CVM instance list is
DescribeInstances .
Region parameter, which is used to identify the region to which
the data you want to work with belongs. For values supported for
an API, see the description of common parameter Region in

RegionStringYes

the input parameters in related API documentation. Note: Thisparameter is not required for some APIs (which will be indicated inrelated API documentation), and will not take effect even if it ispassed.

©2013-2022 Tencent Cloud. All rights reserved.

Page 17 of 321

Face Recognition

Timestamp

IntegerYes

The current UNIX timestamp that records the time when the API
request was initiated, for example, 1529223702. If the difference
between the value and the current system time is too large, asignature expiration error may occur.
A random positive integer used along with Timestamp to

Nonce

Integer

Yes

SecretId

StringYes

The identifying SecretId obtained on the Cloud API Key page. A
SecretId corresponds to a unique SecretKey which is used togenerate the request signature (Signature).

Yes

Request signature used to verify the validity of this request. This iscalculated based on the actual input parameters. For more
information about how this is calculated, see the API
authentication documentation.

Signature

VersionStringStringYes

prevent replay attacks.

API version of the action. For the valid values, see the descriptionof the common input parameter Version in the API
documentation. For example, the version of CVM is 2017-03-12.

SignatureMethod

StringNo

Signature method. Currently, only HmacSHA256 and HmacSHA1
are supported. The HmacSHA256 algorithm is used to verify thesignature only when this parameter is specified as HmacSHA256.
In other cases, the signature is verified with HmacSHA1.

Token

String

No

The token used for a temporary certificate. It must be used with atemporary key. You can obtain the temporary key and token bycalling a CAM API. No token is required for a long-term key.

Assuming you want to query the list of Cloud Virtual Machine instances in the Guangzhou region, the request structurein the form of request URL, request header and request body may be as follows:
Example of an HTTP GET request structure:https://cvm.tencentcloudapi.com/?Action=DescribeInstances&Version=2017-03-12&Sign
atureMethod=HmacSHA256&Timestamp=1527672334&Signature=37ac2f4fde00b0ac9bd9eadeb45
9b1bbee224158d66e7ae5fcadb70b2d181d02&Region=ap-guangzhou&Nonce=23823223&SecretId=AKIDEXAMPLE
Host: cvm.tencentcloudapi.com
Content-Type: application/x-www-form-urlencoded
Example of an HTTP POST request structure:©2013-2022 Tencent Cloud. All rights reserved.

Page 18 of 321

Face Recognition

https://cvm.tencentcloudapi.com/
Host: cvm.tencentcloudapi.com
Content-Type: application/x-www-form-urlencoded
Action=DescribeInstances&Version=2017-03-12&SignatureMethod=HmacSHA256&Timestamp=
1527672334&Signature=37ac2f4fde00b0ac9bd9eadeb459b1bbee224158d66e7ae5fcadb70b2d18
1d02&Region=ap-guangzhou&Nonce=23823223&SecretId=AKIDEXAMPLE©2013-2022 Tencent Cloud. All rights reserved.

Page 19 of 321

Face Recognition

Signature v3：

Last updated 2020-10-16 18:31:14
TencentCloud API authenticates every single request, i.e., the request must be signed using the security credentials inthe designated steps. Each request has to contain the signature information (Signature) in the common request
parameters and be sent in the specified way and format.

Applying for Security Credentials
The security credential used in this document is a key, which includes a SecretId and a SecretKey. Each user canhave up to two pairs of keys.
SecretId: Used to identify the API caller, which is just like a username.
SecretKey: Used to authenticate the API caller, which is just like a password.
You must keep your security credentials private and avoid disclosure; otherwise, your assets may becompromised. If they are disclosed, please disable them as soon as possible.
You can apply for the security credentials through the following steps:
1. Log in to the Tencent Cloud Console.
2. Go to the TencentCloud API Key console page.
3. On the TencentCloud API Key page, click Create to create a SecretId/SecretKey pair.

Using the Resources for Developers
TencentCloud API comes with SDKs for seven commonly used programming languages, including Python, Java,
PHP, Go, NodeJS and .NET. In addition, it provides API Explorer which enables online call, signature verification, andSDK code generation. If you have any troubles calculating a signature, consult these resources.

TC3-HMAC-SHA256 Signature Algorithm
Compatible with the previous HmacSHA1 and HmacSHA256 signature algorithms, the TC3-HMAC-SHA256
signature algorithm is more secure and supports larger requests and JSON format with better performance. We
recommend using TC3-HMAC-SHA256 to calculate the signature.
TencentCloud API supports both GET and POST requests. For the GET method, only the Content-Type:application/x-www-form-urlencoded protocol format is supported. For the POST method, two protocol formats,©2013-2022 Tencent Cloud. All rights reserved.

Page 20 of 321

Face Recognition

Content-Type: application/json and Content-Type: multipart/form-data, are supported. The JSON format is supported
by default for all business APIs, and the multipart format is supported only for specific business APIs. In this case, theAPI cannot be called in JSON format. See the specific business API documentation for more information. The POST
method is recommended, as there is no difference in the results of both the methods, but the GET method only
supports request packets up to 32 KB.
The following uses querying the list of CVM instances in the Guangzhou region as an example to describe the steps ofsignature splicing. We chose this API because:
1. CVM is activated by default, and this API is often used;
2. It is read-only and does not change the status of existing resources;
3. It covers many types of parameters, which allows it to be used to demonstrate how to use arrays containing data
structures.
In the example, we try to choose common parameters and API parameters that are prone to mistakes. When you
actually call an API, please use parameters based on the actual conditions. The parameters vary by API. Do not copy
the parameters and values in this example.
Assuming that your SecretId and SecretKey are AKIDz8krbsJ5yKBZQpn74WFkmLPx3******* andGu5t9xGARNpq86cd98joQYCN3******* , respectively, if you want to view the status of the instance in the
Guangzhou region whose CVM instance name is "unnamed" and have only one data entry returned, then the request
may be:curl -X POST https://cvm.tencentcloudapi.com \-H "Authorization: TC3-HMAC-SHA256 Credential=AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******/2019-02-25/cvm/tc3_request, SignedHeaders=content-type;host, Signature=c492e8e4
1437e97a620b728c301bb8d17e7dc0c17eeabce80c20cd70fc3a78ff" \-H "Content-Type: application/json; charset=utf-8" \-H "Host: cvm.tencentcloudapi.com" \-H "X-TC-Action: DescribeInstances" \-H "X-TC-Timestamp: 1551113065" \-H "X-TC-Version: 2017-03-12" \-H "X-TC-Region: ap-guangzhou" \-d '{"Limit": 1, "Filters": [{"Values": ["unnamed"], "Name": "instance-name"}]}'The signature calculation process is explained in detail below.

1. Concatenating the CanonicalRequest String
Concatenate the canonical request string (CanonicalRequest) in the following pseudocode format:
CanonicalRequest =HTTPRequestMethod + '\n' +CanonicalURI + '\n' +©2013-2022 Tencent Cloud. All rights reserved.

Page 21 of 321

Face Recognition

CanonicalQueryString + '\n' +CanonicalHeaders + '\n' +SignedHeaders + '\n' +HashedRequestPayload
Field Name

Explanation

HTTPRequestMethod

HTTP request method (GET or POST). This example uses POST .

CanonicalURI

URI parameter. Slash ("/") is used for API 3.0.
The query string in the URL of the originating HTTP request. This is always an empty st“” for POST requests, and is the string after the question mark (?) for GET requests. Fo

CanonicalQueryString。

example: Limit=10&Offset=0
Note: CanonicalQueryString must be URL-encoded, referencing RFC3986, theUTF8 character set. We recommend using the programming language library. All specia
characters must be encoded and capitalized.
Header information for signature calculation, including at least two headers of host
content-type . Custom headers can be added to participate in the signature proce
improve the uniqueness and security of the request.
Concatenation rules:
1. Both the key and value of the header should be converted to lowercase with the lead

CanonicalHeaders

and trailing spaces removed, so they are concatenated in the format of key:value\nformat;2. If there are multiple headers, they should be sorted in ASCII ascending order by theheader keys (lowercase).
The calculation result in this example is content-type:application/json;
charset=utf-8\nhost:cvm.tencentcloudapi.com\n .
Note: content-type must match the actually sent content. In some programming
languages, a charset value would be added even if it is not specified. In this case, therequest sent is different from the one signed, and the sever will return an error indicating
signature verification failed.
Header information for signature calculation, indicating which headers of the request
participate in the signature process (they must each individually correspond to the headin CanonicalHeaders). Content-type and host are required headers.

SignedHeaders

Concatenation rules:
1. Both the key and value of the header should be converted to lowercase;
2. If there are multiple headers, they should be sorted in ASCII ascending order by theheader keys (lowercase) and separated by semicolons (;).
The value in this example is content-type;hostHashedRequestPayload

Hash value of the request payload (i.e., the body, such as {"Limit": 1, "Filter©2013-2022 Tencent Cloud. All rights reserved.

Page 22 of 321

Face Recognition[{"Values": ["unnamed"], "Name": "instance-name"}]} in this example
The pseudocode for calculation is
Lowercase(HexEncode(Hash.SHA256(RequestPayload))) by SHA256 hashing the payof the HTTP request, performing hexadecimal encoding, and finally converting the enco
string to lowercase letters. For GET requests, RequestPayload is always an empt
string. The calculation result in this example is
99d58dfbc6745f6747f36bfca17dee5e6881dc0428a0a36f96199342bc5b49

According to the rules above, the CanonicalRequest string obtained in the example is as follows:

POST/
content-type:application/json; charset=utf-8
host:cvm.tencentcloudapi.com
content-type;host
99d58dfbc6745f6747f36bfca17dee5e6881dc0428a0a36f96199342bc5b4907

2. Concatenating the String to Be Signed
The string to sign is concatenated as follows:
StringToSign =Algorithm + \n +RequestTimestamp + \n +CredentialScope + \n +HashedCanonicalRequest
Field Name

Explanation

Algorithm

Signature algorithm, which is currently always TC3-HMAC-SHA256 .
Request timestamp, i.e., the value of the common parameter X-TC-Timestamp in

RequestTimestamp

request header, which is the UNIX timestamp of the current time in seconds, such as1551113065 in this example.
Scope of the credential in the format of Date/service/tc3_request , including
date, requested service and termination string (tc3_request). Date is a date in UT

CredentialScopetime, whose value should match the UTC date converted by the common
parameter X-TC-Timestamp ; service is the product name, which should mthe domain name of the product called. The calculation result in this example is 201
25/cvm/tc3_request .

©2013-2022 Tencent Cloud. All rights reserved.

Page 23 of 321

Face Recognition

HashedCanonicalRequest

Hash value of the CanonicalRequest string concatenated in the steps above. The
pseudocode for calculation is Lowercase(HexEncode(Hash.SHA256(CanonicalRequ
The calculation result in this example is2815843035062fffda5fd6f2a44ea8a34818b0dc46f024b8b3786976a3ad

Note:

1. Date has to be calculated from the timestamp "X-TC-Timestamp" and the time zone is UTC+0. If you add
the system's local time zone information (such as UTC+8), calls can succeed both day and night but willdefinitely fail at 00:00. For example, if the timestamp is 1551113065 and the time in UTC+8 is 2019-02-26
00:44:25, the UTC+0 date in the calculated Date value should be 2019-02-25 instead of 2019-02-26.
2. Timestamp must be the same as your current system time, and your system time and standard time must be
synced; if the difference between Timestamp and your current system time is larger than five minutes, therequest will fail. If your system time is out of sync with the standard time for a while, the request will fail andreturn a signature expiration error.

According to the preceding rules, the string to be signed obtained in the example is as follows:
TC3-HMAC-SHA256
1551113065
2019-02-25/cvm/tc3_request
2815843035062fffda5fd6f2a44ea8a34818b0dc46f024b8b3786976a3adda7a

3. Calculating the Signature
1) Calculate the derived signature key with the following pseudocode:

SecretKey = "Gu5t9xGARNpq86cd98joQYCN3*******"
SecretDate = HMAC_SHA256("TC3" + SecretKey, Date)
SecretService = HMAC_SHA256(SecretDate, Service)
SecretSigning = HMAC_SHA256(SecretService, "tc3_request")
Field Name

Explanation

SecretKey

The original SecretKey, i.e., Gu5t9xGARNpq86cd98joQYCN3******* .

Date

The Date field information in Credential , such as 2019-02-25 in this example.

Service

Value in the Service field in Credential , such as cvm in this example.

©2013-2022 Tencent Cloud. All rights reserved.

Page 24 of 321

Face Recognition

2) Calculate the signature with the following pseudocode:
Signature = HexEncode(HMAC_SHA256(SecretSigning, StringToSign))

4. Concatenating the Authorization
The Authorization is concatenated as follows:

Authorization =Algorithm + ' ' +'Credential=' + SecretId + '/' + CredentialScope + ', ' +'SignedHeaders=' + SignedHeaders + ', ' +'Signature=' + Signature
Field Name

Explanation

Algorithm

Signature algorithm, which is always TC3-HMAC-SHA256 .

SecretId

The SecretId in the key pair, i.e., AKIDz8krbsJ5yKBZQpn74WFkmLPx3******* .

CredentialScope

SignedHeadersSignature

Credential scope (see above). The calculation result in this example is 2019-0225/cvm/tc3_request .
Header information for signature calculation (see above), such as content-type;hostin this example.
Signature value. The calculation result in this example isc492e8e41437e97a620b728c301bb8d17e7dc0c17eeabce80c20cd70fc3a78ff .

According to the rules above, the value obtained in the example is:TC3-HMAC-SHA256 Credential=AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******/2019-02-25/cvm/tc
3_request, SignedHeaders=content-type;host, Signature=c492e8e41437e97a620b728c301
bb8d17e7dc0c17eeabce80c20cd70fc3a78ff
The following example shows a finished authorization header:
POST https://cvm.tencentcloudapi.com/
Authorization: TC3-HMAC-SHA256 Credential=AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******/20
19-02-25/cvm/tc3_request, SignedHeaders=content-type;host, Signature=c492e8e41437
e97a620b728c301bb8d17e7dc0c17eeabce80c20cd70fc3a78ff
Content-Type: application/json; charset=utf-8
Host: cvm.tencentcloudapi.com©2013-2022 Tencent Cloud. All rights reserved.

Page 25 of 321

Face Recognition

X-TC-Action: DescribeInstances
X-TC-Version: 2017-03-12
X-TC-Timestamp: 1551113065
X-TC-Region: ap-guangzhou{"Limit": 1, "Filters": [{"Values": ["unnamed"], "Name": "instance-name"}]}5. Signature Demo
When calling API 3.0, you are recommended to use the corresponding Tencent Cloud SDK 3.0 which encapsulates
the signature process, enabling you to focus on only the specific APIs provided by the product when developing. See
SDK Center for more information. Currently, the following programming languages are supported:
PythonJava
PHP
Go
NodeJS.NET
To further explain the signing process, we will use a programming language to implement the process describedabove. The request domain name, API and parameter values in the sample are used here. This goal of this example isonly to provide additional clarification for the signature process, please see the SDK for actual usage.
The final output URL might be: https://cvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=apguangzhou&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******&Signature=EliP9YW3pW28FpsEdkXt%2F%2B
WcGeI%3D&Timestamp=1465185768&Version=2017-03-12.
Note: The key in the example is fictitious, and the timestamp is not the current time of the system, so if this URL is
opened in the browser or called using commands such as curl, an authentication error will be returned: Signature
expired. In order to get a URL that can work properly, you need to replace the SecretId and SecretKey in the example
with your real credentials and use the current time of the system as the Timestamp.
Note: In the example below, even if you use the same programming language, the order of the parameters in the URL
may be different for each execution. However, the order does not matter, as long as all the parameters are included in
the URL and the signature is calculated correctly.
Note: The following code is only applicable to API 3.0. It cannot be directly used in other signature processes. Even
with an older API, signature calculation errors may occur due to the differences in details. Please refer to thecorresponding documentation.
Java©2013-2022 Tencent Cloud. All rights reserved.

Page 26 of 321

Face Recognition

import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.TimeZone;
import java.util.TreeMap;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
public class TencentCloudAPITC3Demo {private final static Charset UTF8 = StandardCharsets.UTF_8;
private final static String SECRET_ID = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******";
private final static String SECRET_KEY = "Gu5t9xGARNpq86cd98joQYCN3*******";
private final static String CT_JSON = "application/json; charset=utf-8";
public static byte[] hmac256(byte[] key, String msg) throws Exception {Mac mac = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKeySpec = new SecretKeySpec(key, mac.getAlgorithm());
mac.init(secretKeySpec);
return mac.doFinal(msg.getBytes(UTF8));}
public static String sha256Hex(String s) throws Exception {MessageDigest md = MessageDigest.getInstance("SHA-256");
byte[] d = md.digest(s.getBytes(UTF8));
return DatatypeConverter.printHexBinary(d).toLowerCase();}public static void main(String[] args) throws Exception {String service = "cvm";
String host = "cvm.tencentcloudapi.com";
String region = "ap-guangzhou";String action = "DescribeInstances";
String version = "2017-03-12";
String algorithm = "TC3-HMAC-SHA256";
String timestamp = "1551113065";//String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");// Pay attention to the time zone; otherwise, errors may occur
sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
String date = sdf.format(new Date(Long.valueOf(timestamp + "000")));// ************* Step 1: Concatenate the CanonicalRequest string *************
String httpRequestMethod = "POST";©2013-2022 Tencent Cloud. All rights reserved.

Page 27 of 321

Face Recognition

String canonicalUri = "/";
String canonicalQueryString = "";String canonicalHeaders = "content-type:application/json; charset=utf-8\n" + "host:" + host + "\n";String signedHeaders = "content-type;host";
String payload = "{\"Limit\": 1, \"Filters\": [{\"Values\": [\"unnamed\"], \"Name\": \"instance-name\"}]}";
String hashedRequestPayload = sha256Hex(payload);
String canonicalRequest = httpRequestMethod + "\n" + canonicalUri + "\n" + canoni
calQueryString + "\n"+ canonicalHeaders + "\n" + signedHeaders + "\n" + hashedRequestPayload;
System.out.println(canonicalRequest);// ************* Step 2: Concatenate the string to sign *************
String credentialScope = date + "/" + service + "/" + "tc3_request";
String hashedCanonicalRequest = sha256Hex(canonicalRequest);
String stringToSign = algorithm + "\n" + timestamp + "\n" + credentialScope +"\n" + hashedCanonicalRequest;
System.out.println(stringToSign);// ************* Step 3: Calculate the signature *************
byte[] secretDate = hmac256(("TC3" + SECRET_KEY).getBytes(UTF8), date);byte[] secretService = hmac256(secretDate, service);byte[] secretSigning = hmac256(secretService, "tc3_request");String signature = DatatypeConverter.printHexBinary(hmac256(secretSigning, string
ToSign)).toLowerCase();
System.out.println(signature);// ************* Step 4: Concatenate the Authorization *************
String authorization = algorithm + " " + "Credential=" + SECRET_ID + "/" + creden
tialScope + ", "+ "SignedHeaders=" + signedHeaders + ", " + "Signature=" + signature;
System.out.println(authorization);
TreeMap<String, String> headers = new TreeMap<String, String>();headers.put("Authorization", authorization);headers.put("Content-Type", CT_JSON);headers.put("Host", host);
headers.put("X-TC-Action", action);headers.put("X-TC-Timestamp", timestamp);
headers.put("X-TC-Version", version);headers.put("X-TC-Region", region);
StringBuilder sb = new StringBuilder();sb.append("curl -X POST https://").append(host).append(" -H \"Authorization: ").append(authorization).append("\"")©2013-2022 Tencent Cloud. All rights reserved.

Page 28 of 321

Face Recognition.append(" -H \"Content-Type: application/json; charset=utf-8\"").append(" -H \"Host: ").append(host).append("\"").append(" -H \"X-TC-Action: ").append(action).append("\"").append(" -H \"X-TC-Timestamp: ").append(timestamp).append("\"").append(" -H \"X-TC-Version: ").append(version).append("\"").append(" -H \"X-TC-Region: ").append(region).append("\"").append(" -d '").append(payload).append("'");
System.out.println(sb.toString());}}

Python# -*- coding: utf-8 -*import hashlib, hmac, json, os, sys, timefrom datetime import datetime# Key Parameters
secret_id = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"
secret_key = "Gu5t9xGARNpq86cd98joQYCN3*******"
service = "cvm"host = "cvm.tencentcloudapi.com"
endpoint = "https://" + hostregion = "ap-guangzhou"
action = "DescribeInstances"version = "2017-03-12"
algorithm = "TC3-HMAC-SHA256"#timestamp = int(time.time())
timestamp = 1551113065
date = datetime.utcfromtimestamp(timestamp).strftime("%Y-%m-%d")params = {"Limit": 1, "Filters": [{"Name": "instance-name", "Values": ["unnamed"]}]}# ************* Step 1: Concatenate the CanonicalRequest string *************
http_request_method = "POST"
canonical_uri = "/"canonical_querystring = ""ct = "application/json; charset=utf-8"
payload = json.dumps(params)
canonical_headers = "content-type:%s\nhost:%s\n" % (ct, host)signed_headers = "content-type;host"hashed_request_payload = hashlib.sha256(payload.encode("utf-8")).hexdigest()
canonical_request = (http_request_method + "\n" +canonical_uri + "\n" +canonical_querystring + "\n" +©2013-2022 Tencent Cloud. All rights reserved.

Page 29 of 321

Face Recognition

canonical_headers + "\n" +signed_headers + "\n" +hashed_request_payload)
print(canonical_request)# ************* Step 2: Concatenate the string to sign *************
credential_scope = date + "/" + service + "/" + "tc3_request"
hashed_canonical_request = hashlib.sha256(canonical_request.encode("utf-8")).hexd
igest()
string_to_sign = (algorithm + "\n" +str(timestamp) + "\n" +credential_scope + "\n" +hashed_canonical_request)
print(string_to_sign)# ************* Step 3: Calculate the Signature *************# Function for computing signature digest
def sign(key, msg):
return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
secret_date = sign(("TC3" + secret_key).encode("utf-8"), date)secret_service = sign(secret_date, service)secret_signing = sign(secret_service, "tc3_request")
signature = hmac.new(secret_signing, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
print(signature)# ************* Step 4: Concatenate the Authorization *************
authorization = (algorithm + " " +"Credential=" + secret_id + "/" + credential_scope + ", " +"SignedHeaders=" + signed_headers + ", " +"Signature=" + signature)
print(authorization)
print('curl -X POST ' + endpoint+ ' -H "Authorization: ' + authorization + '"'+ ' -H "Content-Type: application/json; charset=utf-8"'+ ' -H "Host: ' + host + '"'+ ' -H "X-TC-Action: ' + action + '"'+ ' -H "X-TC-Timestamp: ' + str(timestamp) + '"'+ ' -H "X-TC-Version: ' + version + '"'+ ' -H "X-TC-Region: ' + region + '"'+ " -d '" + payload + "'")

Golang©2013-2022 Tencent Cloud. All rights reserved.

Page 30 of 321

Face Recognition

package main
import ("crypto/hmac""crypto/sha256""encoding/hex""fmt""time")
func sha256hex(s string) string {b := sha256.Sum256([]byte(s))
return hex.EncodeToString(b[:])}func hmacsha256(s, key string) string {hashed := hmac.New(sha256.New, []byte(key))hashed.Write([]byte(s))
return string(hashed.Sum(nil))}func main() {secretId := "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"
secretKey := "Gu5t9xGARNpq86cd98joQYCN3*******"
host := "cvm.tencentcloudapi.com"
algorithm := "TC3-HMAC-SHA256"
service := "cvm"version := "2017-03-12"
action := "DescribeInstances"
region := "ap-guangzhou"//var timestamp int64 = time.Now().Unix()
var timestamp int64 = 1551113065// step 1: build canonical request string
httpRequestMethod := "POST"
canonicalURI := "/"canonicalQueryString := ""canonicalHeaders := "content-type:application/json; charset=utf-8\n" + "host:" +host + "\n"signedHeaders := "content-type;host"
payload := `{"Limit": 1, "Filters": [{"Values": ["unnamed"], "Name": "instance-name"}]}`
hashedRequestPayload := sha256hex(payload)
canonicalRequest := fmt.Sprintf("%s\n%s\n%s\n%s\n%s\n%s",
httpRequestMethod,
canonicalURI,©2013-2022 Tencent Cloud. All rights reserved.

Page 31 of 321

Face Recognition

canonicalQueryString,canonicalHeaders,signedHeaders,hashedRequestPayload)
fmt.Println(canonicalRequest)// step 2: build string to sign
date := time.Unix(timestamp, 0).UTC().Format("2006-01-02")
credentialScope := fmt.Sprintf("%s/%s/tc3_request", date, service)hashedCanonicalRequest := sha256hex(canonicalRequest)
string2sign := fmt.Sprintf("%s\n%d\n%s\n%s",
algorithm,
timestamp,
credentialScope,
hashedCanonicalRequest)
fmt.Println(string2sign)// step 3: sign string
secretDate := hmacsha256(date, "TC3"+secretKey)
secretService := hmacsha256(service, secretDate)secretSigning := hmacsha256("tc3_request", secretService)signature := hex.EncodeToString([]byte(hmacsha256(string2sign, secretSigning)))
fmt.Println(signature)// step 4: build authorization
authorization := fmt.Sprintf("%s Credential=%s/%s, SignedHeaders=%s, Signature=%s",algorithm,
secretId,
credentialScope,
signedHeaders,signature)
fmt.Println(authorization)
curl := fmt.Sprintf(`curl -X POST https://%s\-H "Authorization: %s"\
-H "Content-Type: application/json; charset=utf-8"\-H "Host: %s" -H "X-TC-Action: %s"\
-H "X-TC-Timestamp: %d"\
-H "X-TC-Version: %s"\
-H "X-TC-Region: %s"\-d '%s'`, host, authorization, host, action, timestamp, version, region, payload)
fmt.Println(curl)}

PHP©2013-2022 Tencent Cloud. All rights reserved.

Page 32 of 321

Face Recognition<?php$secretId = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******";$secretKey = "Gu5t9xGARNpq86cd98joQYCN3*******";$host = "cvm.tencentcloudapi.com";$service = "cvm";$version = "2017-03-12";$action = "DescribeInstances";$region = "ap-guangzhou";// $timestamp = time();$timestamp = 1551113065;$algorithm = "TC3-HMAC-SHA256";// step 1: build canonical request string$httpRequestMethod = "POST";$canonicalUri = "/";
$canonicalQueryString = "";$canonicalHeaders = "content-type:application/json; charset=utf-8\n"."host:".$host."\n";$signedHeaders = "content-type;host";$payload = '{"Limit": 1, "Filters": [{"Values": ["unnamed"], "Name": "instance-name"}]}';$hashedRequestPayload = hash("SHA256", $payload);$canonicalRequest = $httpRequestMethod."\n".$canonicalUri."\n".$canonicalQueryString."\n".$canonicalHeaders."\n".$signedHeaders."\n".$hashedRequestPayload;
echo $canonicalRequest.PHP_EOL;// step 2: build string to sign
$date = gmdate("Y-m-d", $timestamp);$credentialScope = $date."/".$service."/tc3_request";$hashedCanonicalRequest = hash("SHA256", $canonicalRequest);$stringToSign = $algorithm."\n".$timestamp."\n".$credentialScope."\n".$hashedCanonicalRequest;
echo $stringToSign.PHP_EOL;// step 3: sign string$secretDate = hash_hmac("SHA256", $date, "TC3".$secretKey, true);$secretService = hash_hmac("SHA256", $service, $secretDate, true);$secretSigning = hash_hmac("SHA256", "tc3_request", $secretService, true);$signature = hash_hmac("SHA256", $stringToSign, $secretSigning);
echo $signature.PHP_EOL;©2013-2022 Tencent Cloud. All rights reserved.

Page 33 of 321

Face Recognition// step 4: build authorization$authorization = $algorithm." Credential=".$secretId."/".$credentialScope.", SignedHeaders=content-type;host, Signature=".$signature;echo $authorization.PHP_EOL;$curl = "curl -X POST https://".$host.' -H "Authorization: '.$authorization.'"'.' -H "Content-Type: application/json; charset=utf-8"'.' -H "Host: '.$host.'"'.' -H "X-TC-Action: '.$action.'"'.' -H "X-TC-Timestamp: '.$timestamp.'"'.' -H "X-TC-Version: '.$version.'"'.' -H "X-TC-Region: '.$region.'"'." -d '".$payload."'";
echo $curl.PHP_EOL;

Ruby# -*- coding: UTF-8 -*# require ruby>=2.3.0
require 'digest'
require 'json'
require 'time'require 'openssl'# Key Parameters
secret_id = 'AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******'
secret_key = 'Gu5t9xGARNpq86cd98joQYCN3*******'
service = 'cvm'
host = 'cvm.tencentcloudapi.com'
endpoint = 'https://' + hostregion = 'ap-guangzhou'
action = 'DescribeInstances'version = '2017-03-12'
algorithm = 'TC3-HMAC-SHA256'# timestamp = Time.now.to_i
timestamp = 1551113065
date = Time.at(timestamp).utc.strftime('%Y-%m-%d')# ************* Step 1: Concatenate the CanonicalRequest string *************
http_request_method = 'POST'
canonical_uri = '/'canonical_querystring = ''©2013-2022 Tencent Cloud. All rights reserved.

Page 34 of 321

Face Recognition

canonical_headers = "content-type:application/json; charset=utf-8\nhost:#{host}\n"signed_headers = 'content-type;host'# params = { 'Limit' => 1, 'Filters' => [{ 'Name' => 'instance-name', 'Values' =>['unnamed'] }] }# payload = JSON.generate(params, { 'ascii_only' => true, 'space' => ' ' })# json will generate in random order, to get specified result in example, we hard-code it here.
payload = '{"Limit": 1, "Filters": [{"Values": ["unnamed"], "Name": "instance-name"}]}'
hashed_request_payload = Digest::SHA256.hexdigest(payload)
canonical_request = [http_request_method,
canonical_uri,canonical_querystring,canonical_headers,signed_headers,hashed_request_payload,].join("\n")puts canonical_request# ************* Step 2: Concatenate the string to sign *************
credential_scope = date + '/' + service + '/' + 'tc3_request'
hashed_request_payload = Digest::SHA256.hexdigest(canonical_request)
string_to_sign = [algorithm,
timestamp.to_s,
credential_scope,
hashed_request_payload,].join("\n")puts string_to_sign# ************* Step 3: Calculate the Signature *************
digest = OpenSSL::Digest.new('sha256')secret_date = OpenSSL::HMAC.digest(digest, 'TC3' + secret_key, date)secret_service = OpenSSL::HMAC.digest(digest, secret_date, service)secret_signing = OpenSSL::HMAC.digest(digest, secret_service, 'tc3_request')
signature = OpenSSL::HMAC.hexdigest(digest, secret_signing, string_to_sign)
puts signature# ************* Step 4: Concatenate the Authorization *************
authorization = "#{algorithm} Credential=#{secret_id}/#{credential_scope}, Signed
Headers=#{signed_headers}, Signature=#{signature}"puts authorization
puts 'curl -X POST ' + endpoint \©2013-2022 Tencent Cloud. All rights reserved.

Page 35 of 321

Face Recognition+ ' -H "Authorization: ' + authorization + '"' \+ ' -H "Content-Type: application/json; charset=utf-8"' \+ ' -H "Host: ' + host + '"' \+ ' -H "X-TC-Action: ' + action + '"' \+ ' -H "X-TC-Timestamp: ' + timestamp.to_s + '"' \+ ' -H "X-TC-Version: ' + version + '"' \+ ' -H "X-TC-Region: ' + region + '"' \+ " -d '" + payload + "'"DotNetusing System;
using System.Collections.Generic;using System.Security.Cryptography;
using System.Text;
public class Application{
public static string SHA256Hex(string s){
using (SHA256 algo = SHA256.Create()){
byte[] hashbytes = algo.ComputeHash(Encoding.UTF8.GetBytes(s));
StringBuilder builder = new StringBuilder();for (int i = 0; i < hashbytes.Length; ++i){
builder.Append(hashbytes[i].ToString("x2"));}
return builder.ToString();}}
public static byte[] HmacSHA256(byte[] key, byte[] msg){
using (HMACSHA256 mac = new HMACSHA256(key)){
return mac.ComputeHash(msg);}}
public static Dictionary<String, String> BuildHeaders(string secretid,
string secretkey, string service, string endpoint, string region,
string action, string version, DateTime date, string requestPayload){
string datestr = date.ToString("yyyy-MM-dd");
DateTime startTime = new DateTime(1970, 1, 1, 0, 0, 0, 0, DateTimeKind.Utc);
long requestTimestamp = (long)Math.Round((date - startTime).TotalMilliseconds, Mi©2013-2022 Tencent Cloud. All rights reserved.

Page 36 of 321

Face Recognition

dpointRounding.AwayFromZero) / 1000;// ************* Step 1: Concatenate the CanonicalRequest string *************
string algorithm = "TC3-HMAC-SHA256";
string httpRequestMethod = "POST";
string canonicalUri = "/";
string canonicalQueryString = "";string contentType = "application/json";string canonicalHeaders = "content-type:" + contentType + "; charset=utf-8\n" +"host:" + endpoint + "\n";string signedHeaders = "content-type;host";
string hashedRequestPayload = SHA256Hex(requestPayload);string canonicalRequest = httpRequestMethod + "\n"+ canonicalUri + "\n"+ canonicalQueryString + "\n"+ canonicalHeaders + "\n"+ signedHeaders + "\n"+ hashedRequestPayload;
Console.WriteLine(canonicalRequest);
Console.WriteLine("----------------------------------");// ************ Step 2: Concatenate the string to sign *************
string credentialScope = datestr + "/" + service + "/" + "tc3_request";
string hashedCanonicalRequest = SHA256Hex(canonicalRequest);
string stringToSign = algorithm + "\n" + requestTimestamp.ToString() + "\n" + cre
dentialScope + "\n" + hashedCanonicalRequest;
Console.WriteLine(stringToSign);
Console.WriteLine("----------------------------------");// ************* Step 3: Calculate the signature *************
byte[] tc3SecretKey = Encoding.UTF8.GetBytes("TC3" + secretkey);byte[] secretDate = HmacSHA256(tc3SecretKey, Encoding.UTF8.GetBytes(datestr));byte[] secretService = HmacSHA256(secretDate, Encoding.UTF8.GetBytes(service));byte[] secretSigning = HmacSHA256(secretService, Encoding.UTF8.GetBytes("tc3_request"));
byte[] signatureBytes = HmacSHA256(secretSigning, Encoding.UTF8.GetBytes(stringTo
Sign));
string signature = BitConverter.ToString(signatureBytes).Replace("-", "").ToLower();
Console.WriteLine(signature);
Console.WriteLine("----------------------------------");// ************* Step 4: Concatenate the Authorization *************
string authorization = algorithm + " "+ "Credential=" + secretid + "/" + credentialScope + ", "+ "SignedHeaders=" + signedHeaders + ", "+ "Signature=" + signature;
Console.WriteLine(authorization);©2013-2022 Tencent Cloud. All rights reserved.

Page 37 of 321

Face Recognition

Console.WriteLine("----------------------------------");
Dictionary<string, string> headers = new Dictionary<string, string>();headers.Add("Authorization", authorization);headers.Add("Host", endpoint);
headers.Add("Content-Type", contentType + "; charset=utf-8");
headers.Add("X-TC-Timestamp", requestTimestamp.ToString());
headers.Add("X-TC-Version", version);headers.Add("X-TC-Action", action);headers.Add("X-TC-Region", region);
return headers;}public static void Main(string[] args){// SecretID and SecretKey
string SECRET_ID = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******";
string SECRET_KEY = "Gu5t9xGARNpq86cd98joQYCN3*******";
string service = "cvm";
string endpoint = "cvm.tencentcloudapi.com";string region = "ap-guangzhou";string action = "DescribeInstances";
string version = "2017-03-12";// The timestamp `2019-02-26 00:44:25` used here is only for reference. In a proj
ect, use the following parameter:// DateTime date = DateTime.UtcNow;// Enter the correct time zone. We recommend using UTC timestamp to avoid errors.
DateTime date = new DateTime(1970, 1, 1, 0, 0, 0, 0, DateTimeKind.Utc).AddSeconds(1551113065);
string requestPayload = "{\"Limit\": 1, \"Filters\": [{\"Values\": [\"\\u672a\\u5
47d\\u540d\"], \"Name\": \"instance-name\"}]}";
Dictionary<string, string> headers = BuildHeaders(SECRET_ID, SECRET_KEY, service, endpoint, region, action, version, date, requestPayload);
Console.WriteLine("POST https://cvm.tencentcloudapi.com");foreach (KeyValuePair<string, string> kv in headers){Console.WriteLine(kv.Key + ": " + kv.Value);}
Console.WriteLine();Console.WriteLine(requestPayload);}}©2013-2022 Tencent Cloud. All rights reserved.

Page 38 of 321

Face Recognition

NodeJS
const crypto = require('crypto');function sha256(message, secret = '', encoding) {const hmac = crypto.createHmac('sha256', secret)return hmac.update(message).digest(encoding)}
function getHash(message, encoding = 'hex') {const hash = crypto.createHash('sha256')
return hash.update(message).digest(encoding)}
function getDate(timestamp) {const date = new Date(timestamp * 1000)
const year = date.getUTCFullYear()const month = ('0' + (date.getUTCMonth() + 1)).slice(-2)
const day = ('0' + date.getUTCDate()).slice(-2)
return `${year}-${month}-${day}`}function main(){const SECRET_ID = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"
const SECRET_KEY = "Gu5t9xGARNpq86cd98joQYCN3*******"
const endpoint = "cvm.tencentcloudapi.com"
const service = "cvm"
const region = "ap-guangzhou"
const action = "DescribeInstances"
const version = "2017-03-12"//const timestamp = getTime()
const timestamp = 1551113065
const date = getDate(timestamp)// ************* Step 1: Concatenate the CanonicalRequest string *************
const signedHeaders = "content-type;host"const payload = "{\"Limit\": 1, \"Filters\": [{\"Values\": [\"unnamed\"], \"Name\": \"instance-name\"}]}"
const hashedRequestPayload = getHash(payload);
const httpRequestMethod = "POST"
const canonicalUri = "/"const canonicalQueryString = ""const canonicalHeaders = "content-type:application/json; charset=utf-8\n" + "host:" + endpoint + "\n"const canonicalRequest = httpRequestMethod + "\n"©2013-2022 Tencent Cloud. All rights reserved.

Page 39 of 321

Face Recognition+ canonicalUri + "\n"+ canonicalQueryString + "\n"+ canonicalHeaders + "\n"+ signedHeaders + "\n"+ hashedRequestPayload
console.log(canonicalRequest)
console.log("----------------------------")// ************* Step 2: Concatenate the string to sign *************
const algorithm = "TC3-HMAC-SHA256"
const hashedCanonicalRequest = getHash(canonicalRequest);
const credentialScope = date + "/" + service + "/" + "tc3_request"
const stringToSign = algorithm + "\n" +timestamp + "\n" +credentialScope + "\n" +hashedCanonicalRequest
console.log(stringToSign)
console.log("----------------------------")// ************* Step 3: Calculate the signature *************
const kDate = sha256(date, 'TC3' + SECRET_KEY)
const kService = sha256(service, kDate)
const kSigning = sha256('tc3_request', kService)
const signature = sha256(stringToSign, kSigning, 'hex')
console.log(signature)
console.log("----------------------------")// ************* Step 4: Concatenate the Authorization *************
const authorization = algorithm + " " +"Credential=" + SECRET_ID + "/" + credentialScope + ", " +"SignedHeaders=" + signedHeaders + ", " +"Signature=" + signature
console.log(authorization)
console.log("----------------------------")
const Call_Information = 'curl -X POST ' + "https://" + endpoint+ ' -H "Authorization: ' + authorization + '"'+ ' -H "Content-Type: application/json; charset=utf-8"'+ ' -H "Host: ' + endpoint + '"'+ ' -H "X-TC-Action: ' + action + '"'+ ' -H "X-TC-Timestamp: ' + timestamp.toString() + '"'+ ' -H "X-TC-Version: ' + version + '"'+ ' -H "X-TC-Region: ' + region + '"'+ " -d '" + payload + "'"console.log(Call_Information)}main()©2013-2022 Tencent Cloud. All rights reserved.

Page 40 of 321

Face Recognition

C++#include <iostream>#include <iomanip>#include <sstream>#include <string>#include <stdio.h>#include <time.h>#include <openssl/sha.h>#include <openssl/hmac.h>using namespace std;
string get_data(int64_t &timestamp){
string utcDate;char buff[20] = {0};// time_t timenow;
struct tm sttime;
sttime = *gmtime(&timestamp);
strftime(buff, sizeof(buff), "%Y-%m-%d", &sttime);
utcDate = string(buff);
return utcDate;}string int2str(int64_t n){
std::stringstream ss;
ss << n;return ss.str();}string sha256Hex(const string &str){
char buf[3];unsigned char hash[SHA256_DIGEST_LENGTH];
SHA256_CTX sha256;
SHA256_Init(&sha256);
SHA256_Update(&sha256, str.c_str(), str.size());
SHA256_Final(hash, &sha256);
std::string NewString = "";for(int i = 0; i < SHA256_DIGEST_LENGTH; i++){snprintf(buf, sizeof(buf), "%02x", hash[i]);NewString = NewString + buf;}
return NewString;©2013-2022 Tencent Cloud. All rights reserved.

Page 41 of 321

Face Recognition}
string HmacSha256(const string &key, const string &input){
unsigned char hash[32];
HMAC_CTX *h;#if OPENSSL_VERSION_NUMBER < 0x10100000L
HMAC_CTX hmac;
HMAC_CTX_init(&hmac);h = &hmac;#else
h = HMAC_CTX_new();#endif
HMAC_Init_ex(h, &key[0], key.length(), EVP_sha256(), NULL);
HMAC_Update(h, ( unsigned char* )&input[0], input.length());
unsigned int len = 32;
HMAC_Final(h, hash, &len);#if OPENSSL_VERSION_NUMBER < 0x10100000L
HMAC_CTX_cleanup(h);#else
HMAC_CTX_free(h);#endif
std::stringstream ss;
ss << std::setfill('0');for (int i = 0; i < len; i++){ss << hash[i];}return (ss.str());}
string HexEncode(const string &input){
static const char* const lut = "0123456789abcdef";
size_t len = input.length();string output;
output.reserve(2 * len);for (size_t i = 0; i < len; ++i){
const unsigned char c = input[i];output.push_back(lut[c >> 4]);
output.push_back(lut[c & 15]);}©2013-2022 Tencent Cloud. All rights reserved.

Page 42 of 321

Face Recognition

return output;}
int main(){string SECRET_ID = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******";
string SECRET_KEY = "Gu5t9xGARNpq86cd98joQYCN3*******";
string service = "cvm";
string host = "cvm.tencentcloudapi.com";string region = "ap-guangzhou";string action = "DescribeInstances";
string version = "2017-03-12";
int64_t timestamp = 1551113065;
string date = get_data(timestamp);// ************* Step 1: Concatenate the CanonicalRequest string *************
string httpRequestMethod = "POST";
string canonicalUri = "/";
string canonicalQueryString = "";string canonicalHeaders = "content-type:application/json; charset=utf-8\nhost:" +host + "\n";string signedHeaders = "content-type;host";
string payload = "{\"Limit\": 1, \"Filters\": [{\"Values\": [\"unnamed\"], \"Name\": \"instance-name\"}]}";
string hashedRequestPayload = sha256Hex(payload);string canonicalRequest = httpRequestMethod + "\n" + canonicalUri + "\n" + canoni
calQueryString + "\n"+ canonicalHeaders + "\n" + signedHeaders + "\n" + hashedRequestPayload;cout << canonicalRequest << endl;
cout << "-----------------------" << endl;// ************* Step 2: Concatenate the string to sign *************
string algorithm = "TC3-HMAC-SHA256";
string RequestTimestamp = int2str(timestamp);
string credentialScope = date + "/" + service + "/" + "tc3_request";
string hashedCanonicalRequest = sha256Hex(canonicalRequest);
string stringToSign = algorithm + "\n" + RequestTimestamp + "\n" + credentialScop
e + "\n" + hashedCanonicalRequest;
cout << stringToSign << endl;
cout << "-----------------------" << endl;// ************* Step 3: Calculate the signature ***************
string kKey = "TC3" + SECRET_KEY;
string kDate = HmacSha256(kKey, date);
string kService = HmacSha256(kDate, service);
string kSigning = HmacSha256(kService, "tc3_request");©2013-2022 Tencent Cloud. All rights reserved.

Page 43 of 321

Face Recognition

string signature = HexEncode(HmacSha256(kSigning, stringToSign));cout << signature << endl;
cout << "-----------------------" << endl;// ************* Step 4: Concatenate the Authorization *************
string authorization = algorithm + " " + "Credential=" + SECRET_ID + "/" + creden
tialScope + ", "+ "SignedHeaders=" + signedHeaders + ", " + "Signature=" + signature;cout << authorization << endl;
cout << "------------------------" << endl;
string headers = "curl -X POST https://" + host + "\n"+ " -H \"Authorization: " + authorization + "\n"+ " -H \"Content-Type: application/json; charset=utf-8\"" + "\n"+ " -H \"Host: " + host + "\n"+ " -H \"X-TC-Action: " + action + "\n"+ " -H \"X-TC-Timestamp: " + RequestTimestamp + "\n"+ " -H \"X-TC-Version: " + version + "\n"+ " -H \"X-TC-Region: " + region + "\n"+ " -d '" + payload;cout << headers << endl;
return 0;};

Signature Failure
The following situational error codes for signature failure may occur. Please resolve the errors accordingly.
Error CodeDescription

AuthFailure.SignatureExpire

Signature expired. Timestamp and server time cannot differ by more than fiveminutes.

AuthFailure.SecretIdNotFoundThe key does not exist. Please go to the console to check whether it isdisabled or you copied fewer or more characters.

AuthFailure.SignatureFailure

Signature error. It is possible that the signature was calculated incorrectly, thesignature does not match the content actually sent, or the SecretKey isincorrect.

AuthFailure.TokenFailure

Temporary certificate token error.

AuthFailure.InvalidSecretId

Invalid key (not a TencentCloud API key type).

©2013-2022 Tencent Cloud. All rights reserved.

Page 44 of 321

Face Recognition

Signature：

Last updated 2021-10-19 15:02:26
Tencent Cloud API authenticates each access request, i.e. each request needs to include authentication information(Signature) in the common parameters to verify the identity of the requester.
The Signature is generated by the security credentials which include SecretId and SecretKey. If you don't have thesecurity credentials yet, go to the TencentCloud API Key page to apply for them; otherwise, you cannot invoke theTencentCloud API.

1. Applying for Security Credentials
Before using the TencentCloud API for the first time, go to the TencentCloud API Key page to apply for security
credentials.
Security credentials consist of SecretId and SecretKey:
SecretId is used to identify the API requester.
SecretKey is used to encrypt the signature string and verify it on the server.
You must keep your security credentials private and avoid disclosure.
You can apply for the security credentials through the following steps:
1. Log in to the Tencent Cloud Console.
2. Go to the TencentCloud API Key page.
3. On the API Key Management page, click Create Key to create a SecretId/SecretKey pair.
Note: Each account can have up to two pairs of SecretId/SecretKey.

2. Generating a SignatureWith the SecretId and SecretKey, a signature can be generated. The following describes how to generate a signature:
Assume that the SecretId and SecretKey are:SecretId: AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******
SecretKey: Gu5t9xGARNpq86cd98joQYCN3*******
Note: This is just an example. For actual operations, please use your own SecretId and SecretKey.

©2013-2022 Tencent Cloud. All rights reserved.

Page 45 of 321

Face Recognition

Take the Cloud Virtual Machine's request to view the instance list (DescribeInstances) as an example. When you
invoke this API, the request parameters may be as follows:
Parameter
nameDescription

Parameter value

Action

Method name

DescribeInstances

SecretId

Key ID

AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******

Timestamp

Current timestamp

1465185768

Nonce

Random positive integer

11886

RegionRegion where the instance islocatedap-guangzhou

InstanceIds.0

ID of the instance to query

ins-09dx96dg

OffsetOffset0

Limit

Allowed maximum output

20

VersionAPI version number

2017-03-12

2.1. Sorting Parameters
First, sort all the request parameters in an ascending lexicographical order (ASCII code) by their names. Notes: (1)Parameters are sorted by their names instead of their values; (2) The parameters are sorted based on ASCII code, notin an alphabetical order or by values. For example, InstanceIds.2 should be arranged after InstanceIds.12. You cancomplete the sorting process using a sorting function in a programming language, such as the ksort function in PHP.
The parameters in the example are sorted as follows:{'Action' : 'DescribeInstances','InstanceIds.0' : 'ins-09dx96dg','Limit' : 20,'Nonce' : 11886,'Offset' : 0,
'Region' : 'ap-guangzhou','SecretId' : 'AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******','Timestamp' : 1465185768,'Version': '2017-03-12',}©2013-2022 Tencent Cloud. All rights reserved.

Page 46 of 321

Face Recognition

When developing in another programming language, you can sort these sample parameters and it will work as long as
you obtain the same results.

2.2. Concatenating a Request String
This step generates a request string.
Format the request parameters sorted in the previous step into the form of "parameter name"="parameter value". For
example, for the Action parameter, its parameter name is "Action" and its parameter value is "DescribeInstances", so it
will become Action=DescribeInstances after formatted.
Note: The "parameter value" is the original value but not the value after URL encoding.
Then, concatenate the formatted parameters with "&". The resulting request string is as follows:

Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******&Timestamp=1465
185768&Version=2017-03-12

2.3. Concatenating the Signature Original String
This step generates a signature original string.
The signature original string consists of the following parameters:
1. HTTP method: POST and GET modes are supported, and GET is used here for the request. Please note that themethod name should be in all capital letters.
2. Request server: the domain name of the request to view the list of instances (DescribeInstances) is
cvm.tencentcloudapi.com. The actual request domain name varies by the module to which the API belongs. For
more information, see the instructions of the specific API.
3. Request path: The request path in the current version of TencentCloud API is fixed to /.
4. Request string: the request string generated in the previous step.
The concatenation rule of the signature original string is: Request method + request host + request path + ? + request
string
The concatenation result of the example is:

GETcvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&L
imit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yKBZQpn74WF
kmLPx3*******&Timestamp=1465185768&Version=2017-03-12

2.4. Generating a Signature String
This step generates a signature string.
First, use the HMAC-SHA1 algorithm to sign the signature original string obtained in the previous step, and then©2013-2022 Tencent Cloud. All rights reserved.

Page 47 of 321

Face Recognition

encode the generated signature using Base64 to obtain the final signature.
The specific code is as follows with the PHP language being used as an example:$secretKey = 'Gu5t9xGARNpq86cd98joQYCN3*******';$srcStr = 'GETcvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins-09dx96dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5
yKBZQpn74WFkmLPx3*******&Timestamp=1465185768&Version=2017-03-12';$signStr = base64_encode(hash_hmac('sha1', $srcStr, $secretKey, true));echo $signStr;
The final signature is:zmmjn35mikh6pM3V7sUEuX4wyYM=
When developing in another programming language, you can sign and verify the original in the example above and it
works as long as you get the same results.

3. Encoding a Signature String
The generated signature string cannot be directly used as a request parameter and must be URL encoded.
For example, if the signature string generated in the previous step is zmmjn35mikh6pM3V7sUEuX4wyYM=, the final
signature string request parameter (Signature) is zmmjn35mikh6pM3V7sUEuX4wyYM%3D, which will be used togenerate the final request URL.
Note: If your request method is GET, or the request method is POST and the Content-Type isapplication/x-www-form-urlencoded, then all the request parameter values need to be URL encoded(except the parameter key and the symbol of =) when sending the request. Non-ASCII characters need to
be encoded with UTF-8 before URL encoding.
Note: The network libraries of some programming languages automatically URL encode all parameters, inwhich case there is no need to URL encode the signature string; otherwise, two rounds of URL encoding
will cause the signature to fail.
Note: Other parameter values also need to be encoded using RFC 3986. Use %XY in percent-encoding forspecial characters such as Chinese characters, where "X" and "Y" are hexadecimal characters (0-9 anduppercase A-F), and using lowercase will cause an error.

4. Signature Failure©2013-2022 Tencent Cloud. All rights reserved.

Page 48 of 321

Face Recognition

The following situational error codes for signature failure may occur. Please resolve the errors accordingly.
Error code

Error description

AuthFailure.SignatureExpire

The signature is expired

AuthFailure.SecretIdNotFoundThe key does not exist

AuthFailure.SignatureFailure

Signature error

AuthFailure.TokenFailure

Token error

AuthFailure.InvalidSecretId

Invalid key (not a TencentCloud API key type)

5. Signature Demo
When calling API 3.0, you are recommended to use the corresponding Tencent Cloud SDK 3.0 which encapsulates
the signature process, enabling you to focus on only the specific APIs provided by the product when developing. See
SDK Center for more information. Currently, the following programming languages are supported:
PythonJava
PHP
Go
NodeJS.NET
To further explain the signing process, we will use a programming language to implement the process describedabove. The request domain name, API and parameter values in the sample are used here. This goal of this example isonly to provide additional clarification for the signature process, please see the SDK for actual usage.
The final output URL might be:https://cvm.tencentcloudapi.com/?Action=DescribeInstances&InstanceIds.0=ins-09dx9
6dg&Limit=20&Nonce=11886&Offset=0&Region=ap-guangzhou&SecretId=AKIDz8krbsJ5yKBZQp
n74WFkmLPx3*******&Signature=zmmjn35mikh6pM3V7sUEuX4wyYM%3D&Timestamp=1465185768&
Version=2017-03-12
Note: The key in the example is fictitious, and the timestamp is not the current time of the system, so if this URL is
opened in the browser or called using commands such as curl, an authentication error will be returned: Signature
expired. In order to get a URL that can work properly, you need to replace the SecretId and SecretKey in the example
with your real credentials and use the current time of the system as the Timestamp.

©2013-2022 Tencent Cloud. All rights reserved.

Page 49 of 321

Face Recognition

Note: In the example below, even if you use the same programming language, the order of the parameters in the URL
may be different for each execution. However, the order does not matter, as long as all the parameters are included in
the URL and the signature is calculated correctly.
Note: The following code is only applicable to API 3.0. It cannot be directly used in other signature processes. Even
with an older API, signature calculation errors may occur due to the differences in details. Please refer to thecorresponding documentation.

Java
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;import java.util.Random;
import java.util.TreeMap;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
public class TencentCloudAPIDemo {private final static String CHARSET = "UTF-8";
public static String sign(String s, String key, String method) throws Exception {Mac mac = Mac.getInstance(method);
SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(CHARSET), mac.getAlg
orithm());
mac.init(secretKeySpec);
byte[] hash = mac.doFinal(s.getBytes(CHARSET));
return DatatypeConverter.printBase64Binary(hash);}public static String getStringToSign(TreeMap<String, Object> params) {StringBuilder s2s = new StringBuilder("GETcvm.tencentcloudapi.com/?");// When signing, the parameters need to be sorted in lexicographical order. TreeM
ap is used here to guarantee the correct order.
for (String k : params.keySet()) {s2s.append(k).append("=").append(params.get(k).toString()).append("&");}
return s2s.toString().substring(0, s2s.length() - 1);}
public static String getUrl(TreeMap<String, Object> params) throws UnsupportedEnc
odingException {StringBuilder url = new StringBuilder("https://cvm.tencentcloudapi.com/?");// There is no requirement for the order of the parameters in the actual request
URL.
for (String k : params.keySet()) {// The request string needs to be URL encoded. As the Key is all in English letters, only the value is URL encoded here.
url.append(k).append("=").append(URLEncoder.encode(params.get(k).toString(), CHAR
SET)).append("&");©2013-2022 Tencent Cloud. All rights reserved.

Page 50 of 321

Face Recognition}
return url.toString().substring(0, url.length() - 1);}
public static void main(String[] args) throws Exception {TreeMap<String, Object> params = new TreeMap<String, Object>(); // TreeMap enable
s automatic sorting// A random number should be used when actually calling, for example: params.put("Nonce", new Random().nextInt(java.lang.Integer.MAX_VALUE));params.put("Nonce", 11886); // Common parameter// The current time of the system should be used when actually calling, for examp
le: params.put("Timestamp", System.currentTimeMillis() / 1000);params.put("Timestamp", 1465185768); // Common parameterparams.put("SecretId", "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"); // Common parameterparams.put("Action", "DescribeInstances"); // Common parameterparams.put("Version", "2017-03-12"); // Common parameterparams.put("Region", "ap-guangzhou"); // Common parameterparams.put("Limit", 20); // Business parameterparams.put("Offset", 0); // Business parameterparams.put("InstanceIds.0", "ins-09dx96dg"); // Business parameterparams.put("Signature", sign(getStringToSign(params), "Gu5t9xGARNpq86cd98joQYCN3*******", "HmacSHA1")); // Common parameter
System.out.println(getUrl(params));}}

PythonNote: If running in a Python 2 environment, the following requests dependency package must be installed first: pip
install requests .

# -*- coding: utf8 -*import base64
import hashlib
import hmac
import time
import requests
secret_id = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"
secret_key = "Gu5t9xGARNpq86cd98joQYCN3*******"
def get_string_to_sign(method, endpoint, params):
s = method + endpoint + "/?"
query_str = "&".join("%s=%s" % (k, params[k]) for k in sorted(params))
return s + query_str
def sign_str(key, s, method):
hmac_str = hmac.new(key.encode("utf8"), s.encode("utf8"), method).digest()
return base64.b64encode(hmac_str)©2013-2022 Tencent Cloud. All rights reserved.

Page 51 of 321

Face Recognition

if __name__ == '__main__':endpoint = "cvm.tencentcloudapi.com"
data = {'Action' : 'DescribeInstances','InstanceIds.0' : 'ins-09dx96dg','Limit' : 20,'Nonce' : 11886,'Offset' : 0,
'Region' : 'ap-guangzhou','SecretId' : secret_id,'Timestamp' : 1465185768, # int(time.time())'Version': '2017-03-12'}
s = get_string_to_sign("GET", endpoint, data)
data["Signature"] = sign_str(secret_key, s, hashlib.sha1)
print(data["Signature"])# An actual invocation would occur here, which may incur fees after success# resp = requests.get("https://" + endpoint, params=data)# print(resp.url)

Golangpackage main
import ("bytes""crypto/hmac""crypto/sha1""encoding/base64""fmt""sort")
func main() {secretId := "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"
secretKey := "Gu5t9xGARNpq86cd98joQYCN3*******"
params := map[string]string{"Nonce": "11886","Timestamp": "1465185768","Region": "ap-guangzhou","SecretId": secretId,"Version": "2017-03-12","Action": "DescribeInstances","InstanceIds.0": "ins-09dx96dg","Limit": "20","Offset": "0",}var buf bytes.Buffer©2013-2022 Tencent Cloud. All rights reserved.

Page 52 of 321

Face Recognition

buf.WriteString("GET")
buf.WriteString("cvm.tencentcloudapi.com")buf.WriteString("/")
buf.WriteString("?")// sort keys by ascii asc orderkeys := make([]string, 0, len(params))
for k, _ := range params {keys = append(keys, k)}sort.Strings(keys)
for i := range keys {k := keys[i]buf.WriteString(k)buf.WriteString("=")
buf.WriteString(params[k])buf.WriteString("&")}
buf.Truncate(buf.Len() - 1)hashed := hmac.New(sha1.New, []byte(secretKey))hashed.Write(buf.Bytes())
fmt.Println(base64.StdEncoding.EncodeToString(hashed.Sum(nil)))
}

PHP
<?php
$secretId = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******";$secretKey = "Gu5t9xGARNpq86cd98joQYCN3*******";$param["Nonce"] = 11886;//rand();$param["Timestamp"] = 1465185768;//time();$param["Region"] = "ap-guangzhou";$param["SecretId"] = $secretId;$param["Version"] = "2017-03-12";$param["Action"] = "DescribeInstances";$param["InstanceIds.0"] = "ins-09dx96dg";$param["Limit"] = 20;$param["Offset"] = 0;
ksort($param);$signStr = "GETcvm.tencentcloudapi.com/?";foreach ( $param as $key => $value ) {$signStr = $signStr . $key . "=" . $value . "&";}
$signStr = substr($signStr, 0, -1);
$signature = base64_encode(hash_hmac("sha1", $signStr, $secretKey, true));echo $signature.PHP_EOL;// need to install and enable curl extension in php.ini©2013-2022 Tencent Cloud. All rights reserved.

Page 53 of 321

Face Recognition// $param["Signature"] = $signature;// $url = "https://cvm.tencentcloudapi.com/?".http_build_query($param);// echo $url.PHP_EOL;// $ch = curl_init();// curl_setopt($ch, CURLOPT_URL, $url);// $output = curl_exec($ch);// curl_close($ch);// echo json_decode($output);Ruby# -*- coding: UTF-8 -*# require ruby>=2.3.0
require 'time'require 'openssl'
require 'base64'
secret_id = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"
secret_key = "Gu5t9xGARNpq86cd98joQYCN3*******"
method = 'GET'
endpoint = 'cvm.tencentcloudapi.com'
data = {'Action' => 'DescribeInstances','InstanceIds.0' => 'ins-09dx96dg','Limit' => 20,'Nonce' => 11886,'Offset' => 0,'Region' => 'ap-guangzhou','SecretId' => secret_id,'Timestamp' => 1465185768, # Time.now.to_i'Version' => '2017-03-12',}
sign = method + endpoint + '/?'
params = []data.sort.each do |item|
params << "#{item[0]}=#{item[1]}"endsign += params.join('&')
digest = OpenSSL::Digest.new('sha1')
data['Signature'] = Base64.encode64(OpenSSL::HMAC.digest(digest, secret_key, sign))puts data['Signature']# require 'net/http'# uri = URI('https://' + endpoint)# uri.query = URI.encode_www_form(data)# p uri©2013-2022 Tencent Cloud. All rights reserved.

Page 54 of 321

Face Recognition# res = Net::HTTP.get_response(uri)# puts res.body

DotNetusing System;
using System.Collections.Generic;using System.Net;
using System.Security.Cryptography;
using System.Text;
public class Application {public static string Sign(string signKey, string secret){string signRet = string.Empty;
using (HMACSHA1 mac = new HMACSHA1(Encoding.UTF8.GetBytes(signKey))){byte[] hash = mac.ComputeHash(Encoding.UTF8.GetBytes(secret));signRet = Convert.ToBase64String(hash);}return signRet;}
public static string MakeSignPlainText(SortedDictionary<string, string> requestParams, string requestMethod, string requestHost, string requestPath){string retStr = "";retStr += requestMethod;
retStr += requestHost;
retStr += requestPath;
retStr += "?";
string v = "";foreach (string key in requestParams.Keys){v += string.Format("{0}={1}&", key, requestParams[key]);}
retStr += v.TrimEnd('&');
return retStr;}
public static void Main(string[] args){
string SECRET_ID = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******";
string SECRET_KEY = "Gu5t9xGARNpq86cd98joQYCN3*******";
string endpoint = "cvm.tencentcloudapi.com";string region = "ap-guangzhou";string action = "DescribeInstances";
string version = "2017-03-12";
double RequestTimestamp = 1465185768;©2013-2022 Tencent Cloud. All rights reserved.

Page 55 of 321

Face Recognition// long timestamp = ToTimestamp() / 1000;// string requestTimestamp = timestamp.ToString();
Dictionary<string, string> param = new Dictionary<string, string>();param.Add("Limit", "20");param.Add("Offset", "0");param.Add("InstanceIds.0", "ins-09dx96dg");
param.Add("Action", action);param.Add("Nonce", "11886");// param.Add("Nonce", Math.Abs(new Random().Next()).ToString());
param.Add("Timestamp", RequestTimestamp.ToString());
param.Add("Version", version);param.Add("SecretId", SECRET_ID);
param.Add("Region", region);
SortedDictionary<string, string> headers = new SortedDictionary<string, string>(param, StringComparer.Ordinal);
string sigInParam = MakeSignPlainText(headers, "GET", endpoint, "/");
Console.WriteLine(sigInParam);
string sigOutParam = Sign(SECRET_KEY, sigInParam);
Console.WriteLine("GET https://cvm.tencentcloudapi.com");foreach (KeyValuePair<string, string> kv in headers){Console.WriteLine(kv.Key + ": " + kv.Value);}
Console.WriteLine("Signature" + ": " + WebUtility.UrlEncode(sigOutParam));
Console.WriteLine();string result = "https://cvm.tencentcloudapi.com/?";foreach (KeyValuePair<string, string> kv in headers){
result += WebUtility.UrlEncode(kv.Key) + "=" + WebUtility.UrlEncode(kv.Value) +"&";}result += WebUtility.UrlEncode("Signature") + "=" + WebUtility.UrlEncode(sigOutPa
ram);
Console.WriteLine("GET " + result);}}

NodeJS
const crypto = require('crypto');function get_req_url(params, endpoint){
params['Signature'] = escape(params['Signature']);const url_strParam = sort_params(params)
return "https://" + endpoint + "/?" + url_strParam.slice(1);}function formatSignString(reqMethod, endpoint, path, strParam){©2013-2022 Tencent Cloud. All rights reserved.

Page 56 of 321

Face Recognition

let strSign = reqMethod + endpoint + path + "?" + strParam.slice(1);return strSign;}function sha1(secretKey, strsign){
let signMethodMap = {'HmacSHA1': "sha1"};
let hmac = crypto.createHmac(signMethodMap['HmacSHA1'], secretKey || "");
return hmac.update(Buffer.from(strsign, 'utf8')).digest('base64')}function sort_params(params){
let strParam = "";let keys = Object.keys(params);
keys.sort();for (let k in keys) {//k = k.replace(/_/g, '.');
strParam += ("&" + keys[k] + "=" + params[keys[k]]);}return strParam}function main(){const SECRET_ID = "AKIDz8krbsJ5yKBZQpn74WFkmLPx3*******"
const SECRET_KEY = "Gu5t9xGARNpq86cd98joQYCN3*******"
const endpoint = "cvm.tencentcloudapi.com"
const Region = "ap-guangzhou"
const Version = "2017-03-12"
const Action = "DescribeInstances"
const Timestamp = 1465185768// const Timestamp = Math.round(Date.now() / 1000)
const Nonce = 11886//const nonce = Math.round(Math.random() * 65535)
let params = {};params['Action'] = Action;
params['InstanceIds.0'] = 'ins-09dx96dg';
params['Limit'] = 20;
params['Offset'] = 0;params['Nonce'] = Nonce;params['Region'] = Region;
params['SecretId'] = SECRET_ID;
params['Timestamp'] = Timestamp;
params['Version'] = Version;
strParam = sort_params(params)
const reqMethod = "GET";
const path = "/";
strSign = formatSignString(reqMethod, endpoint, path, strParam)
console.log(strSign)
console.log("-----------------------")
params['Signature'] = sha1(SECRET_KEY, strSign)
console.log(params['Signature'])©2013-2022 Tencent Cloud. All rights reserved.

Page 57 of 321

Face Recognition

console.log("-----------------------")
const req_url = get_req_url(params, endpoint)
console.log(params['Signature'])console.log("-----------------------")
console.log(req_url)}
main()©2013-2022 Tencent Cloud. All rights reserved.

Page 58 of 321

Face Recognition

Responses：

Last updated 2020-07-02 16:02:15

Response for Successful Requests
For example, when calling CAM API (version: 2017-03-12) to view the status of instances (DescribeInstancesStatus),
if the request has succeeded, you may see the response as shown below:{"Response": {"TotalCount": 0,"InstanceStatusSet": [],"RequestId": "b5b41468-520d-4192-b42f-595cc34b6c1c"}}
The API will return Response , which contains RequestId , as long as it processes the request. It does notmatter if the request is successful or not.
RequestId is the unique ID of an API request. Contact us with this ID when an exception occurs.
Except for the fixed fields, all fields are action-specified. For the definitions of action-specified fields, see thecorresponding API documentation. In this example, TotalCount and InstanceStatusSet are the fields
specified by the API DescribeInstancesStatus . 0 TotalCount means that the requester owns 0 CVM
instance so the InstanceStatusSet is empty.

Response for Failed Requests
If the request has failed, you may see the response as shown below:{"Response": {"Error": {"Code": "AuthFailure.SignatureFailure","Message": "The provided credentials could not be validated. Please ensure your signature is correct."},"RequestId": "ed93f3cb-f35e-473f-b9f3-0d451b8b79c6"}}©2013-2022 Tencent Cloud. All rights reserved.

Page 59 of 321

Face Recognition

The presence of the Error field indicates that the request has failed. A response for a failed request will include
Error , Code and Message fields.
Code is the code of the error that helps you identify the cause and solution. There are two types of error codes
so you may find the code in either common error codes or API-specified error codes.
Message explains the cause of the error. Note that the returned messages are subject to service updates. The
information the messages provide may not be up-to-date and should not be the only source of reference.
RequestId is the unique ID of an API request. Contact us with this ID when an exception occurs.

Common Error Codes
If there is an Error field in the response, it means that the API call failed. The Code field in Error indicates the error
code. The following table lists the common error codes that all actions can return.
Error CodeDescription

AuthFailure.InvalidSecretId

Invalid key (not a TencentCloud API key type).

AuthFailure.MFAFailure

MFA failed.

AuthFailure.SecretIdNotFoundThe key does not exist.

AuthFailure.SignatureExpire

Signature expired.

AuthFailure.SignatureFailure

Signature error.

AuthFailure.TokenFailure

Token error.

AuthFailure.UnauthorizedOperation

The request does not have CAM authorization.

DryRunOperation

DryRun Operation. It means that the request would have succeeded, but
the DryRun parameter was used.

FailedOperation

Operation failed.

InternalError

Internal error.

InvalidAction

The API does not exist.

InvalidParameter

Incorrect parameter.

InvalidParameterValue

Invalid parameter value.

LimitExceeded

Quota limit exceeded.

©2013-2022 Tencent Cloud. All rights reserved.

Page 60 of 321

Face Recognition

Error CodeDescription

MissingParameter

A parameter is missing.

NoSuchVersion

The API version does not exist.

RequestLimitExceeded

The number of requests exceeds the frequency limit.

ResourceInUse

Resource is in use.

ResourceInsufficientInsufficient resource.

ResourceNotFoundThe resource does not exist.

ResourceUnavailable

Resource is unavailable.

UnauthorizedOperation

Unauthorized operation.

UnknownParameter

Unknown parameter.

UnsupportedOperation

Unsupported operation.

UnsupportedProtocol

HTTPS request method error. Only GET and POST requests aresupported.

UnsupportedRegion

API does not support the requested region.

©2013-2022 Tencent Cloud. All rights reserved.

Page 61 of 321

Face Recognition

Face Detection and Analysis APIs
DetectFace：

Last updated 2023-02-27 15:22:53

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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, andpose (pitch, roll, yaw); and the face quality information includes the overall quality score, sharpness, brightness, andcompleteness.
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 ofsubsequent processing. Application scenarios of this feature include:
1. Creating/Adding a person in a group: this is to ensure the quality of the face information to facilitate subsequent
processing.
2. Face search: this is to ensure the quality of the input image to quickly find the corresponding person.
3. Face verification: 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 .
We recommend you to use API Explorer
Try itAPI 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.

©2013-2022 Tencent Cloud. All rights reserved.

Page 62 of 321

Face Recognition

2. Input Parameters
The following request parameter list only provides API request parameters and some common parameters. For thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: DetectFace.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

IntegerMaximum number of processable faces. Default value: 1 (i.e.,
detecting only the face with the largest size in the image).
Maximum value: 120.
This parameter is used to control the number of faces in theimage to be detected. The smaller the value, the faster theprocessing.

MaxFaceNum

MinFaceSize

No

No

Integer

Minimum height and width of face in px.
Default value: 34. We recommend keeping it at or above 34.
Faces below the MinFaceSize value will not be
detected.

Image

No

StringBase64-encoded image data, which cannot exceed 5 MB.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
PNG, JPG, JPEG, and BMP images are supported, while
GIF images are not.
Image URL. The image cannot exceed 5 MB in size after
being Base64-encoded.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Either Url or Image must be provided; if both areprovided, only Url will be used.

Url

No

StringWe recommend storing the image in Tencent Cloud, as aTencent Cloud URL can guarantee higher download speed
and stability.
The download speed and stability of non-Tencent Cloud
URLs may be low.
PNG, JPG, JPEG, and BMP images are supported, while
GIF images are not.

NeedFaceAttributes

No

Integer

Whether the face attribute information (FaceAttributesInfo)©2013-2022 Tencent Cloud. All rights reserved.

Page 63 of 321

Face Recognitionneeds to be returned. 0: no; 1: yes. Default value: 0.
If the value is not 1, it will be deemed as no need to return,and FaceAttributesInfo is meaningless in this case.
The face attribute information of up to 5 largest faces in theimage will be returned, and FaceAttributesInfo of
the 6th and rest faces is meaningless.
Extracting face attribute information is quite time-consuming.
If face attribute information is not required, we recommend
disabling this feature to speed up face detection.

NeedQualityDetection

No

Integer

Whether to enable quality detection. 0: no; 1: yes. Default
value: 0.
If the value is not 1, it will be deemed not to perform quality
detection.
The face quality score information of up to 30 largest faces in
the image will be returned, and FaceQualityInfo of the
31st and rest faces is meaningless.
We recommend enabling this feature for the face adding
operation.
Algorithm model version used by the Face Recognition
service.
Currently, 2.0 and 3.0 are supported.
This parameter is 3.0 by default starting from April 2,
2020. If it is left empty for accounts that used this API, 2.0

FaceModelVersion

No

Stringwill be used by default.
The parameter can be set only to 3.0 for accounts thatpurchase the service after November 26, 2020.
Different algorithm model versions correspond to different
face recognition algorithms. The 3.0 version has a betteroverall effect than the legacy version and is recommended.
Whether to enable the support for rotated image recognition.

NeedRotateDetection

No

Integer©2013-2022 Tencent Cloud. All rights reserved.

0: no; 1: yes. Default value: 0. When the face in the image isrotated and the image has no EXIF information, if thisparameter is not enabled, the face in the image cannot becorrectly detected and recognized. If you are sure that the
input image contains EXIF information or the face in theimage will not be rotated, do not enable this parameter, as
the overall time consumption may increase by hundreds ofmilliseconds after it is enabled.

Page 64 of 321

Face Recognition

3. Output Parameters
Parameter NameType

Description

ImageWidthInteger

Width of requested image.

ImageHeight

Integer

Height of requested image.

FaceInfos

Array of
FaceInfo

Face information list, including face coordinate information, attributeinformation (if needed), and quality score information (if needed).

FaceModelVersion

StringAlgorithm model version used for face recognition.

RequestId

String

The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

4. Example
Example1 Detecting and analyzing faces
Input Example
https://iai.tencentcloudapi.com/?Action=DetectFace&MaxFaceNum=1&MinFaceSize=40&Url=http://test.image.myqcloud.com/testB.jpg&NeedFaceAttributes=0&NeedQualityDetection=0&<Common request parameters>

Output Example{"Response": {"ImageWidth": 640,
"ImageHeight": 440,
"FaceInfos": [{"X": 156,"Y": 129,"Width": 196,
"Height": 196,
"FaceAttributesInfo": {©2013-2022 Tencent Cloud. All rights reserved.

Page 65 of 321

Face Recognition"Gender": 0,"Age": 0,"Expression": 0,"Hat": false,"Glass": false,"EyeOpen": true,"Mask": false,"Hair": {"Length": 0,"Bang": 0,"Color": 0},"Pitch": 0,"Yaw": 0,"Roll": 0,"Beauty": 0},"FaceQualityInfo": {"Score": 0,"Sharpness": 0,"Brightness": 0,"Completeness": {"Eyebrow": 0,"Eye": 0,"Nose": 0,"Cheek": 0,"Mouth": 0,"Chin": 0}}}],"FaceModelVersion": "3.0","RequestId": "a574102d-1b86-48a7-a08b-6a741a8fedb6"}}

Example2 Detecting and analyzing faces - 2
Input Example
https://iai.tencentcloudapi.com/?Action=DetectFace&MaxFaceNum=1&MinFaceSize=40&Url=http://test.image.myqcloud.com/testA.jpg&NeedFaceAttributes=1©2013-2022 Tencent Cloud. All rights reserved.

Page 66 of 321

Face Recognition&NeedQualityDetection=1&<Common request parameters>

Output Example{"Response": {"ImageWidth": 640,
"ImageHeight": 440,
"FaceInfos": [{"X": 156,"Y": 129,"Width": 196,
"Height": 196,
"FaceAttributesInfo": {"Gender": 99,"Age": 51,"Expression": 99,"Hat": false,"Glass": false,"EyeOpen": true,"Mask": true,"Hair": {"Length": 1,"Bang": 1,"Color": 0},"Pitch": 17,"Yaw": 5,"Roll": -2,"Beauty": 71},"FaceQualityInfo": {"Score": 63,"Sharpness": 73,"Brightness": 47,"Completeness": {"Eyebrow": 99,"Eye": 99,"Nose": 99,"Cheek": 52,"Mouth": 99,"Chin": 47}}©2013-2022 Tencent Cloud. All rights reserved.

Page 67 of 321

Face Recognition}],"FaceModelVersion": "3.0","RequestId": "bcde47b5-e6d8-446e-a538-bcecffbe306a"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

AuthFailure.InvalidAuthorization

Authentication failed.

FailedOperation

Operation failed.

FailedOperation.ConflictOperation

The operations conflict. Do not operate on thesame person simultaneously.

FailedOperation.DuplicatedGroupDescription©2013-2022 Tencent Cloud. All rights reserved.

The custom description field must be unique inthe group.

Page 68 of 321

Face Recognition

FailedOperation.FaceSizeTooSmall

The face frame size is smaller than the
MinFaceSize value, and the face is filtered
out.

FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist

The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

FailedOperation.ImageResolutionTooSmall

The image short edge resolution is smaller than64.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

FailedOperation.UnKnowError

An internal error occurred.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.

InvalidParameterValue.DeleteFaceNumExceed

The number of faces to be deleted exceeds thelimit. Every person must have at least one face
image.

©2013-2022 Tencent Cloud. All rights reserved.

Page 69 of 321

Face Recognition

InvalidParameterValue.FaceModelVersionIllegal

The algorithm model version is invalid.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.

InvalidParameterValue.GroupExDescriptionsNameIllegal

The name of the group's custom description
field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

The name of the group's custom description
field exceeds the length limit.

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.GroupNameTooLong

The group name exceeds the length limit.

InvalidParameterValue.GroupNumExceed

The number of groups exceeds the limit. If you
need more, please contact us.

InvalidParameterValue.GroupNumPerPersonExceed

The number of groups exceeds the limit. One
person can be added to up to 100 groups.

InvalidParameterValue.GroupTagIllegal

The group remarks field contains invalidcharacters. It can contain only letters, - ,_ , and digits.

©2013-2022 Tencent Cloud. All rights reserved.

Page 70 of 321

Face Recognition

InvalidParameterValue.GroupTagTooLong

The group remarks field exceeds the length
limit.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.LimitExceed

The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.

InvalidParameterValue.PersonExDescriptionInfosExceed

The array length of the person's custom
description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdentical

The name of the person's custom description
field must be unique.

InvalidParameterValue.PersonExDescriptionsNameIllegal

The name of the person's custom description
field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

The name of the person's custom description
field exceeds the length limit.

InvalidParameterValue.PersonExistInGroupThe ID of the corresponding person is alreadyin the group.

InvalidParameterValue.PersonFaceNumExceed

The number of face images for the person
exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.

InvalidParameterValue.PersonIdAlreadyExist

The person ID already exists. It must be unique.

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

©2013-2022 Tencent Cloud. All rights reserved.

Page 71 of 321

Face Recognition

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.LowBalanceInsufficient balance.

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

ResourceUnavailable.Recover

The resource has been repossessed.

ResourceUnavailable.StopUsing

The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 72 of 321

Face Recognition

DetectFaceAttributes：

Last updated 2023-02-27 15:22:53

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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, andpose (pitch, roll, yaw); and the face quality information includes the overall quality score, sharpness, brightness, andcompleteness.
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 ofsubsequent processing. Application scenarios of this feature include:
1. Creating/Adding a person in a group: This is to ensure the quality of the face information to facilitate subsequent
processing.
2. Face search: This is to ensure the quality of the input image to quickly find the corresponding person.
3. Face verification: This is to ensure the quality of the face information to avoid cases where the verification fails
unexpectedly.
4. Face fusion: This is to ensure the quality of the uploaded face images to improve the fusion effect.

This API is an upgrade of DetectFace; specifically:
1. This API can be used to specify the face attributes that need to be computed and returned, which avoids ineffective
computation and reduces time consumption.
2. This API supports more detailed attribute items and will continue providing new features in the future.
Use this API for corresponding face detection and attribute analysis.

©2013-2022 Tencent Cloud. All rights reserved.

Page 73 of 321

Face Recognition

Use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the parameter
SignatureMethod to TC3-HMAC-SHA256 .
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

ActionYes

String

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

IntegerMaximum number of processable faces.
Default value: 1 (i.e., detecting only the face with the largest
size in the image). Maximum value: 120.
This parameter is used to control the number of faces in theimage to be detected. The smaller the value, the faster theprocessing.
Base64-encoded image data, which cannot exceed 5 MB.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.

MaxFaceNum

No

Image

No

StringUrl

No

StringDescription
Common Params. The value used for this API:
DetectFaceAttributes.

Image URL.
The image cannot exceed 5 MB in size after being Base64encoded.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Either Url or Image must be provided; if both areprovided, only Url will be used.
We recommend storing the image in Tencent Cloud, as a©2013-2022 Tencent Cloud. All rights reserved.

Page 74 of 321

Face Recognition

Tencent Cloud URL can guarantee higher download speed
and stability.
The download speed and stability of non-Tencent Cloud
URLs may be low.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
Whether to return attributes such as age, gender, andemotion.
Valid values (case-insensitive): None, Age, Beauty, Emotion,
Eye, Eyebrow, Gender, Hair, Hat, Headpose, Mask, Mouth,
Moustache, Nose, Shape, Skin, Smile.
None indicates that no attributes need to be returned,
FaceAttributesType

No

Stringwhich is the default value; that is, if the
FaceAttributesType attribute is empty, the values of
all attributes will be 0 .
You need to combine the attributes into a string and separate
them by comma. The sequence of the attributes is not limited.
For more information on the attributes, see the output
parameters as described below.
The face attribute information of up to 5 largest faces in theimage will be returned, and AttributesInfo of the 6th
and rest faces is meaningless.

NeedRotateDetection

No

Integer

Whether to enable the support for rotated image recognition.
0: no; 1: yes. Default value: 0. When the face in the image isrotated and the image has no EXIF information, if thisparameter is not enabled, the face in the image cannot becorrectly detected and recognized. If you are sure that the
input image contains EXIF information or the face in theimage is not rotated, do not enable this parameter, as theoverall time consumption may increase by hundreds ofmilliseconds after it is enabled.

FaceModelVersion

No

StringAlgorithm model version used by the Face Recognition
service. You can enter only 3.0 for this API.

3. Output Parameters
Parameter NameType

Description

ImageWidthInteger

Width of requested image.

©2013-2022 Tencent Cloud. All rights reserved.

Page 75 of 321

Face Recognition

ImageHeight

Integer

Height of requested image.

FaceDetailInfos

Array of
FaceDetailInfo

Face information list.

FaceModelVersion

StringAlgorithm model version used for face recognition.

RequestId

String

The unique request ID, which is returned for each request. RequestId
is required for locating a problem.

4. Example
Example1 Detecting faces and analyzing attributes
Input Example
POST / HTTP/1.1
Host: iai.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DetectFaceAttributes<Common request parameters>{"Url": "http://test.image.myqcloud.com/testA.jpg","FaceAttributesType": "eye"}Output Example{"Response": {"ImageWidth": 550,
"ImageHeight": 366,
"FaceModelVersion": "3.0","FaceDetailInfos": [{"FaceRect": {"X": 375,"Y": 37,"Width": 63,"Height": 82},"FaceDetailAttributesInfo": {"Age": 0,©2013-2022 Tencent Cloud. All rights reserved.

Page 76 of 321

Face Recognition"Beauty": 0,"Emotion": {"Type": 0,"Probability": 0},"Eye": {"Glass": {"Type": 0,"Probability": 0.99936753511429},"EyeOpen": {"Type": 0,"Probability": 0.99949336051941},"EyelidType": {"Type": 1,"Probability": 0.75467920303345},"EyeSize": {"Type": 2,"Probability": 0.59152442216873}},"Eyebrow": {"EyebrowDensity": {"Type": 0,"Probability": 0},"EyebrowCurve": {"Type": 0,"Probability": 0},"EyebrowLength": {"Type": 0,"Probability": 0}},"Gender": {"Type": 0,"Probability": 0},"Hair": {"Length": {"Type": 0,"Probability": 0},"Bang": {©2013-2022 Tencent Cloud. All rights reserved.

Page 77 of 321

Face Recognition"Type": 0,"Probability": 0},"Color": {"Type": 0,"Probability": 0}},"Hat": {"Style": {"Type": 0,"Probability": 0},"Color": {"Type": 0,"Probability": 0}},"HeadPose": {"Pitch": 0,"Yaw": 0,"Roll": 0},"Mask": {"Type": 0,"Probability": 0},"Mouth": {"MouthOpen": {"Type": 0,"Probability": 0}},"Moustache": {"Type": 0,"Probability": 0},"Nose": {"Type": 2,"Probability": 0.75233882665634},"Shape": {"Type": 0,"Probability": 0},"Skin": {"Type": 0,©2013-2022 Tencent Cloud. All rights reserved.

Page 78 of 321

Face Recognition"Probability": 0},"Smile": 0}}],"RequestId": "b2c154b9-4620-4d37-8fd1-f6af3748f998"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

AuthFailure.InvalidAuthorization

Authentication failed.

FailedOperation.FaceSizeTooSmall©2013-2022 Tencent Cloud. All rights reserved.

The face frame size is smaller than the MinFaceSize
value, and the face is filtered out.

Page 79 of 321

Face Recognition

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

FailedOperation.ImageResolutionTooSmall

The image short edge resolution is smaller than 64.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot exceed 5
MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.RpcFail

The RPC call failed.

FailedOperation.ServerError

The algorithm service is exceptional. Please retry.

FailedOperation.UnKnowError

An internal error occurred.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.FaceModelVersionIllegal

The algorithm model version is invalid.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.NotExist

The billing status is unknown. Please check whether theservice has been activated in the console.

ResourceUnavailable.Recover

The resource has been repossessed.

ResourceUnavailable.StopUsing

The service has been suspended for the account.

©2013-2022 Tencent Cloud. All rights reserved.

Page 80 of 321

Face Recognition

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 81 of 321

Face Recognition

Facial Feature Localization APIs
AnalyzeFace：

Last updated 2023-02-27 15:22:51

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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), andeyeballs 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 .
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: AnalyzeFace.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

Mode

No

Integer

Detection mode. 0: detect all faces that appear; 1: detect the©2013-2022 Tencent Cloud. All rights reserved.

Page 82 of 321

Face Recognition

largest face. Default value: 0. The facial feature localization
information (facial keypoints) of up to 10 faces can be
returned.

Image

No

StringBase64-encoded image data, which cannot exceed 5 MB.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
Image URL. The image cannot exceed 5 MB in size after
being Base64-encoded.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Either Url or Image must be provided; if both areprovided, only Url will be used.

Url

No

StringWe recommend storing the image in Tencent Cloud, as aTencent Cloud URL can guarantee higher download speed
and stability.
The download speed and stability of non-Tencent Cloud
URLs may be low.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
Algorithm model version used by the Face Recognition
service.
Currently, 2.0 and 3.0 are supported.
This parameter is 3.0 by default starting from April 2,
2020. If it is left empty for accounts that used this API, 2.0

FaceModelVersion

No

Stringwill be used by default.
The parameter can be set only to 3.0 for accounts thatpurchase the service after November 26, 2020.
Different algorithm model versions correspond to different
face recognition algorithms. The 3.0 version has a betteroverall effect than the legacy version and is recommended.

NeedRotateDetection

No

Integer©2013-2022 Tencent Cloud. All rights reserved.

Whether to enable the support for rotated image recognition.
0: no; 1: yes. Default value: 0. When the face in the image isrotated and the image has no EXIF information, if thisparameter is not enabled, the face in the image cannot becorrectly detected and recognized. If you are sure that the
input image contains EXIF information or the face in the

Page 83 of 321

Face Recognition

image will not be rotated, do not enable this parameter, as theoverall time consumption may increase by hundreds ofmilliseconds after it is enabled.

3. Output Parameters
Parameter NameType

Description

ImageWidthInteger

Width of requested image.

ImageHeight

Integer

Height of requested image.

FaceShapeSet

Array of
FaceShape

Specific information of facial feature localization (facial keypoints).

FaceModelVersion

StringAlgorithm model version used for face recognition.

RequestId

String

The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

4. Example
Example1 Performing facial feature localization
Input Example
https://iai.tencentcloudapi.com/?Action=AnalyzeFace&Mode=0&Url=http://test.image.myqcloud.com/testA.jpg&<Common request parameters>

Output Example{"Response": {"ImageWidth": 550,
"ImageHeight": 366,
"FaceShapeSet":[{"FaceProfile": [{"X": 63,©2013-2022 Tencent Cloud. All rights reserved.

Page 84 of 321

Face Recognition"Y": 335},{"X": 63,"Y": 374},{
0"X": 66,
"Y": 412},{"X": 74,"Y": 450},{"X": 85,"Y": 487},{"X": 100,"Y": 522},{"X": 121,"Y": 554},{"X": 147,"Y": 582},{"X": 176,"Y": 608},{"X": 208,"Y": 627},{"X": 245,"Y": 634},{"X": 282,"Y": 627},{©2013-2022 Tencent Cloud. All rights reserved.

Page 85 of 321

Face Recognition"X": 315,"Y": 607},{"X": 344,"Y": 582},{"X": 370,"Y": 554},{"X": 391,"Y": 522},{"X": 405,"Y": 487},{"X": 416,"Y": 449},{"X": 423,"Y": 411},{"X": 427,"Y": 372},{"X": 426,"Y": 334}],"LeftEye": [{"X": 114,"Y": 333},{"X": 128,"Y": 345},{"X": 146,©2013-2022 Tencent Cloud. All rights reserved.

Page 86 of 321

Face Recognition"Y": 349},{"X": 165,"Y": 347},{"X": 183,"Y": 341},{"X": 169,"Y": 325},{"X": 150,"Y": 318},{"X": 130,"Y": 321}],"RightEye": [{"X": 378,"Y": 331},{"X": 364,"Y": 343},{"X": 345,"Y": 348},{"X": 327,"Y": 346},{"X": 309,"Y": 340},{"X": 322,"Y": 323©2013-2022 Tencent Cloud. All rights reserved.

Page 87 of 321

Face Recognition},{"X": 341,"Y": 316},{"X": 361,"Y": 319}],"LeftEyeBrow": [{"X": 79,"Y": 280},{"X": 108,"Y": 275},{"X": 138,"Y": 274},{"X": 168,"Y": 277},{"X": 198,"Y": 279},{"X": 173,"Y": 256},{"X": 139,"Y": 251},{"X": 105,"Y": 256}],"RightEyeBrow": [{"X": 410,©2013-2022 Tencent Cloud. All rights reserved.

Page 88 of 321

Face Recognition"Y": 277},{"X": 380,"Y": 273},{"X": 350,"Y": 272},{"X": 320,"Y": 275},{"X": 290,"Y": 277},{"X": 315,"Y": 255},{"X": 349,"Y": 249},{"X": 384,"Y": 254}],"Mouth": [{"X": 173,"Y": 522},{"X": 193,"Y": 541},{"X": 217,"Y": 554},{"X": 244,"Y": 558©2013-2022 Tencent Cloud. All rights reserved.

Page 89 of 321

Face Recognition},{"X": 272,"Y": 554},{"X": 297,"Y": 541},{"X": 317,"Y": 522},{"X": 291,"Y": 517},{"X": 264,"Y": 512},{"X": 245,"Y": 517},{"X": 225,"Y": 512},{"X": 199,"Y": 517},{"X": 196,"Y": 528},{"X": 220,"Y": 532},{"X": 244,"Y": 535},{"X": 269,©2013-2022 Tencent Cloud. All rights reserved.

Page 90 of 321

Face Recognition"Y": 532},{"X": 293,"Y": 528},{"X": 293,"Y": 525},{"X": 269,"Y": 527},{"X": 245,"Y": 530},{"X": 221,"Y": 528},{"X": 197,"Y": 525}],"Nose": [{"X": 244,"Y": 428},{"X": 245,"Y": 341},{"X": 231,"Y": 367},{"X": 217,"Y": 392},{"X": 203,"Y": 418©2013-2022 Tencent Cloud. All rights reserved.

Page 91 of 321

Face Recognition},{"X": 187,"Y": 448},{"X": 217,"Y": 464},{"X": 245,"Y": 468},{"X": 272,"Y": 464},{"X": 302,"Y": 448},{"X": 287,"Y": 417},{"X": 273,"Y": 392},{"X": 259,"Y": 366}],"LeftPupil": [{"X": 188,"Y": 303}],"RightPupil": [{"X": 201,"Y": 304}]}©2013-2022 Tencent Cloud. All rights reserved.

Page 92 of 321

Face Recognition],"FaceModelVersion": "3.0","RequestId": "a8eb4545-a154-4f86-9510-57a8be9cae0c"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

AuthFailure.InvalidAuthorization

Authentication failed.

FailedOperation.ConflictOperation

The operations conflict. Do not operate on thesame person simultaneously.

FailedOperation.DuplicatedGroupDescription

The custom description field must be unique inthe group.

FailedOperation.FaceSizeTooSmall

The face frame size is smaller than the
MinFaceSize value, and the face is filtered©2013-2022 Tencent Cloud. All rights reserved.

Page 93 of 321

Face Recognition

out.
FailedOperation.GroupInDeletedStateThe current group is being deleted. Please wait.

FailedOperation.GroupPersonMapExist

The ID of the corresponding person is alreadyin the group.

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

FailedOperation.ImageResolutionTooSmall

FailedOperation.ImageSizeExceed
FailedOperation.RequestTimeout
FailedOperation.SearchFacesExceed

The image short edge resolution is smaller than64.
The size of the Base64-encoded image cannot
exceed 5 MB.
The backend service timed out.
The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

FailedOperation.UnKnowError

An internal error occurred.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.

InvalidParameterValue.FaceModelVersionIllegal

The algorithm model version is invalid.

InvalidParameterValue.GroupExDescriptionsExceed

The array length of the group's custom
description fields exceeds the limit. Up to 5

©2013-2022 Tencent Cloud. All rights reserved.

Page 94 of 321

Face Recognition

fields can be created.
InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

field contains invalid characters. It can contain
only letters, - , _ , and digits.
The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.GroupNameTooLong

The group name exceeds the length limit.

InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalid

InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong©2013-2022 Tencent Cloud. All rights reserved.

The group remarks field exceeds the length
limit.

Page 95 of 321

Face Recognition

InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

InvalidParameterValue.PersonExDescriptionInfosExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom
description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdenticalInvalidParameterValue.PersonExDescriptionsNameIllegal

The name of the person's custom description
field must be unique.
The name of the person's custom description
field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroup

InvalidParameterValue.PersonFaceNumExceed

The name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person
exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.

InvalidParameterValue.PersonIdAlreadyExist

The person ID already exists. It must be unique.

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal©2013-2022 Tencent Cloud. All rights reserved.

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

Page 96 of 321

Face Recognition

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.Recover

The resource has been repossessed.

ResourceUnavailable.StopUsing

The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 97 of 321

Face Recognition

Face Comparison APIs
CompareFace：

Last updated 2023-02-27 15:22:54

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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
or VerifyPerson 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 .
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: CompareFace.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

ImageANo

StringBase64-encoded data of image A, which cannot exceed 5©2013-2022 Tencent Cloud. All rights reserved.

Page 98 of 321

Face RecognitionMB.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
If there are multiple faces in the image, only the face with thelargest size will be selected.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
Base64-encoded data of image B, which cannot exceed 5
MB.

ImageBNo

String

The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
If there are multiple faces in the image, only the face with thelargest size will be selected.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
URL of image A. The image cannot exceed 5 MB in size after
being Base64-encoded.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Either Url or Image of image A must be provided; ifboth are provided, only Url will be used.
We recommend storing the image in Tencent Cloud, as a

UrlA

No

StringTencent Cloud URL can guarantee higher download speed
and stability.
The download speed and stability of non-Tencent Cloud
URLs may be low.
If there are multiple faces in the image, only the face with thelargest size will be selected.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.

UrlB

No

String

URL of image B. The image cannot exceed 5 MB in size after
being Base64-encoded.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Either Url or Image of image B must be provided; ifboth are provided, only Url will be used.
We recommend storing the image in Tencent Cloud, as aTencent Cloud URL can guarantee higher download speed
and stability.
The download speed and stability of non-Tencent Cloud
URLs may be low.
If there are multiple faces in the image, only the face with thelargest size will be selected.

©2013-2022 Tencent Cloud. All rights reserved.

Page 99 of 321

Face Recognition

PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
Algorithm model version used by the Face Recognition
service.
Currently, 2.0 and 3.0 are supported.
This parameter is 3.0 by default starting from April 2,
2020. If it is left empty for accounts that used this API, 2.0
FaceModelVersion

No

Stringwill be used by default.
The parameter can be set only to 3.0 for accounts thatpurchase the service after November 26, 2020.
Different algorithm model versions correspond to different
face recognition algorithms. The 3.0 version has a betteroverall effect than the legacy version and is recommended.
Image quality control.
0: no control.
1: low quality requirement. The image has one or more of thefollowing problems: extreme blurriness, covered eyes,covered nose, and covered mouth.
2: average quality requirement. The image has at least threeof the following problems: excessive brightness, excessive
dimness, blurriness or average blurriness, covered eyebrows,
covered cheeks, and covered chin.

QualityControl

No

Integer

3: high-quality requirement. The image has one to two of thefollowing problems: excessive brightness, excessive dimness,average blurriness, covered eyebrows, covered cheeks, andcovered chin.
4: very high-quality requirement. The image is optimal in all
dimensions or only has a slight problem in one dimension.
Default value: 0.
If the image quality does not meet the requirement, thereturned result will prompt that the detected image quality is
unsatisfactory.

NeedRotateDetection

No

Integer

Whether to enable the support for rotated image recognition.
0: no; 1: yes. Default value: 0. When the face in the image isrotated and the image has no EXIF information, if thisparameter is not enabled, the face in the image cannot becorrectly detected and recognized. If you are sure that the
input image contains EXIF information or the face in theimage will not be rotated, do not enable this parameter, as the©2013-2022 Tencent Cloud. All rights reserved.

Page 100 of 321

Face Recognition

overall time consumption may increase by hundreds ofmilliseconds after it is enabled.

3. Output Parameters
Parameter NameType

Description
Face similarity score between two images.
The returned similarity score varies by algorithm version.
If you need to verify whether the faces in the two images are the same person,then the 0.1%, 0.01%, and 0.001% FARs on v3.0 correspond to scores of 40,
50, and 60, respectively. Generally, if the score is above 50, it can be judged

Score

Float

that they are the same person.
The 0.1%, 0.01%, and 0.001% FARs on v2.0 correspond to scores of 70, 80,
and 90, respectively. Generally, if the score is above 80, it can be judged thatthey are the same person.
If you need to verify whether the faces in the two images are the same person,
we recommend using the VerifyFace API.

FaceModelVersion

StringAlgorithm model version used for face recognition.

RequestId

String

The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

4. Example
Example1 Comparing faces
Input Example
POST / HTTP/1.1
Host: iai.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CompareFace<Common request parameters>{"UrlA": "http://test.image.myqcloud.com/testA.jpg","UrlB": "http://test.image.myqcloud.com/testB.jpg"}©2013-2022 Tencent Cloud. All rights reserved.

Page 101 of 321

Face Recognition

Output Example{"Response": {"Score": 0.999,"FaceModelVersion": "3.0","RequestId": "a8eb4545-a154-4f86-9510-57a8be9cae0c"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

AuthFailure.InvalidAuthorization

Authentication failed.

FailedOperation.ConflictOperation

The operations conflict. Do not operate on thesame person simultaneously.

©2013-2022 Tencent Cloud. All rights reserved.

Page 102 of 321

Face Recognition

FailedOperation.DuplicatedGroupDescription

The custom description field must be unique inthe group.

FailedOperation.FaceQualityNotQualified

FailedOperation.FaceSizeTooSmall

The face image quality does not meet therequirement.
The face frame size is smaller than the
MinFaceSize value, and the face is filtered
out.

FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist

FailedOperation.GroupPersonMapNotExist

The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.
The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

FailedOperation.ImageResolutionTooSmall

The image short edge resolution is smaller than64.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.RpcFail

The RPC call failed.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

FailedOperation.UnKnowError

An internal error occurred.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds the©2013-2022 Tencent Cloud. All rights reserved.

Page 103 of 321

Face Recognition

limit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.

InvalidParameterValue.FaceModelVersionIllegal

The algorithm model version is invalid.

InvalidParameterValue.GroupExDescriptionsExceed

The array length of the group's custom
description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdenticalInvalidParameterValue.GroupExDescriptionsNameIllegal

The name of the group's custom description
field must be unique.
The name of the group's custom description
field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

The name of the group's custom description
field exceeds the length limit.

InvalidParameterValue.GroupFaceNumExceed

The number of faces in the group exceeds thelimit.

InvalidParameterValue.GroupIdAlreadyExist

The group ID already exists. It must be unique.

InvalidParameterValue.GroupIdIllegal

The group ID contains invalid characters. It cancontain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.GroupNameTooLong

The group name exceeds the length limit.

InvalidParameterValue.GroupNumExceed

The number of groups exceeds the limit. If you
need more, please contact us.

©2013-2022 Tencent Cloud. All rights reserved.

Page 104 of 321

Face Recognition

InvalidParameterValue.GroupNumPerPersonExceed

The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalid

InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong

The group remarks field exceeds the length
limit.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.LimitExceed

The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

InvalidParameterValue.PersonExDescriptionInfosExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom
description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdenticalInvalidParameterValue.PersonExDescriptionsNameIllegal

The name of the person's custom description
field must be unique.
The name of the person's custom description
field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroup

InvalidParameterValue.PersonFaceNumExceed

The name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person
exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.

InvalidParameterValue.PersonIdAlreadyExist

The person ID already exists. It must be unique.

©2013-2022 Tencent Cloud. All rights reserved.

Page 105 of 321

Face Recognition

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.QualityControlIllegal

Invalid QualityControl parameter.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.LowBalanceInsufficient balance.

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 106 of 321

Face Recognition

Group Management APIs
CreateGroup：

Last updated 2023-02-27 15:22:50

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: CreateGroup.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringGroupName

Yes

StringGroupId

Yes

String©2013-2022 Tencent Cloud. All rights reserved.

Common Params. This parameter is not required for thisAPI.
Group name, which is modifiable, must be unique, and cancontain 1 to 60 characters.
Group ID, which is unmodifiable, must be unique, and cancontain letters, digits, and special symbols (-%@#&_) of up

Page 107 of 321

Face Recognition

to 64 B.
Custom group description field that describes the person
attributes in the group, which will be applied to all persons in
the group.
Up to 5 ones can be created.

GroupExDescriptions.N

No

Array

Each custom description field can contain 1 to 30
characters.

ofString

The custom description field must be unique in the group.
Example: if you set the "custom description field" of a groupto ["student ID","employee ID","mobile number"],then all the persons in the group will have description fields
named "student ID", "employee ID", and "mobile number".
You can enter content in the corresponding field to register aperson's student ID, employee ID, and mobile number.

Tag

No

StringGroup remarks, which can contain 0 to 40 characters.
Algorithm model version used by the Face Recognition
service.
Currently, 2.0 and 3.0 are supported.
This parameter is 3.0 by default starting from April 2,
2020. If it is left empty for accounts that used this API,

FaceModelVersion

No

String

2.0 will be used by default.
The parameter can be set only to 3.0 for accounts thatpurchase the service after November 26, 2020.
Different algorithm model versions correspond to different
face recognition algorithms. The 3.0 version has a betteroverall effect than the legacy version and is recommended.

3. Output Parameters
Parameter NameType

Description

FaceModelVersion

StringAlgorithm model version used for face recognition.

RequestId

String

The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

©2013-2022 Tencent Cloud. All rights reserved.

Page 108 of 321

Face Recognition

4. Example
Example1 Creating group
This example shows you how to create groups.
Input Example
https://iai.tencentcloudapi.com/?Action=CreateGroup&GroupName=Tencent Shenzhen Employee Group&FaceModelVersion=3.0&GroupId=TencentShenZhenEmployee&Tag=Excludes interns&GroupExDescriptions.0=Business Group&GroupExDescriptions.1=Department name&GroupExDescriptions.2=Group name&<Common request parameters>

Output Example{"Response": {"FaceModelVersion": "3.0","RequestId": "e53ee4ec-9099-4b35-a129-21dd4820ff85"}}

Example2 Creating group - 2
Input Example
https://iai.tencentcloudapi.com/?Action=CreateGroup&GroupName=Building 1, Zhuyuan Dormitory of XXX University&GroupId=ZhuYuanDormitoryNo1&FaceModelVersion=3.0&Tag=All are girls&GroupExDescriptions.0=School name&GroupExDescriptions.1=Major&GroupExDescriptions.2=Grade&GroupExDescriptions.3=Student ID&<Common request parameters>

Output Example©2013-2022 Tencent Cloud. All rights reserved.

Page 109 of 321

Face Recognition{"Response": {"FaceModelVersion": "3.0","RequestId": "1695f3dd-b668-479e-8b87-f37de371a8ec"}}

Example3 Sample error
This example shows the error that will occur if a group ID already exists.
Input Example
https://iai.tencentcloudapi.com/?Action=CreateGroup&GroupName=Tencent Shenzhen Employee Group&GroupId=TencentShenZhenEmployee&<Common request parameters>

Output Example{"Response": {"RequestId": "76ec6e41-37d6-4ab9-abef-48ef0c6ab175"}}

Example4 Sample error - 2
This example shows the error that will occur if there are Chinese characters in a group ID.
Input Example
https://iai.tencentcloudapi.com/?Action=CreateGroup&GroupName=Tencent Shenzhen Employee Group&GroupId=Tencent Employees in Shenzhen&<Common request parameters>

Output Example{"Response": {"RequestId": "8125dda4-2905-4e02-88bd-79a93a660ad2"©2013-2022 Tencent Cloud. All rights reserved.

Page 110 of 321

Face Recognition}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

AuthFailure.InvalidAuthorization

Authentication failed.

FailedOperation.ConflictOperation

FailedOperation.DuplicatedGroupDescription
FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist©2013-2022 Tencent Cloud. All rights reserved.

The operations conflict. Do not operate on thesame person simultaneously.
The custom description field must be unique inthe group.
The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.

Page 111 of 321

Face Recognition

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.

InvalidParameterValue.DeleteFaceNumExceed

The number of faces to be deleted exceeds thelimit. Every person must have at least one face
image.

InvalidParameterValue.FaceModelVersionIllegal

The algorithm model version is invalid.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

InvalidParameterValue.GroupExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields can be created.
The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong©2013-2022 Tencent Cloud. All rights reserved.

The name of the group's custom description
field exceeds the length limit.

Page 112 of 321

Face Recognition

InvalidParameterValue.GroupFaceNumExceed

The number of faces in the group exceeds thelimit.

InvalidParameterValue.GroupIdAlreadyExist

The group ID already exists. It must be unique.

InvalidParameterValue.GroupIdIllegal

The group ID contains invalid characters. It cancontain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.GroupNameTooLong

The group name exceeds the length limit.

InvalidParameterValue.GroupNumExceed

The number of groups exceeds the limit. If you
need more, please contact us.

InvalidParameterValue.GroupNumPerPersonExceed

The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalid

InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong

The group remarks field exceeds the length
limit.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.LimitExceed

The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.

InvalidParameterValue.PersonExDescriptionInfosExceed

The array length of the person's custom©2013-2022 Tencent Cloud. All rights reserved.

Page 113 of 321

Face Recognition

description fields exceeds the limit. Up to 5
fields are allowed.
InvalidParameterValue.PersonExDescriptionsNameIdenticalInvalidParameterValue.PersonExDescriptionsNameIllegal

The name of the person's custom description
field must be unique.
The name of the person's custom description
field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroup

InvalidParameterValue.PersonFaceNumExceed

The name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person
exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.

InvalidParameterValue.PersonIdAlreadyExist

The person ID already exists. It must be unique.

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal
InvalidParameterValue.PersonNameTooLong
InvalidParameterValue.SearchPersonsExceed

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.
The person name exceeds the length limit.
The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

©2013-2022 Tencent Cloud. All rights reserved.

Page 114 of 321

Face Recognition

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.LowBalanceInsufficient balance.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.Recover

The resource has been repossessed.

ResourceUnavailable.StopUsing

The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 115 of 321

Face Recognition

DeleteGroup：

Last updated 2023-02-27 15:22:49

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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 othergroups will not be affected.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: DeleteGroup.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

GroupId

Yes

StringGroup ID, which is the GroupId in the CreateGroup API.

3. Output Parameters
Parameter
Name

Type

Description

RequestId

String

The unique request ID, which is returned for each request. RequestId is required for©2013-2022 Tencent Cloud. All rights reserved.

Page 116 of 321

Face Recognition

locating a problem.

4. Example
Example1 Deleting group
This example shows you how to delete a specified group and all its members.
Input Example
https://iai.tencentcloudapi.com/?Action=DeleteGroup&GroupId=ZhuYuanDormitoryNo1&<Common request parameters>

Output Example{"Response": {"RequestId": "2ff7181c-ef20-4f02-b4ed-13924b381368"}}

Example2 Sample error
This example shows the error that will occur if a group ID does not exist.
Input Example
https://iai.tencentcloudapi.com/?Action=DeleteGroup&GroupId=ZhuYuanDormitory&<Common request parameters>

Output Example{"Response": {"RequestId": "878b225f-d3a4-4aa0-a849-3df415ac61a9"}}©2013-2022 Tencent Cloud. All rights reserved.

Page 117 of 321

Face Recognition

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

6. Error CodeThe following only lists the error codes related to the API business logic. For other error codes, see Common Error
Codes.
Error Code
FailedOperation.ConflictOperation

Description
The operations conflict. Do not operate on thesame person simultaneously.

FailedOperation.DuplicatedGroupDescription

The custom description field must be unique inthe group.

FailedOperation.GroupInDeletedStateThe current group is being deleted. Please wait.

FailedOperation.GroupPersonMapExist

The ID of the corresponding person is alreadyin the group.

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

©2013-2022 Tencent Cloud. All rights reserved.

Page 118 of 321

Face Recognition

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

InvalidParameterValue.DeleteFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds thelimit. Every person must have at least one face
image.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

InvalidParameterValue.GroupExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields can be created.
The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal©2013-2022 Tencent Cloud. All rights reserved.

contain only letters, digits, and special symbols(-%@#&_).

Page 119 of 321

Face Recognition

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.GroupNameTooLong

The group name exceeds the length limit.

InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalid

InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

The group remarks field exceeds the length
limit.
Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdenticalInvalidParameterValue.PersonExDescriptionsNameIllegal©2013-2022 Tencent Cloud. All rights reserved.

The name of the person's custom description
field must be unique.
The name of the person's custom description
field contains invalid characters. It can contain

Page 120 of 321

Face Recognition

only letters, - , _ , and digits.
InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroup

InvalidParameterValue.PersonFaceNumExceed

The name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person
exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal
InvalidParameterValue.PersonIdAlreadyExist
InvalidParameterValue.PersonIdIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.
The person ID already exists. It must be unique.
The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal
InvalidParameterValue.PersonNameTooLong
InvalidParameterValue.SearchPersonsExceed

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.
The person name exceeds the length limit.
The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

©2013-2022 Tencent Cloud. All rights reserved.

Page 121 of 321

Face Recognition

ResourceUnavailable.Recover

The resource has been repossessed.

ResourceUnavailable.StopUsing

The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 122 of 321

Face Recognition

GetGroupInfo：

Last updated 2023-02-27 15:22:49

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to get the group information.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: GetGroupInfo.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

GroupId

Yes

StringGroup ID, which is the GroupId in the CreateGroup API.

3. Output Parameters
Parameter NameType

Description

GroupName

StringGroup nameGroupId

StringGroup ID

GroupExDescriptions

Array
of

Custom group description field©2013-2022 Tencent Cloud. All rights reserved.

Page 123 of 321

Face Recognition

StringTag

StringGroup remarks

FaceModelVersion

StringAlgorithm model version used for face recognition.
Group creation time and date ( CreationTimestamp ), whose value isCreationTimestamp

Integerthe number of milliseconds between the UNIX epoch time and the group
creation time.

RequestId

String

The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

4. Example
Example1 Getting group information
Input Example
https://iai.tencentcloudapi.com/?Action=GetGroupInfo&GroupId=aaa&<Common request parameters>

Output Example{"Response": {"GroupName": "aaa","GroupId": "aaa","GroupExDescriptions": ["24"],"Tag": "fdsaf","FaceModelVersion": "3.0","CreationTimestamp": 1559530931613,"RequestId": "6faa05d0-287b-464e-8755-cf3e8d0c703d"}}

5. Developer Resources©2013-2022 Tencent Cloud. All rights reserved.

Page 124 of 321

Face Recognition

SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.ServerError

The algorithm service is exceptional. Please retry.

InvalidParameterValue.GroupIdIllegal

The group ID contains invalid characters. It can contain only
letters, digits, and special symbols (-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.NotExist

The billing status is unknown. Please check whether the service
has been activated in the console.

ResourceUnavailable.StopUsing

The service has been suspended for the account.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

©2013-2022 Tencent Cloud. All rights reserved.

Page 125 of 321

Face Recognition©2013-2022 Tencent Cloud. All rights reserved.

Page 126 of 321

Face Recognition

GetGroupList：

Last updated 2023-02-27 15:22:48

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to get the list of groups.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: GetGroupList.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

OffsetNo

IntegerStarting number. Default value: 0.

Limit

No

IntegerNumber of returned results. Default value: 10. Maximum value:
1000.

Name

3. Output Parameters
Parameter
NameGroupInfosType

Description

Array of

Returned group information©2013-2022 Tencent Cloud. All rights reserved.

Page 127 of 321

Face Recognition

GroupInfo
GroupNum

Integer

Total number of groups
Note: this field may return null, indicating that no valid values can be obtained.

RequestId

String

The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

4. Example
Example1 Getting the group list
This example shows you how to get the group list.
Input Example
https://iai.tencentcloudapi.com/?Action=GetGroupList&Offset=0&Limit=10&<Common request parameters>

Output Example{"Response": {"GroupInfos": [{"GroupName": "Tencent Shenzhen Employees","GroupId": "TencentShenZhenEmployee","GroupExDescriptions": ["Business group","Department name","Group name"],"Tag": "Excluding interns""FaceModelVersion": "3.0","CreationTimestamp": 1592210245686},{"GroupName": "Dormitory Building #1, Zhuyuan Campus, XX University","GroupId": "ZhuYuanDormitoryNo1","GroupExDescriptions": ["School name","Major",©2013-2022 Tencent Cloud. All rights reserved.

Page 128 of 321

Face Recognition"Grade","Student ID"],"Tag": "Female only""FaceModelVersion": "3.0","CreationTimestamp": 1594552117118}],"GroupNum": 2,"RequestId": "72102087-a18d-4225-9ae9-87ef49e9f63e"}}

Example2 Sample error - 2
The number of returned results cannot be above 1,000.
Input Example
https://iai.tencentcloudapi.com/?Action=GetGroupList&Offset=0&Limit=1001&<Common request parameters>

Output Example{"Response": {"RequestId": "a6bb57de-773b-45e4-9e1c-c30ef48eba85"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go©2013-2022 Tencent Cloud. All rights reserved.

Page 129 of 321

Face Recognition

Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

AuthFailure.InvalidAuthorization

Authentication failed.

FailedOperation.ConflictOperation

The operations conflict. Do not operate on thesame person simultaneously.

FailedOperation.DuplicatedGroupDescription

The custom description field must be unique inthe group.

FailedOperation.GroupInDeletedStateThe current group is being deleted. Please wait.

FailedOperation.GroupPersonMapExist

The ID of the corresponding person is alreadyin the group.

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageSizeExceed
FailedOperation.RequestTimeout
FailedOperation.SearchFacesExceed
FailedOperation.ServerError©2013-2022 Tencent Cloud. All rights reserved.

The size of the Base64-encoded image cannot
exceed 5 MB.
The backend service timed out.
The number of faces searched for exceeds thelimit.
The algorithm service is exceptional. Please

Page 130 of 321

Face Recognition

retry.
InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

InvalidParameterValue.GroupExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields can be created.
The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

field contains invalid characters. It can contain
only letters, - , _ , and digits.
The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

InvalidParameterValue.GroupNameIllegal©2013-2022 Tencent Cloud. All rights reserved.

The group name already exists. It must be
unique.
The group name contains invalid characters. It
can contain only letters, - , _ , and digits.

Page 131 of 321

Face Recognition

InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

InvalidParameterValue.GroupTagIllegal

The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalidcharacters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

The group remarks field exceeds the length
limit.
Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

InvalidParameterValue.PersonExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields are allowed.
The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroup

field contains invalid characters. It can contain
only letters, - , _ , and digits.
The name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed©2013-2022 Tencent Cloud. All rights reserved.

exceeds the limit. One person can have up to 5
face images.

Page 132 of 321

Face Recognition

InvalidParameterValue.PersonGenderIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.

InvalidParameterValue.PersonIdAlreadyExist

The person ID already exists. It must be unique.

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal
InvalidParameterValue.PersonNameTooLong
InvalidParameterValue.SearchPersonsExceed

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.
The person name exceeds the length limit.
The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 133 of 321

Face Recognition

ModifyGroup：

Last updated 2023-02-27 15:22:47

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to modify the name, tag, and custom description field of a group.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

Description

ActionYes

StringCommon Params. The value used forthis API: ModifyGroup.

VersionYes

StringCommon Params. The value used forthis API: 2020-03-03.

RegionNo

StringGroupId

Yes

StringGroupNameNo

StringGroupExDescriptionInfos.N

Tag

No

No

©2013-2022 Tencent Cloud. All rights reserved.

Array ofGroupExDescriptionInfo
StringCommon Params. This parameter is
not required for this API.
Group ID, which is the GroupId in
the CreateGroup API.
Group name
Custom description field of the group
to be modified, which is a keyvalue pair.
Group remarks

Page 134 of 321

Face Recognition

3. Output Parameters
Parameter
Name

Type

Description

RequestId

String

The unique request ID, which is returned for each request. RequestId is required forlocating a problem.

4. Example
Example1 Modifying group
This example shows you how to modify the name, tag, and custom description field of a group.
Input Example
https://iai.tencentcloudapi.com/?Action=ModifyGroup&GroupId=ZhuYuanDormitoryNo1&GroupName=Dormitory Building #1, Zhuyuan Campus, XX University&Tag=Graduates&GroupExDescriptionInfos.0.GroupExDescriptionIndex=0&GroupExDescriptionInfos.0.GroupExDescription=School&<Common request parameters>

Output Example{"Response": {"RequestId": "da051f16-0400-49d4-9832-2cfd3b51866f"}}

Example2 Modifying group - 2
This example shows you how to modify the name, remarks, and custom description fields of a group.
Input Example
https://iai.tencentcloudapi.com/?Action=ModifyGroup&GroupId=TencentShenZhenEmployee&GroupName=Tencent Shenzhen In-Service Employee Group&Tag=Includes interns©2013-2022 Tencent Cloud. All rights reserved.

Page 135 of 321

Face Recognition&GroupExDescriptionInfos.0.GroupExDescriptionIndex=1&GroupExDescriptionInfos.0.GroupExDescription=Department&GroupExDescriptionInfos.1.GroupExDescriptionIndex=2&GroupExDescriptionInfos.1.GroupExDescription=Project team&<Common request parameters>

Output Example{"Response": {"RequestId": "98381738-509f-4749-8a66-dbf54247333d"}}

Example3 Sample error
The group name must be unique.
Input Example
https://iai.tencentcloudapi.com/?Action=ModifyGroup&GroupId=TencentShenZhenEmployee&GroupExDescriptionInfos.0.GroupExDescriptionIndex=0&GroupExDescriptionInfos.0.GroupExDescription=Department&<Common request parameters>

Output Example{"Response": {"RequestId": "4b483679-3f08-4a7c-b827-4a6332dc030f"}}

Example4 Sample error - 2
This example shows the error that will occur if a group name already exists.
Input Example
https://iai.tencentcloudapi.com/?Action=ModifyGroup&GroupId=TencentShenZhenEmployee&GroupName=Dormitory Building #1, Zhuyuan Campus, XX University&<Common request parameters>©2013-2022 Tencent Cloud. All rights reserved.

Page 136 of 321

Face Recognition

Output Example{"Response": {"RequestId": "2dcce170-30cf-4078-9b3c-309362fbad21"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

FailedOperation.ConflictOperation

The operations conflict. Do not operate on thesame person simultaneously.

FailedOperation.DuplicatedGroupDescription©2013-2022 Tencent Cloud. All rights reserved.

The custom description field must be unique inthe group.

Page 137 of 321

Face Recognition

FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist

FailedOperation.GroupPersonMapNotExist

The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.
The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

InvalidParameterValue.GroupExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields can be created.
The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

The name of the group's custom description©2013-2022 Tencent Cloud. All rights reserved.

Page 138 of 321

Face Recognition

field exceeds the length limit.
InvalidParameterValue.GroupFaceNumExceed

The number of faces in the group exceeds thelimit.

InvalidParameterValue.GroupIdAlreadyExist

The group ID already exists. It must be unique.

InvalidParameterValue.GroupIdIllegal

The group ID contains invalid characters. It cancontain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.GroupNameTooLong

The group name exceeds the length limit.

InvalidParameterValue.GroupNumExceed

The number of groups exceeds the limit. If you
need more, please contact us.

InvalidParameterValue.GroupNumPerPersonExceed

The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalid

InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong

The group remarks field exceeds the length
limit.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.LimitExceed

The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.

©2013-2022 Tencent Cloud. All rights reserved.

Page 139 of 321

Face Recognition

InvalidParameterValue.PersonExDescriptionInfosExceed

The array length of the person's custom
description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdenticalInvalidParameterValue.PersonExDescriptionsNameIllegal

The name of the person's custom description
field must be unique.
The name of the person's custom description
field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroup

InvalidParameterValue.PersonFaceNumExceed

The name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person
exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.

InvalidParameterValue.PersonIdAlreadyExist

The person ID already exists. It must be unique.

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal
InvalidParameterValue.PersonNameTooLong
InvalidParameterValue.SearchPersonsExceed

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.
The person name exceeds the length limit.
The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

©2013-2022 Tencent Cloud. All rights reserved.

Page 140 of 321

Face Recognition

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 141 of 321

Face Recognition

CreatePerson：

Last updated 2023-02-27 15:22:50

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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 .
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

ActionYes

String

VersionYes

StringRegionNo

StringGroupId

Yes

StringDescription
Common Params. The value used forthis API: CreatePerson.
Common Params. The value used forthis API: 2020-03-03.
Common Params. This parameter is
not required for this API.
ID of the group to join, which is theGroupId in the CreateGroupAPI.

©2013-2022 Tencent Cloud. All rights reserved.

Page 142 of 321

Face Recognition

PersonName

Yes

StringPerson name, which can contain 1 to
60 characters and is modifiable andrepeatable.
Person ID, which is unmodifiable,

PersonId

Yes

Stringmust be unique under a Tencent
Cloud account, and can containletters, digits, and special symbols (%@#&_) of up to 64 B.

Gender

PersonExDescriptionInfos.N

No

No

Integer

0: empty; 1: male; 2: female.

Array ofContent of person description field,
which is a key-value pair, canPersonExDescriptionInfo

contain 0 to 60 characters, and is
modifiable and repeatable.
Base64-encoded image data, whichcannot exceed 5 MB.

Image

No

String

The long side cannot exceed 4,000
px for images in JPG format or 2,000
px for images in other formats.
PNG, JPG, JPEG, and BMP images
are supported, while GIF images are
not.
Image URL. The image cannot
exceed 5 MB in size after being
Base64-encoded.
The long side cannot exceed 4,000
px for images in JPG format or 2,000
px for images in other formats.
Either Url or Image must be
provided; if both are provided, only
Url will be used.

Url

No

StringWe recommend storing the image inTencent Cloud, as a Tencent Cloud
URL can guarantee higher download
speed and stability.
The download speed and stability of
non-Tencent Cloud URLs may be
low.
PNG, JPG, JPEG, and BMP images
are supported, while GIF images arenot.

©2013-2022 Tencent Cloud. All rights reserved.

Page 143 of 321

Face Recognition

UniquePersonControl

No

IntegerThis parameter is used to control the
judgment whether the face containedin the image in Image or Urlcorresponds to an existing person in
the group.
If it is judged that a duplicate person
exists in the group, no new person
will be created, and information of
the suspected duplicate person will
be returned.
Otherwise, the new person will becreated.
0: do not judge, i.e., the person willbe created no matter whether aduplicate person exists in the group.
1: low duplicate person judgment
requirement (1% FAR);
2: average duplicate person
judgment requirement (0.1% FAR);
3: high duplicate person judgment
requirement (0.01% FAR);
4: very high duplicate person
judgment requirement (0.001%
FAR).
Default value: 0.
Note: the higher the requirement, thelower the probability of duplicate
person. The FARs corresponding todifferent requirements are forreference only and can be adjusted
as needed.

QualityControl

No

Integer

Image quality control.
0: no control.
1: low quality requirement. The
image has one or more of thefollowing problems: extreme
blurriness, covered eyes, covered
nose, and covered mouth.
2: average quality requirement. The
image has at least three of thefollowing problems: excessive
brightness, excessive dimness,blurriness or average blurriness,covered eyebrows, covered cheeks,©2013-2022 Tencent Cloud. All rights reserved.

Page 144 of 321

Face Recognitionand covered chin.
3: high-quality requirement. The
image has one to two of the following
problems: excessive brightness,
excessive dimness, average
blurriness, covered eyebrows,
covered cheeks, and covered chin.
4: very high-quality requirement. The
image is optimal in all dimensions or
only has a slight problem in one
dimension.
Default value: 0.
If the image quality does not meet therequirement, the returned result willprompt that the detected image
quality is unsatisfactory.
Whether to enable the support for
rotated image recognition. 0: no; 1:yes. Default value: 0. When the facein the image is rotated and the image
has no EXIF information, if thisparameter is not enabled, the face in
NeedRotateDetection

No

Integerthe image cannot be correctly
detected and recognized. If you are
sure that the input image contains
EXIF information or the face in theimage will not be rotated, do notenable this parameter, as the overall
time consumption may increase by
hundreds of milliseconds after it isenabled.

3. Output Parameters
Parameter NameType

Description

FaceIdStringUnique ID of face image.

FaceRect

Position of detected face frame.
Note: this field may return null, indicating that no valid values can be

FaceRectobtained.
SimilarPersonId

StringPersonId of suspected duplicate person.

©2013-2022 Tencent Cloud. All rights reserved.

Page 145 of 321

Face Recognition

This parameter is meaningful only if the UniquePersonControl
parameter is not 0 and there is a suspected duplicate person in the group.
FaceModelVersion

StringRequestId

StringAlgorithm model version used for face recognition.
The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

4. Example
Example1 Creating person
Input Example
https://iai.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=Class of 2015
&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"©2013-2022 Tencent Cloud. All rights reserved.

Page 146 of 321

Face Recognition}}

Example2 Creating person - 2
This example shows you how to create persons.
Input Example
https://iai.tencentcloudapi.com/?Action=CreatePerson&GroupId=TencentShenZhenEmployee&PersonName=evanliao&PersonId=1001&Gender=1&Url=http://test.image.myqcloud.com/testA.jpg&PersonExDescriptionInfos.0.PersonExDescriptionIndex=0&PersonExDescriptionInfos.0.PersonExDescription=Cloud & Smart Industries Group&PersonExDescriptionInfos.1.PersonExDescriptionIndex=1&PersonExDescriptionInfos.1.PersonExDescription=AI Product Center&PersonExDescriptionInfos.2.PersonExDescriptionIndex=2&PersonExDescriptionInfos.2.PersonExDescription=Face Recognition Products Group&<Common request parameters>

Output Example{"Response": {"FaceId": "3454816969590585881","SimilarPersonId": "","FaceRect": {"X": 172,"Y": 122,"Width": 178,
"Height": 228},"FaceModelVersion": "3.0","RequestId": "269a6bc0-0016-47e8-a63d-517ce4052b0e"}}

Example3 Sample error
This example shows the error that will occur if a person ID already exists.
Input Example©2013-2022 Tencent Cloud. All rights reserved.

Page 147 of 321

Face Recognition

https://iai.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": {"RequestId": "76dedef7-af27-4a20-9064-c5ef3133926d"}}

Example4 Sample error - 2
This example shows the error that will occur if a group ID does not exist.
Input Example
https://iai.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": {"RequestId": "dfa512fc-fd07-4bf1-a292-cb497b620857"}}

5. Developer Resources
SDK©2013-2022 Tencent Cloud. All rights reserved.

Page 148 of 321

Face Recognition

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

AuthFailure.InvalidAuthorization

Authentication failed.

FailedOperation.ConflictOperation
FailedOperation.CreateFaceConcurrent
FailedOperation.DuplicatedGroupDescription

FailedOperation.FaceQualityNotQualified

The operations conflict. Do not operate on thesame person simultaneously.
Faces cannot be added concurrently.
The custom description field must be unique inthe group.
The face image quality does not meet therequirement.
The face frame size is smaller than the

FailedOperation.FaceSizeTooSmall

MinFaceSize value, and the face is filtered
out.

FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist©2013-2022 Tencent Cloud. All rights reserved.

The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.

Page 149 of 321

Face Recognition

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

FailedOperation.ImageResolutionTooSmall

The image short edge resolution is smaller than64.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

InvalidParameterValue.GroupExDescriptionsExceed

limit. Every person must have at least one face
image.
The array length of the group's custom
description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal©2013-2022 Tencent Cloud. All rights reserved.

field contains invalid characters. It can contain
only letters, - , _ , and digits.

Page 150 of 321

Face Recognition

InvalidParameterValue.GroupExDescriptionsNameTooLong

The name of the group's custom description
field exceeds the length limit.

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.GroupNameTooLong

The group name exceeds the length limit.

InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

InvalidParameterValue.GroupTagIllegal

The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalidcharacters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

The group remarks field exceeds the length
limit.
Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please check©2013-2022 Tencent Cloud. All rights reserved.

Page 151 of 321

Face Recognition

the length of the array to be requested.
The array length of the person's custom
InvalidParameterValue.PersonExDescriptionInfosExceed

InvalidParameterValue.PersonExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields are allowed.
The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

InvalidParameterValue.PersonExDescriptionsNameTooLong

field contains invalid characters. It can contain
only letters, - , _ , and digits.
The name of the person's custom description
field exceeds the length limit.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.

InvalidParameterValue.PersonIdAlreadyExist

The person ID already exists. It must be unique.

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.QualityControlIllegal

Invalid QualityControl parameter.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UniquePersonControlIllegal

Invalid UniquePersonControl parameter.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

©2013-2022 Tencent Cloud. All rights reserved.

Page 152 of 321

Face Recognition

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.LowBalanceInsufficient balance.

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 153 of 321

Face Recognition

DeletePerson：

Last updated 2023-02-27 15:22:49

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to delete a person from all groups. Meanwhile, all face information of the person will be deleted.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter
Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: DeletePerson.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

PersonId

Yes

StringPerson ID, which is the PersonId in the CreatePerson
API.

3. Output Parameters
Parameter
Name

Type

Description

RequestId

String

The unique request ID, which is returned for each request. RequestId is required forlocating a problem.

©2013-2022 Tencent Cloud. All rights reserved.

Page 154 of 321

Face Recognition

4. Example
Example1 Deleting person
This example shows you how to delete a specified person.
Input Example
https://iai.tencentcloudapi.com/?Action=DeletePerson&PersonId=2001&<Common request parameters>

Output Example{"Response": {"RequestId": "4b609b7c-7a9a-4ea0-be8b-1fb638c2ceca"}}

Example2 Sample error
This example shows the error that will occur if a person ID does not exist.
Input Example
https://iai.tencentcloudapi.com/?Action=DeletePerson&PersonId=3001&<Common request parameters>

Output Example{"Response": {"RequestId": "4b9c1bdc-86eb-413f-8c74-15bcf4466cd5"}}

5. Developer Resources
SDK©2013-2022 Tencent Cloud. All rights reserved.

Page 155 of 321

Face Recognition

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

6. Error CodeThe following only lists the error codes related to the API business logic. For other error codes, see Common Error
Codes.
Error Code
FailedOperation.ConflictOperation
FailedOperation.CreateFaceConcurrent
FailedOperation.DuplicatedGroupDescription
FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist

FailedOperation.GroupPersonMapNotExist

Description
The operations conflict. Do not operate on thesame person simultaneously.
Faces cannot be added concurrently.
The custom description field must be unique inthe group.
The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.
The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

©2013-2022 Tencent Cloud. All rights reserved.

Page 156 of 321

Face Recognition

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

InvalidParameterValue.GroupExDescriptionsExceed

limit. Every person must have at least one face
image.
The array length of the group's custom
description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

The name of the group's custom description
field exceeds the length limit.

InvalidParameterValue.GroupFaceNumExceed

The number of faces in the group exceeds thelimit.

InvalidParameterValue.GroupIdAlreadyExist

The group ID already exists. It must be unique.

InvalidParameterValue.GroupIdIllegal

The group ID contains invalid characters. It cancontain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist©2013-2022 Tencent Cloud. All rights reserved.

The group ID does not exist.

Page 157 of 321

Face Recognition

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal
InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

InvalidParameterValue.GroupTagIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.
The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalidcharacters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

The group remarks field exceeds the length
limit.
Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

InvalidParameterValue.PersonExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields are allowed.
The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal©2013-2022 Tencent Cloud. All rights reserved.

field contains invalid characters. It can contain
only letters, - , _ , and digits.

Page 158 of 321

Face Recognition

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroupThe name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

InvalidParameterValue.PersonGenderIllegal
InvalidParameterValue.PersonIdAlreadyExist
InvalidParameterValue.PersonIdIllegal

exceeds the limit. One person can have up to 5
face images.
An error occurred while setting person gender.
0: empty; 1: male; 2: female.
The person ID already exists. It must be unique.
The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.Recover

The resource has been repossessed.

©2013-2022 Tencent Cloud. All rights reserved.

Page 159 of 321

Face Recognition

ResourceUnavailable.StopUsing

The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 160 of 321

Face Recognition

DeletePersonFromGroup：

Last updated 2023-02-27 15:22:49

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter

RequiredType

ActionYes

String

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

PersonId

Yes

StringGroupId

Yes

StringName

Description
Common Params. The value used for this API:
DeletePersonFromGroup.

Person ID, which is the PersonId in the CreatePerson
API.
Group ID, which is the GroupId in the CreateGroup API.

3. Output Parameters
Parameter

Type

DescriptionName©2013-2022 Tencent Cloud. All rights reserved.

Page 161 of 321

Face Recognition

RequestId

String

The unique request ID, which is returned for each request. RequestId is required forlocating a problem.

4. Example
Example1 Deleting person from group
This example shows you how to delete a person from a group. This operation only affects the group.
Input Example
https://iai.tencentcloudapi.com/?Action=DeletePersonFromGroup&PersonId=1001&GroupId=TencentShenZhenEmployee&<Common request parameters>

Output Example{"Response": {"RequestId": "f9b22bbc-c94d-4287-a2ab-fa68f7bbbaf3"}}

Example2 Sample error
This example shows the error that will occur if the specified person is not in the group.
Input Example
https://iai.tencentcloudapi.com/?Action=DeletePersonFromGroup&PersonId=3001&GroupId=ZhuYuanDormitoryNo1&<Common request parameters>

Output Example{"Response": {"RequestId": "b9d9641d-3de2-4a6f-a728-36a3b66e7bd0"}}©2013-2022 Tencent Cloud. All rights reserved.

Page 162 of 321

Face Recognition

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

FailedOperation.ConflictOperation

The operations conflict. Do not operate on thesame person simultaneously.

FailedOperation.CreateFaceConcurrent

Faces cannot be added concurrently.

FailedOperation.DuplicatedGroupDescription

The custom description field must be unique inthe group.

FailedOperation.GroupInDeletedStateThe current group is being deleted. Please wait.

FailedOperation.GroupPersonMapExist

The ID of the corresponding person is alreadyin the group.

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

©2013-2022 Tencent Cloud. All rights reserved.

Page 163 of 321

Face Recognition

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

FailedOperation.ServerError

The number of faces searched for exceeds thelimit.
The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

InvalidParameterValue.GroupExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields can be created.
The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist©2013-2022 Tencent Cloud. All rights reserved.

field contains invalid characters. It can contain
only letters, - , _ , and digits.
The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.

Page 164 of 321

Face Recognition

InvalidParameterValue.GroupIdIllegal

The group ID contains invalid characters. It cancontain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal
InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

InvalidParameterValue.GroupTagIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.
The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalidcharacters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

The group remarks field exceeds the length
limit.
Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdentical

The name of the person's custom description©2013-2022 Tencent Cloud. All rights reserved.

Page 165 of 321

Face Recognition

field must be unique.
The name of the person's custom description
InvalidParameterValue.PersonExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

The name of the person's custom description
field exceeds the length limit.

InvalidParameterValue.PersonExistInGroupThe ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

InvalidParameterValue.PersonGenderIllegal
InvalidParameterValue.PersonIdAlreadyExist
InvalidParameterValue.PersonIdIllegal

exceeds the limit. One person can have up to 5
face images.
An error occurred while setting person gender.
0: empty; 1: male; 2: female.
The person ID already exists. It must be unique.
The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

©2013-2022 Tencent Cloud. All rights reserved.

Page 166 of 321

Face Recognition

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 167 of 321

Face Recognition

GetPersonGroupInfo：

Last updated 2023-02-27 15:22:48

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to get the information of a specified person, including group, description, etc.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter
Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API:
GetPersonGroupInfo.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

PersonId

Yes

StringOffsetNo

IntegerStarting number. Default value: 0.

Limit

No

IntegerNumber of returned results. Default value: 10. Maximum value:
100.

Person ID, which is the PersonId in the CreatePerson
API.

3. Output Parameters©2013-2022 Tencent Cloud. All rights reserved.

Page 168 of 321

Face Recognition

Parameter NameType

Description

PersonGroupInfos

Array of
PersonGroupInfo

List of groups containing this person and their description fields
Total number of groups

GroupNum

FaceModelVersion

IntegerStringNote: this field may return null, indicating that no valid values can beobtained.
Algorithm model version used by the Face Recognition service.
Note: this field may return null, indicating that no valid values can beobtained.

RequestId

String

The unique request ID, which is returned for each request.
RequestId is required for locating a problem.

4. Example
Example1 Getting the group information of person
Input Example
https://iai.tencentcloudapi.com/?Action=GetPersonGroupInfo&PersonId=2001&Offset=0&Limit=10&<Common request parameters>

Output Example{"Response": {"GroupNum": "1","PersonGroupInfos": [{"GroupId": "ZhuYuanDormitoryNo1","PersonExDescriptions": ["School of Computer Science","Software Engineering","Class of 2015","3150108080"]}],©2013-2022 Tencent Cloud. All rights reserved.

Page 169 of 321

Face Recognition"FaceModelVersion": "3.0","RequestId": "671f0a1d-2b35-47c4-b9d1-b18053f71a04"}}

Example2 Getting the group information of person - 2
Input Example
https://iai.tencentcloudapi.com/?Action=GetPersonGroupInfo&PersonId=1001&Offset=0&Limit=10&<Common request parameters>

Output Example{"Response": {"GroupNum": "1","PersonGroupInfos": [{"GroupId": "TencentShenZhenEmployee","PersonExDescriptions": ["Cloud & Smart Industries Group","Big Data and AI Products Center","Face Recognition Products Group"]}],"FaceModelVersion": "3.0","RequestId": "b7a505ad-4a85-42da-97b3-886c7999fb76"}}

Example3 Sample error
This example shows the error that will occur if a person ID does not exist.
Input Example
https://iai.tencentcloudapi.com/?Action=GetPersonGroupInfo&PersonId=1002&Offset=0©2013-2022 Tencent Cloud. All rights reserved.

Page 170 of 321

Face Recognition&Limit=10&<Common request parameters>

Output Example{"Response": {"RequestId": "98330f25-eb2e-432a-a30c-3830774210c1"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

FailedOperation.ConflictOperation

The operations conflict. Do not operate on thesame person simultaneously.

FailedOperation.DuplicatedGroupDescription

The custom description field must be unique in©2013-2022 Tencent Cloud. All rights reserved.

Page 171 of 321

Face Recognition

the group.
FailedOperation.GroupInDeletedStateThe current group is being deleted. Please wait.

FailedOperation.GroupPersonMapExist

The ID of the corresponding person is alreadyin the group.

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

InvalidParameterValue.DeleteFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds thelimit. Every person must have at least one face
image.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

InvalidParameterValue.GroupExDescriptionsNameIdenticalInvalidParameterValue.GroupExDescriptionsNameIllegal

description fields exceeds the limit. Up to 5
fields can be created.
The name of the group's custom description
field must be unique.
The name of the group's custom description
field contains invalid characters. It can contain©2013-2022 Tencent Cloud. All rights reserved.

Page 172 of 321

Face Recognition

only letters, - , _ , and digits.
InvalidParameterValue.GroupExDescriptionsNameTooLong

The name of the group's custom description
field exceeds the length limit.

InvalidParameterValue.GroupFaceNumExceed

The number of faces in the group exceeds thelimit.

InvalidParameterValue.GroupIdAlreadyExist

The group ID already exists. It must be unique.

InvalidParameterValue.GroupIdIllegal

The group ID contains invalid characters. It cancontain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.GroupNameTooLong

The group name exceeds the length limit.

InvalidParameterValue.GroupNumExceed

The number of groups exceeds the limit. If you
need more, please contact us.

InvalidParameterValue.GroupNumPerPersonExceed

The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalid

InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong

The group remarks field exceeds the length
limit.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.LimitExceed

The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

©2013-2022 Tencent Cloud. All rights reserved.

Page 173 of 321

Face Recognition

InvalidParameterValue.OffsetExceed

InvalidParameterValue.PersonExDescriptionInfosExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom
description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdenticalInvalidParameterValue.PersonExDescriptionsNameIllegal

The name of the person's custom description
field must be unique.
The name of the person's custom description
field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroup

InvalidParameterValue.PersonFaceNumExceed

The name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person
exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.

InvalidParameterValue.PersonIdAlreadyExist

The person ID already exists. It must be unique.

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal
InvalidParameterValue.PersonNameTooLong
InvalidParameterValue.SearchPersonsExceed

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.
The person name exceeds the length limit.
The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

©2013-2022 Tencent Cloud. All rights reserved.

Page 174 of 321

Face Recognition

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.Recover

The resource has been repossessed.

ResourceUnavailable.StopUsing

The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 175 of 321

Face Recognition

GetPersonBaseInfo：

Last updated 2023-02-27 15:22:48

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to get the information of a specified person, including name, gender, face, etc.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: GetPersonBaseInfo.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

PersonId

Yes

StringName

Person ID, which is the PersonId in the CreatePerson
API.

3. Output Parameters
Parameter

Type

Description

PersonName

StringPerson name

GenderInteger

Person gender. 0: empty; 1: male; 2: female.

Name©2013-2022 Tencent Cloud. All rights reserved.

Page 176 of 321

Face Recognition

FaceIds

Array of

List of the IDs of included faces

StringRequestId

String

The unique request ID, which is returned for each request. RequestId is required
for locating a problem.

4. Example
Example1 Getting the basic information of person
This example shows you how to get the information of the specified person, including name, gender, and face.
Input Example
https://iai.tencentcloudapi.com/?Action=GetPersonBaseInfo&PersonId=1001&<Common request parameters>

Output Example{"Response": {"PersonName": "EvanLiao","Gender": 1,"FaceIds": ["2873640802022644880","2875186538564559728"],"RequestId": "9568a077-0710-40d2-9d6a-b9483d3f2051"}}

Example2 Sample error
This example shows the error that will occur if a person ID does not exist.
Input Example
https://iai.tencentcloudapi.com/?Action=GetPersonBaseInfo&PersonId=1002&<Common request parameters>

Output Example©2013-2022 Tencent Cloud. All rights reserved.

Page 177 of 321

Face Recognition{"Response": {"RequestId": "98b4a0bc-802b-4764-9701-bc0c6c544395"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

6. Error CodeThe following only lists the error codes related to the API business logic. For other error codes, see Common Error
Codes.
Error Code
FailedOperation.ConflictOperation

FailedOperation.DuplicatedGroupDescription

Description
The operations conflict. Do not operate on thesame person simultaneously.
The custom description field must be unique inthe group.

FailedOperation.GroupInDeletedStateThe current group is being deleted. Please wait.

FailedOperation.GroupPersonMapExist

The ID of the corresponding person is already©2013-2022 Tencent Cloud. All rights reserved.

Page 178 of 321

Face Recognitionin the group.
FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

InvalidParameterValue.GroupExDescriptionsExceed

limit. Every person must have at least one face
image.
The array length of the group's custom
description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdenticalInvalidParameterValue.GroupExDescriptionsNameIllegal

The name of the group's custom description
field must be unique.
The name of the group's custom description
field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong©2013-2022 Tencent Cloud. All rights reserved.

The name of the group's custom description
field exceeds the length limit.

Page 179 of 321

Face Recognition

InvalidParameterValue.GroupFaceNumExceed

The number of faces in the group exceeds thelimit.

InvalidParameterValue.GroupIdAlreadyExist

The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

InvalidParameterValue.GroupNameIllegal
InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

InvalidParameterValue.GroupTagIllegal

The group name already exists. It must be
unique.
The group name contains invalid characters. It
can contain only letters, - , _ , and digits.
The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalidcharacters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

The group remarks field exceeds the length
limit.
Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed
InvalidParameterValue.PersonExDescriptionInfosExceed©2013-2022 Tencent Cloud. All rights reserved.

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

Page 180 of 321

Face Recognition

description fields exceeds the limit. Up to 5
fields are allowed.
InvalidParameterValue.PersonExDescriptionsNameIdentical

The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

The name of the person's custom description
field exceeds the length limit.

InvalidParameterValue.PersonExistInGroupThe ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

InvalidParameterValue.PersonGenderIllegal
InvalidParameterValue.PersonIdAlreadyExist
InvalidParameterValue.PersonIdIllegal

exceeds the limit. One person can have up to 5
face images.
An error occurred while setting person gender.
0: empty; 1: male; 2: female.
The person ID already exists. It must be unique.
The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

©2013-2022 Tencent Cloud. All rights reserved.

Page 181 of 321

Face Recognition

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.Recover

The resource has been repossessed.

ResourceUnavailable.StopUsing

The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 182 of 321

Face Recognition

GetPersonList：

Last updated 2023-02-27 15:22:47

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to get the list of persons in a specified group.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: GetPersonList.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

GroupId

Yes

StringGroup ID, which is the GroupId in the CreateGroup API.

OffsetNo

IntegerStarting number. Default value: 0.

Limit

No

IntegerName

Number of returned results. Default value: 10. Maximum value:
1000.

3. Output Parameters
Parameter NameType

Description©2013-2022 Tencent Cloud. All rights reserved.

Page 183 of 321

Face Recognition

PersonInfos

Array of

Returned person information

PersonInfo
Number of persons in the group
PersonNum

Integer

Note: this field may return null, indicating that no valid values can beobtained.
Number of faces in the group

FaceNum

Integer

Note: this field may return null, indicating that no valid values can beobtained.

FaceModelVersion

StringAlgorithm model version used for face recognition.
Note: this field may return null, indicating that no valid values can beobtained.

RequestId

String

The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

4. Example
Example1 Getting person list
This example shows you how to get the list of persons in a specified group.
Input Example
https://iai.tencentcloudapi.com/?Action=GetPersonList&GroupId=ZhuYuanDormitoryNo1&Offset=0&Limit=10&<Common request parameters>

Output Example{"Response": {"PersonInfos": [{"PersonName": "Junly","PersonId": "2001","Gender": 1,"PersonExDescriptions": ["School of Computer Science","Software Engineering",©2013-2022 Tencent Cloud. All rights reserved.

Page 184 of 321

Face Recognition"Class of 2015","3150108080"],"FaceIds": ["2877244861637985315"],"CreationTimestamp": 1594642823572}],"PersonNum": 1,"FaceNum": 1,"FaceModelVersion": "3.0","RequestId": "337d1bb5-3f88-4681-9291-5194f478f0d1"}}

Example2 Getting person list - 2
Input Example
https://iai.tencentcloudapi.com/?Action=GetPersonList&GroupId=TencentShenZhenEmployee&Offset=0&Limit=10&<Common request parameters>

Output Example{"Response": {"PersonInfos": [{"PersonName": "evanliao","PersonId": "1001","Gender": 1,"PersonExDescriptions": ["Cloud & Smart Industries Group","Big Data and AI Products Center","Face Recognition Products Group"],"FaceIds": ["2877242150180891493"],"CreationTimestamp": 1594642823572}©2013-2022 Tencent Cloud. All rights reserved.

Page 185 of 321

Face Recognition],"PersonNum": 1,"FaceNum": 1,"FaceModelVersion": "3.0","RequestId": "aa292f16-27d9-423b-9048-cdd43f6e4156"}}

Example3 Sample error
The group ID does not exist.
Input Example
https://iai.tencentcloudapi.com/?Action=GetPersonList&GroupId=ZhuYuanDormitory&Offset=0&Limit=10&<Common request parameters>

Output Example{"Response": {"RequestId": "b7c0cd81-d621-465f-8fd6-86a6b49e67be"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++©2013-2022 Tencent Cloud. All rights reserved.

Page 186 of 321

Face Recognition

Command Line Interface
Tencent Cloud CLI 3.0

6. Error CodeThe following only lists the error codes related to the API business logic. For other error codes, see Common Error
Codes.
Error Code
FailedOperation.ConflictOperation

Description
The operations conflict. Do not operate on thesame person simultaneously.

FailedOperation.DuplicatedGroupDescription

The custom description field must be unique inthe group.

FailedOperation.GroupInDeletedStateThe current group is being deleted. Please wait.

FailedOperation.GroupPersonMapExist

The ID of the corresponding person is alreadyin the group.

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

FailedOperation.ServerError

The number of faces searched for exceeds thelimit.
The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

©2013-2022 Tencent Cloud. All rights reserved.

Page 187 of 321

Face Recognition

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

InvalidParameterValue.GroupNameIllegal
InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed
InvalidParameterValue.GroupNumPerPersonExceed©2013-2022 Tencent Cloud. All rights reserved.

The group name already exists. It must be
unique.
The group name contains invalid characters. It
can contain only letters, - , _ , and digits.
The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One

Page 188 of 321

Face Recognition

person can be added to up to 100 groups.
The group remarks field contains invalid
InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

The group remarks field exceeds the length
limit.
Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

InvalidParameterValue.PersonExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields are allowed.
The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroup

field contains invalid characters. It can contain
only letters, - , _ , and digits.
The name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

InvalidParameterValue.PersonGenderIllegal

exceeds the limit. One person can have up to 5
face images.
An error occurred while setting person gender.
0: empty; 1: male; 2: female.

InvalidParameterValue.PersonIdAlreadyExist

The person ID already exists. It must be unique.

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It©2013-2022 Tencent Cloud. All rights reserved.

Page 189 of 321

Face Recognition

can contain only letters, digits, and -%@#&_.
InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal
InvalidParameterValue.PersonNameTooLong
InvalidParameterValue.SearchPersonsExceed

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.
The person name exceeds the length limit.
The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 190 of 321

Face Recognition

GetPersonListNum：

Last updated 2023-02-27 15:22:47

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to get the number of persons in a specified group.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: GetPersonListNum.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

GroupId

Yes

StringGroup ID, which is the GroupId in the CreateGroup API.

3. Output Parameters
Parameter

Type

Description

PersonNum

IntegerNumber of persons

FaceNum

IntegerNumber of faces

RequestId

String

The unique request ID, which is returned for each request. RequestId is required forName©2013-2022 Tencent Cloud. All rights reserved.

Page 191 of 321

Face Recognition

locating a problem.

4. Example
Example1 Getting person list length
This example shows you how to get the number of persons in a specified group.
Input Example
https://iai.tencentcloudapi.com/?Action=GetPersonListNum&GroupId=TencentShenZhenEmployee&<Common request parameters>

Output Example{"Response": {"PersonNum": 2,"FaceNum": 2,"RequestId": "18fb1e31-0d33-4371-9f41-b1fd59e0c781"}}

Example2 Sample error
This example shows the error that will occur if a group ID does not exist.
Input Example
https://iai.tencentcloudapi.com/?Action=GetPersonListNum&GroupId=Tencent&<Common request parameters>

Output Example{"Response": {"RequestId": "2865a458-4db1-46bd-ae52-b7507c9f4e62"}}©2013-2022 Tencent Cloud. All rights reserved.

Page 192 of 321

Face Recognition

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

6. Error CodeThe following only lists the error codes related to the API business logic. For other error codes, see Common Error
Codes.
Error Code
FailedOperation.ConflictOperation

FailedOperation.DuplicatedGroupDescription
FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist

FailedOperation.GroupPersonMapNotExist

Description
The operations conflict. Do not operate on thesame person simultaneously.
The custom description field must be unique inthe group.
The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.
The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

©2013-2022 Tencent Cloud. All rights reserved.

Page 193 of 321

Face Recognition

FailedOperation.ImageFacedetectFailed
FailedOperation.ImageSizeExceed

Face detection failed.
The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

FailedOperation.ServerError

The number of faces searched for exceeds thelimit.
The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

InvalidParameterValue.GroupExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields can be created.
The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

field contains invalid characters. It can contain
only letters, - , _ , and digits.
The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal©2013-2022 Tencent Cloud. All rights reserved.

contain only letters, digits, and special symbols(-%@#&_).

Page 194 of 321

Face Recognition

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

InvalidParameterValue.GroupNameIllegal
InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

InvalidParameterValue.GroupTagIllegal

The group name already exists. It must be
unique.
The group name contains invalid characters. It
can contain only letters, - , _ , and digits.
The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalidcharacters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

The group remarks field exceeds the length
limit.
Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdenticalInvalidParameterValue.PersonExDescriptionsNameIllegal

The name of the person's custom description
field must be unique.
The name of the person's custom description
field contains invalid characters. It can contain©2013-2022 Tencent Cloud. All rights reserved.

Page 195 of 321

Face Recognition

only letters, - , _ , and digits.
InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroupThe name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal
InvalidParameterValue.PersonIdAlreadyExist
InvalidParameterValue.PersonIdIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.
The person ID already exists. It must be unique.
The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

©2013-2022 Tencent Cloud. All rights reserved.

Page 196 of 321

Face Recognition

ResourceUnavailable.Recover

The resource has been repossessed.

ResourceUnavailable.StopUsing

The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 197 of 321

Face Recognition

ModifyPersonGroupInfo：

Last updated 2023-02-27 15:22:47

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to modify the description of a specified person in a group.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

ActionYes

String

VersionYes

StringRegionNo

StringGroupId

Yes

StringDescription
Common Params. The value used forthis API: ModifyPersonGroupInfo.
Common Params. The value used forthis API: 2020-03-03.
Common Params. This parameter is
not required for this API.
Group ID, which is the GroupId
in the CreateGroup API.
Person ID, which is the

PersonId

Yes

StringPersonId in theCreatePerson API.

PersonExDescriptionInfos.N

Yes©2013-2022 Tencent Cloud. All rights reserved.

Array of
PersonExDescriptionInfo

Custom description field of theperson to be modified, which is a
key-value pair.

Page 198 of 321

Face Recognition

3. Output Parameters
Parameter
Name
RequestId

Type

Description

String

The unique request ID, which is returned for each request. RequestId is required forlocating a problem.

4. Example
Example1 Modifying person description
Input Example
https://iai.tencentcloudapi.com/?Action=ModifyPersonGroupInfo&GroupId=ZhuYuanDormitoryNo1&PersonId=2001&PersonExDescriptionInfos.0.PersonExDescriptionIndex=3&PersonExDescriptionInfos.0.PersonExDescription=3150108080&<Common request parameters>

Output Example{"Response": {"RequestId": "77e11a2d-0fc0-4fba-ab25-016e998221c3"}}

Example2 Modifying person description - 2
Input Example
https://iai.tencentcloudapi.com/?Action=ModifyPersonGroupInfo&GroupId=TencentShenZhenEmployee&PersonId=1001&PersonExDescriptionInfos.0.PersonExDescriptionIndex=1&PersonExDescriptionInfos.0.PersonExDescription=Big Data and AI Products Center&<Common request parameters>

Output Example©2013-2022 Tencent Cloud. All rights reserved.

Page 199 of 321

Face Recognition{"Response": {"RequestId": "77e11a2d-0fc0-4fba-ab25-016e998221c3"}}

Example3 Sample error
This example shows the error that will occur if a subscript is invalid.
Input Example
https://iai.tencentcloudapi.com/?Action=ModifyPersonGroupInfo&GroupId=TencentShenZhenEmployee&PersonId=1001&PersonExDescriptionInfos.0.PersonExDescriptionIndex=-1&PersonExDescriptionInfos.0.PersonExDescription=AI Lab&<Common request parameters>

Output Example{"Response": {"RequestId": "f944657d-6260-4a2e-a4d8-9c1845f39e56"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++©2013-2022 Tencent Cloud. All rights reserved.

Page 200 of 321

Face Recognition

Command Line Interface
Tencent Cloud CLI 3.0

6. Error CodeThe following only lists the error codes related to the API business logic. For other error codes, see Common Error
Codes.
Error Code
FailedOperation.ConflictOperation

FailedOperation.DuplicatedGroupDescription

Description
The operations conflict. Do not operate on thesame person simultaneously.
The custom description field must be unique inthe group.

FailedOperation.GroupInDeletedStateThe current group is being deleted. Please wait.

FailedOperation.GroupPersonMapExist

The ID of the corresponding person is alreadyin the group.

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageSizeExceed
FailedOperation.RequestTimeout
FailedOperation.SearchFacesExceed

The size of the Base64-encoded image cannot
exceed 5 MB.
The backend service timed out.
The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds the©2013-2022 Tencent Cloud. All rights reserved.

Page 201 of 321

Face Recognition

limit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

The name of the group's custom description
field exceeds the length limit.

InvalidParameterValue.GroupFaceNumExceed

The number of faces in the group exceeds thelimit.

InvalidParameterValue.GroupIdAlreadyExist

The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

InvalidParameterValue.GroupNameIllegal
InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed©2013-2022 Tencent Cloud. All rights reserved.

The group name already exists. It must be
unique.
The group name contains invalid characters. It
can contain only letters, - , _ , and digits.
The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.

Page 202 of 321

Face Recognition

InvalidParameterValue.GroupTagIllegal

The group remarks field contains invalidcharacters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

The group remarks field exceeds the length
limit.
Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

InvalidParameterValue.PersonExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields are allowed.
The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroup

field contains invalid characters. It can contain
only letters, - , _ , and digits.
The name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

InvalidParameterValue.PersonGenderIllegal
InvalidParameterValue.PersonIdAlreadyExist
InvalidParameterValue.PersonIdIllegal©2013-2022 Tencent Cloud. All rights reserved.

exceeds the limit. One person can have up to 5
face images.
An error occurred while setting person gender.
0: empty; 1: male; 2: female.
The person ID already exists. It must be unique.
The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

Page 203 of 321

Face Recognition

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal
InvalidParameterValue.PersonNameTooLong
InvalidParameterValue.SearchPersonsExceed

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.
The person name exceeds the length limit.
The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 204 of 321

Face Recognition

ModifyPersonBaseInfo：

Last updated 2022-01-28 15:42:43

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to modify the information of a person, including name, gender, etc. The changes of person name andgender will be synced to all the groups that contain the person.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
This document describes the parameters for Signature V1. It's recommended to use the V3 signature, which provides
higher security. Note that for Signature V3, the common parameters need to be placed in the HTTP Header. See
details.
Parameter
Name

RequiredType

ActionYes

String

VersionYes

StringCommon parameter. The value used for this API: 2020-03-03.

RegionYes

StringCommon parameter. For more information, please see the list ofregions supported by the product.

PersonId

Yes

StringPerson ID, which is the PersonId in the CreatePerson API.

PersonName

No

StringName of the person to be modified

GenderNo

Integer

Gender of the person to be modified. 1: male; 2: female.

Description
Common parameter. The value used for this API:
ModifyPersonBaseInfo.

©2013-2022 Tencent Cloud. All rights reserved.

Page 205 of 321

Face Recognition

3. Output Parameters
Parameter
Name
RequestId

Type

StringDescription
The unique request ID, which is returned for each request. RequestId is required forlocating a problem.

4. Example
Example1 Modifying the basic information of person
Input Example
https://iai.tencentcloudapi.com/?Action=ModifyPersonBaseInfo&PersonId=2001&PersonName=JunlyWang&Gender=1&<Common request parameters>

Output Example{"Response": {"RequestId": "6e2a0fb7-7c9e-45c7-abf1-338457d1def7"}}

Example2 Modifying the basic information of person - 2
Input Example
https://iai.tencentcloudapi.com/?Action=ModifyPersonBaseInfo&PersonId=1001&PersonName=EvanLiao&Gender=1&<Common request parameters>

Output Example©2013-2022 Tencent Cloud. All rights reserved.

Page 206 of 321

Face Recognition{"Response": {"RequestId": "6e2a0fb7-7c9e-45c7-abf1-338457d1def7"}}

Example3 Sample error
This example shows the error that will occur if the gender of a person is incorrectly set.
Input Example
https://iai.tencentcloudapi.com/?Action=ModifyPersonBaseInfo&PersonId=1001&Gender=-1&<Common request parameters>

Output Example{"Response": {"RequestId": "f40bf659-0283-4773-abe8-945f643d5015"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface©2013-2022 Tencent Cloud. All rights reserved.

Page 207 of 321

Face Recognition

Tencent Cloud CLI 3.0

6. Error CodeThe following only lists the error codes related to the API business logic. For other error codes, see Common Error
Codes.
Error Code
FailedOperation.ConflictOperation

FailedOperation.DuplicatedGroupDescription
FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist

Description
The operations conflict. Do not operate on thesame person simultaneously.
The custom description field must be unique inthe group.
The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

FailedOperation.ServerError

The number of faces searched for exceeds thelimit.
The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

©2013-2022 Tencent Cloud. All rights reserved.

Page 208 of 321

Face Recognition

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.

InvalidParameterValue.GroupExDescriptionsExceed

The array length of the group's custom
description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdenticalInvalidParameterValue.GroupExDescriptionsNameIllegal

The name of the group's custom description
field must be unique.
The name of the group's custom description
field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed

The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.

InvalidParameterValue.GroupIdAlreadyExist

The group ID already exists. It must be unique.

InvalidParameterValue.GroupIdIllegal

The group ID contains invalid characters. It cancontain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal
InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed
InvalidParameterValue.GroupNumPerPersonExceed©2013-2022 Tencent Cloud. All rights reserved.

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.
The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One

Page 209 of 321

Face Recognition

person can be added to up to 100 groups.
The group remarks field contains invalid
InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

The group remarks field exceeds the length
limit.
Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

InvalidParameterValue.PersonExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields are allowed.
The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroupThe name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.

InvalidParameterValue.PersonIdAlreadyExist

The person ID already exists. It must be unique.

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It©2013-2022 Tencent Cloud. All rights reserved.

Page 210 of 321

Face Recognition

can contain only letters, digits, and -%@#&_.
InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 211 of 321

Face Recognition

CopyPerson：

Last updated 2023-02-27 15:22:51

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: CopyPerson.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

PersonId

Yes

StringPerson ID, which is the PersonId in the CreatePerson API.

GroupIds.N

Yes

Array of

List of groups to join. The array element value is the GroupId in

Stringthe CreateGroup API.

Name

©2013-2022 Tencent Cloud. All rights reserved.

Page 212 of 321

Face Recognition

3. Output Parameters
Parameter
Name
SucGroupNum
SucGroupIds

RequestId

Type

Description

IntegerNumber of groups successfully added to.

Array of
StringStringList of groups successfully added to.
The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

4. Example
Example1 Copying person
Input Example
https://iai.tencentcloudapi.com/?Action=CopyPerson&PersonId=2001&GroupIds.0=TencentShenZhenEmployee&GroupIds.1=ShenZhenCitizen&<Common request parameters>

Output Example{"Response": {"SucGroupNum": 2,"SucGroupIds": ["ShenZhenCitizen","TencentShenZhenEmployee"],"RequestId": "9841c008-e597-4356-a8d5-c47a246abd8d"}}

Example2 Sample error
Input Example©2013-2022 Tencent Cloud. All rights reserved.

Page 213 of 321

Face Recognition

https://iai.tencentcloudapi.com/?Action=CopyPerson&PersonId=1001&GroupIds.0=TencentShenZhenEmployee&GroupIds.1=ZhuYuanDormitoryNo1&<Common request parameters>

Output Example{"Response": {"RequestId": "8ecfa566-68a9-4eb5-a6da-95ba9be26947"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

6. Error CodeThe following only lists the error codes related to the API business logic. For other error codes, see Common Error
Codes.
Error Code©2013-2022 Tencent Cloud. All rights reserved.

Description

Page 214 of 321

Face Recognition

FailedOperation.AcrossVersionsError

FailedOperation.ConflictOperation
FailedOperation.CreateFaceConcurrent
FailedOperation.DuplicatedGroupDescription
FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist

FailedOperation.GroupPersonMapNotExist

This operation cannot be performed acrossalgorithm model versions.
The operations conflict. Do not operate on thesame person simultaneously.
Faces cannot be added concurrently.
The custom description field must be unique inthe group.
The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.
The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.

©2013-2022 Tencent Cloud. All rights reserved.

Page 215 of 321

Face Recognition

InvalidParameterValue.GroupExDescriptionsExceed

The array length of the group's custom
description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

InvalidParameterValue.GroupNameIllegal
InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

The group name already exists. It must be
unique.
The group name contains invalid characters. It
can contain only letters, - , _ , and digits.
The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalid

InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong©2013-2022 Tencent Cloud. All rights reserved.

The group remarks field exceeds the length

Page 216 of 321

Face Recognition

limit.
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

InvalidParameterValue.PersonExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields are allowed.
The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroup

field contains invalid characters. It can contain
only letters, - , _ , and digits.
The name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

InvalidParameterValue.PersonGenderIllegal
InvalidParameterValue.PersonIdAlreadyExist
InvalidParameterValue.PersonIdIllegal

exceeds the limit. One person can have up to 5
face images.
An error occurred while setting person gender.
0: empty; 1: male; 2: female.
The person ID already exists. It must be unique.
The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It©2013-2022 Tencent Cloud. All rights reserved.

Page 217 of 321

Face Recognition

can contain only letters, - , _ , and digits.
InvalidParameterValue.PersonNameTooLong
InvalidParameterValue.SearchPersonsExceed

The person name exceeds the length limit.
The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 218 of 321

Face Recognition

CreateFace：

Last updated 2023-02-27 15:22:51

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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 .
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: CreateFace.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

PersonId

Yes

StringImages.N

No

Array

Base64-encoded image data, which cannot exceed 5 MB.

of

The long side cannot exceed 4,000 px for images in JPG

Stringformat or 2,000 px for images in other formats.

©2013-2022 Tencent Cloud. All rights reserved.

Person ID, which is the PersonId in theCreatePerson API.

Page 219 of 321

Face Recognition

A person can have up to 5 face images.
If there are multiple faces in the image, only the face with thelargest size will be selected.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
Image URL. The image cannot exceed 5 MB in size after
being Base64-encoded.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Either Url or Image must be provided; if both areprovided, only Url will be used.
Array
Urls.N

No

of
StringWe recommend storing the image in Tencent Cloud, as aTencent Cloud URL can guarantee higher download speed
and stability.
The download speed and stability of non-Tencent Cloud
URLs may be low.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
A person can have up to 5 face images.
If there are multiple faces in the image, only the face with thelargest size will be selected.
Only faces whose similarity to an existing face of the person is

FaceMatchThreshold

No

Float

above the value of FaceMatchThreshold can be added
successfully.
Default value: 60. Value range: [0,100].

QualityControl

No

Integer

Image quality control.
0: no control.
1: low quality requirement. The image has one or more of thefollowing problems: extreme blurriness, covered eyes,covered nose, and covered mouth.
2: average quality requirement. The image has at least threeof the following problems: excessive brightness, excessive
dimness, blurriness or average blurriness, covered eyebrows,
covered cheeks, and covered chin.
3: high-quality requirement. The image has one to two of thefollowing problems: excessive brightness, excessive dimness,average blurriness, covered eyebrows, covered cheeks, andcovered chin.
4: very high-quality requirement. The image is optimal in all
dimensions or only has a slight problem in one dimension.
Default value: 0.
If the image quality does not meet the requirement, the©2013-2022 Tencent Cloud. All rights reserved.

Page 220 of 321

Face Recognition

returned result will prompt that the detected image quality is
unsatisfactory.
Whether to enable the support for rotated image recognition.
0: no; 1: yes. Default value: 0. When the face in the image isrotated and the image has no EXIF information, if this
NeedRotateDetection

No

Integerparameter is not enabled, the face in the image cannot becorrectly detected and recognized. If you are sure that the
input image contains EXIF information or the face in theimage will not be rotated, do not enable this parameter, as theoverall time consumption may increase by hundreds ofmilliseconds after it is enabled.

3. Output Parameters
Parameter NameType

Description

SucFaceNum

IntegerNumber of successfully added faces

SucFaceIds

Array of
StringList of IDs of successfully added faces
Adding result for each face image. -1101: no face detected; -1102: image
decoding failed;

RetCodeArray ofInteger-1601: the image quality control requirement is not met; -1604: the facesimilarity is not above FaceMatchThreshold .
Other non-zero values: algorithm service exception.
The order of RetCode values is the same as the order of Images or
Urls in the input parameter.
Indexes of successfully added faces. The order of indexes is the same as

SucIndexes

Array ofthe order of Images or Urls in the input parameter.

Integer

For example, if there are 3 URLs in Urls , and the second URL fails,
then the value of SucIndexes will be [0,2].

SucFaceRects

Array of
FaceRect

Frame positions of successfully added faces. The order is the same as theorder of Images or Urls in the input parameter.

FaceModelVersion

StringAlgorithm model version used for face recognition.

RequestId

String

The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

©2013-2022 Tencent Cloud. All rights reserved.

Page 221 of 321

Face Recognition

4. Example
Example1 Adding faces
This example shows you how to add a group of face images to a person.
Input Example
https://iai.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"}}

Example2 Sample error
This example shows the error that will occur if a person has more than 5 face images.
Input Example©2013-2022 Tencent Cloud. All rights reserved.

Page 222 of 321

Face Recognition

https://iai.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": {"RequestId": "44506f79-2191-49bc-997b-748a566d781c"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

6. Error Code©2013-2022 Tencent Cloud. All rights reserved.

Page 223 of 321

Face Recognition

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

AuthFailure.InvalidAuthorization

Authentication failed.

FailedOperation.ConflictOperation
FailedOperation.CreateFaceConcurrent
FailedOperation.DuplicatedGroupDescription

The operations conflict. Do not operate on thesame person simultaneously.
Faces cannot be added concurrently.
The custom description field must be unique inthe group.
The face frame size is smaller than the

FailedOperation.FaceSizeTooSmall

MinFaceSize value, and the face is filtered
out.

FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist

FailedOperation.GroupPersonMapNotExist

The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.
The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

FailedOperation.ImageResolutionTooSmall

The image short edge resolution is smaller than64.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed©2013-2022 Tencent Cloud. All rights reserved.

The number of faces searched for exceeds thelimit.

Page 224 of 321

Face Recognition

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.

InvalidParameterValue.FaceMatchThresholdIllegal

Invalid FaceMatchThreshold parameter.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

The name of the group's custom description
field exceeds the length limit.

InvalidParameterValue.GroupFaceNumExceed

The number of faces in the group exceeds thelimit.

InvalidParameterValue.GroupIdAlreadyExist

The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist©2013-2022 Tencent Cloud. All rights reserved.

The group name already exists. It must be
unique.

Page 225 of 321

Face Recognition

InvalidParameterValue.GroupNameIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalid

InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong

The group remarks field exceeds the length
limit.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.LimitExceed

The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdentical

The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

The name of the person's custom description
field exceeds the length limit.

InvalidParameterValue.PersonExistInGroupThe ID of the corresponding person is alreadyin the group.

InvalidParameterValue.PersonFaceNumExceed

The number of face images for the person©2013-2022 Tencent Cloud. All rights reserved.

Page 226 of 321

Face Recognition

exceeds the limit. One person can have up to 5
face images.
InvalidParameterValue.PersonGenderIllegal
InvalidParameterValue.PersonIdAlreadyExist
InvalidParameterValue.PersonIdIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.
The person ID already exists. It must be unique.
The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.QualityControlIllegal

Invalid QualityControl parameter.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing
ResourceUnavailable.UnknownStatus©2013-2022 Tencent Cloud. All rights reserved.

The resource has been repossessed.
The service has been suspended for theaccount.
The billing status is unknown.

Page 227 of 321

Face Recognition

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 228 of 321

Face Recognition

DeleteFace：

Last updated 2023-02-27 15:22:50

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: DeleteFace.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

PersonId

Yes

StringPerson ID, which is the PersonId in the CreatePerson API.

Yes

Array
of

Name

FaceIds.N

StringList of IDs of the faces to be deleted. The array element value is the
FaceId returned by the CreateFace API.

3. Output Parameters
Parameter
Name

Type

Description©2013-2022 Tencent Cloud. All rights reserved.

Page 229 of 321

Face Recognition

SucDeletedNum
SucFaceIds

RequestId

IntegerArray of
StringStringNumber of successfully deleted faces
List of IDs of successfully deleted faces
The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

4. Example
Example1 Deleting faces
This example shows you how to delete the face images under a person.
Input Example
https://iai.tencentcloudapi.com/?Action=DeleteFace&PersonId=1001&FaceIds.0=2875186538564559728&<Common request parameters>

Output Example{"Response": {"SucDeletedNum": 1,"SucFaceIds": ["2875186538564559728"],"RequestId": "38f96439-d5ea-48ea-899b-44a284708f6b"}}

Example2 Sample error
This example shows the error that will occur if a person ID does not exist.
Input Example
https://iai.tencentcloudapi.com/?Action=DeleteFace&PersonId=5001&FaceIds.0=2875186538564559728&<Common request parameters>©2013-2022 Tencent Cloud. All rights reserved.

Page 230 of 321

Face Recognition

Output Example{"Response": {"RequestId": "e2b603e5-51d0-4a8a-8319-2df026ae7518"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

6. Error CodeThe following only lists the error codes related to the API business logic. For other error codes, see Common Error
Codes.
Error Code
FailedOperation.ConflictOperation
FailedOperation.CreateFaceConcurrent
FailedOperation.DuplicatedGroupDescription©2013-2022 Tencent Cloud. All rights reserved.

Description
The operations conflict. Do not operate on thesame person simultaneously.
Faces cannot be added concurrently.
The custom description field must be unique inthe group.

Page 231 of 321

Face Recognition

FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist

The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

FailedOperation.ServerError

The number of faces searched for exceeds thelimit.
The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

©2013-2022 Tencent Cloud. All rights reserved.

Page 232 of 321

Face Recognition

InvalidParameterValue.GroupExDescriptionsNameTooLong

The name of the group's custom description
field exceeds the length limit.

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.GroupNameTooLong

The group name exceeds the length limit.

InvalidParameterValue.GroupNumExceed

The number of groups exceeds the limit. If you
need more, please contact us.

InvalidParameterValue.GroupNumPerPersonExceed

The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalid

InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong

The group remarks field exceeds the length
limit.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.LimitExceed

The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please check©2013-2022 Tencent Cloud. All rights reserved.

Page 233 of 321

Face Recognition

the length of the array to be requested.
The array length of the person's custom
InvalidParameterValue.PersonExDescriptionInfosExceed

description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdentical

The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroup

InvalidParameterValue.PersonFaceNumExceed

The name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person
exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal
InvalidParameterValue.PersonIdAlreadyExist
InvalidParameterValue.PersonIdIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.
The person ID already exists. It must be unique.
The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

©2013-2022 Tencent Cloud. All rights reserved.

Page 234 of 321

Face Recognition

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 235 of 321

Face Recognition

Face Search APIs
SearchFaces：

Last updated 2023-02-27 15:50:37

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to recognize top K persons in one or more groups who are similar to the person in a given image andrank the similarity in 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 algorithm model version( FaceModelVersion ) of groups, 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 andSearchPersonsReturnsByGroup 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 theperson to make the search more accurate.
This API should be used together with Group Management APIs.
Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set theparameter SignatureMethod to TC3-HMAC-SHA256 .
You cannot search for groups using different algorithm model versions ( FaceModelVersion ) at a time.

We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.

©2013-2022 Tencent Cloud. All rights reserved.

Page 236 of 321

Face Recognition

Parameter Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: SearchFaces.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.
List of groups to be searched in (up to 100). The array

GroupIds.N

Yes

Array

element value is the GroupId in the CreateGroup

of

API.

String

You cannot search for groups using different algorithm modelversions ( FaceModelVersion ) at a time.
Base64-encoded image data, which cannot exceed 5 MB.

Image

No

String

The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
Image URL. The image cannot exceed 5 MB in size after
being Base64-encoded.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Either Url or Image must be provided; if both areprovided, only Url will be used.

Url

No

StringWe recommend storing the image in Tencent Cloud, as aTencent Cloud URL can guarantee higher download speed
and stability.
The download speed and stability of non-Tencent Cloud
URLs may be low.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
Maximum number of recognizable faces. Default value: 1 (i.e.,
detecting only the face with the largest size in the image).
Maximum value: 10.
MaxFaceNum is used to control the number of faces to be

MaxFaceNum

No

Integer

searched for if there are multiple faces in the input image tobe recognized.
For example, if the input image in Image or Url
contains multiple faces and MaxFaceNum is 5, top 5 faces
with the largest size in the image will be recognized.

©2013-2022 Tencent Cloud. All rights reserved.

Page 237 of 321

Face Recognition

Parameter Name

RequiredType

Description
Minimum height and width of face in px. Default value: 34.

MinFaceSize

No

IntegerFace images whose value is below 34 cannot be recognized.
We recommend setting this parameter to 80.
Number of the most similar persons returned for one single
recognized face image. Default value: 5. Maximum value:
100.

MaxPersonNum

No

Integer

For example, if MaxFaceNum is 1 and MaxPersonNum
is 8, information of the top 8 most similar persons will be
returned.
The greater the value, the longer the processing time. We
recommend setting a value below 10.

NeedPersonInfo

No

Integer

Whether to return person details. 0: no; 1: yes. Default value:
0. Other values will be considered as 0 by default.
Image quality control.
0: no control.
1: low quality requirement. The image has one or more of thefollowing problems: extreme blurriness, covered eyes,covered nose, and covered mouth.
2: average quality requirement. The image has at least threeof the following problems: excessive brightness, excessive
dimness, blurriness or average blurriness, covered eyebrows,
covered cheeks, and covered chin.

QualityControl

No

Integer

3: high-quality requirement. The image has one to two of thefollowing problems: excessive brightness, excessive dimness,average blurriness, covered eyebrows, covered cheeks, andcovered chin.
4: very high-quality requirement. The image is optimal in all
dimensions or only has a slight problem in one dimension.
Default value: 0.
If the image quality does not meet the requirement, thereturned result will prompt that the detected image quality is
unsatisfactory.
In the output parameter Score , the result will be returned

FaceMatchThreshold

No

Float

only if the result value is above the
FaceMatchThreshold value. Default value: 0.

©2013-2022 Tencent Cloud. All rights reserved.

Page 238 of 321

Face Recognition

Parameter Name

RequiredType

Description
Whether to enable the support for rotated image recognition.
0: no; 1: yes. Default value: 0. When the face in the image isrotated and the image has no EXIF information, if thisparameter is not enabled, the face in the image cannot be

NeedRotateDetection

No

Integercorrectly detected and recognized. If you are sure that the
input image contains EXIF information or the face in theimage will not be rotated, do not enable this parameter, as theoverall time consumption may increase by hundreds ofmilliseconds after it is enabled.

3. Output Parameters
Parameter Name
Results

Type
Array ofResultDescription
Recognition result.

FaceNum

IntegerNumber of faces included in searched groups.

FaceModelVersion

StringAlgorithm model version used for face recognition.

RequestId

String

The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

4. Example
Example1 Searching for face
Input Example
https://iai.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©2013-2022 Tencent Cloud. All rights reserved.

Page 239 of 321

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

Example2 Sample error
MaxFaceNum cannot be above 10.
Input Example
https://iai.tencentcloudapi.com/?Action=SearchFaces&Url=http://test.image.myqcloud.com/testA.jpg&MaxFaceNum=11©2013-2022 Tencent Cloud. All rights reserved.

Page 240 of 321

Face Recognition&GroupIds.0=TencentShenZhenEmployee&<Common request parameters>

Output Example{"Response": {"RequestId": "f04ba2f3-532c-4207-9caa-6e818ded7fb9"}}

Example3 Sample error - 2
This example shows the error that will occur if an image URL is incorrect.
Input Example
https://iai.tencentcloudapi.com/?Action=SearchFaces&Url=http://test.image.myqcloud.com/testA&GroupIds.0=TencentShenZhenEmployee&<Common request parameters>

Output Example{"Response": {"RequestId": "527ecffe-4c6a-47c9-8217-4dd2e3f018da"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS©2013-2022 Tencent Cloud. All rights reserved.

Page 241 of 321

Face Recognition

Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

AuthFailure.InvalidAuthorization

Authentication failed.

FailedOperation.AcrossVersionsError

FailedOperation.ConflictOperation

FailedOperation.DuplicatedGroupDescription

This operation cannot be performed acrossalgorithm model versions.
The operations conflict. Do not operate on thesame person simultaneously.
The custom description field must be unique inthe group.
The face frame size is smaller than the

FailedOperation.FaceSizeTooSmall

MinFaceSize value, and the face is filtered
out.

FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist

FailedOperation.GroupPersonMapNotExist

The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.
The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

©2013-2022 Tencent Cloud. All rights reserved.

Page 242 of 321

Face Recognition

Error CodeDescription

FailedOperation.ImageResolutionTooSmall

The image short edge resolution is smaller than64.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.

InvalidParameterValue.FaceMatchThresholdIllegal

Invalid FaceMatchThreshold parameter.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed©2013-2022 Tencent Cloud. All rights reserved.

The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.

Page 243 of 321

Face Recognition

Error CodeDescription

InvalidParameterValue.GroupIdAlreadyExist

The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

InvalidParameterValue.GroupNameIllegal
InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

The group name already exists. It must be
unique.
The group name contains invalid characters. It
can contain only letters, - , _ , and digits.
The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalid

InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

The group remarks field exceeds the length
limit.
Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed©2013-2022 Tencent Cloud. All rights reserved.

The starting number is too large. Please checkthe length of the array to be requested.

Page 244 of 321

Face Recognition

Error CodeDescription
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdentical

The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroupThe name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.

InvalidParameterValue.PersonIdAlreadyExist

The person ID already exists. It must be unique.

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.QualityControlIllegal

Invalid QualityControl parameter.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

©2013-2022 Tencent Cloud. All rights reserved.

Page 245 of 321

Face Recognition

Error CodeDescription

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 246 of 321

Face Recognition

SearchFacesReturnsByGroup：

Last updated 2023-02-27 15:22:52

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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 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 modelversion ( 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 andSearchPersonsReturnsByGroup 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 theperson to make the search more accurate.
This API should be used together with Group Management APIs.

Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the
SignatureMethod parameter to TC3-HMAC-SHA256 .

You cannot search for groups using different algorithm model versions ( FaceModelVersion ) at a time.

We recommend you to use API Explorer
Try itAPI 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©2013-2022 Tencent Cloud. All rights reserved.

Page 247 of 321

Face Recognition

The following request parameter list only provides API request parameters and some common parameters. For thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API:
SearchFacesReturnsByGroup.

VersionYes

StringRegionNo

StringArray
GroupIds.N

Yesof
StringCommon Params. The value used for this API: 2020-0303.
Common Params. This parameter is not required for thisAPI.
List of groups to be searched in (up to 60). The arrayelement value is the GroupId in theCreateGroup API.
You cannot search for groups using different algorithm
model versions ( FaceModelVersion ) at a time.
Base64-encoded image data, which cannot exceed 5

Image

No

String

MB.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
PNG, JPG, JPEG, and BMP images are supported, while
GIF images are not.
Image URL. The image cannot exceed 5 MB in size after
being Base64-encoded.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Either Url or Image must be provided; if both areprovided, only Url will be used.

Url

No

StringWe recommend storing the image in Tencent Cloud, as aTencent Cloud URL can guarantee higher download
speed and stability.
The download speed and stability of non-Tencent Cloud
URLs may be low.
PNG, JPG, JPEG, and BMP images are supported, while
GIF images are not.

MaxFaceNum

No

IntegerMaximum number of recognizable faces. Default value: 1(i.e., detecting only the face with the largest size in theimage). Maximum value: 10.
MaxFaceNum is used to control the number of faces tobe searched for if there are multiple faces in the input©2013-2022 Tencent Cloud. All rights reserved.

Page 248 of 321

Face Recognition

image to be recognized.
For example, if the input image in Image or Url
contains multiple faces and MaxFaceNum is 5, top 5
faces with the largest size in the image will berecognized.
Minimum height and width of face in px. Default value:
MinFaceSize

No

Integer

34. A value below 34 will affect the search accuracy. We
recommend setting this parameter to 80.
Detected faces, which is corresponding to the maximum
number of returned most matching persons. Default
value: 5. Maximum value: 10.

MaxPersonNumPerGroupNo

Integer

For example, if MaxFaceNum is 3,
MaxPersonNumPerGroup is 5, and theGroupIds length is 3, up to 45 (3 * 5 * 3) persons will
be returned.

NeedPersonInfo

No

Integer

Whether to return person details. 0: no; 1: yes. Default
value: 0. Other values will be considered as 0 by default.
Image quality control.
0: no control.
1: low quality requirement. The image has one or more of
the following problems: extreme blurriness, covered eyes,covered nose, and covered mouth.
2: average quality requirement. The image has at least
three of the following problems: excessive brightness,
excessive dimness, blurriness or average blurriness,covered eyebrows, covered cheeks, and covered chin.

QualityControl

No

Integer

3: high-quality requirement. The image has one to two of
the following problems: excessive brightness, excessive
dimness, average blurriness, covered eyebrows, covered
cheeks, and covered chin.
4: very high-quality requirement. The image is optimal in
all dimensions or only has a slight problem in one
dimension.
Default value: 0.
If the image quality does not meet the requirement, thereturned result will prompt that the detected image quality
is unsatisfactory.

FaceMatchThreshold

No

Float

In the output parameter Score , the result will be
returned only if the result value is greater than or equal to
the FaceMatchThreshold value.

©2013-2022 Tencent Cloud. All rights reserved.

Page 249 of 321

Face Recognition

Default value: 0.
Value range: [0.0,100.0).
Whether to enable the support for rotated image
recognition. 0: no; 1: yes. Default value: 0. When the facein the image is rotated and the image has no EXIF
information, if this parameter is not enabled, the face in
NeedRotateDetection

No

Integerthe image cannot be correctly detected and recognized. If
you are sure that the input image contains EXIF
information or the face in the image will not be rotated, do
not enable this parameter, as the overall time
consumption may increase by hundreds of milliseconds
after it is enabled.

3. Output Parameters
Parameter NameType

Description

FaceNum

IntegerNumber of faces included in searched groups.

ResultsReturnsByGroup

Array ofResultsReturnsByGroup

Recognition result.

FaceModelVersion

StringAlgorithm model version used for face recognition.

RequestId

String

The unique request ID, which is returned for eachrequest. RequestId is required for locating a problem.

4. Example
Example1 Searching for faces with results returned by group
Input Example
POST / HTTP/1.1
Host: iai.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: SearchFacesReturnsByGroup<Common request parameters>{"Url": "http://test.image.myqcloud.com/testA.jpg",©2013-2022 Tencent Cloud. All rights reserved.

Page 250 of 321

Face Recognition"MaxPersonNumPerGroup": "5","GroupIds": ["TencentShenZhenEmployee"],"MaxFaceNum": "1",
"MinFaceSize": "40"}Output Example{"Response": {"FaceNum": 1,"ResultsReturnsByGroup": [{"GroupCandidates": [{"Candidates": [{"PersonGroupInfos": [{"GroupId": "abc","PersonExDescriptions": ["description1","description2"]}],"PersonId": "1001","Gender": 0,"PersonName": "John Smith","Score": 100,
"FaceId": "2875093635484912302"}],"GroupId": "Group1"}],"FaceRect": {"Y": 46,"X": 370,"Height": 1,"Width": 1},"RetCode": 0}©2013-2022 Tencent Cloud. All rights reserved.

Page 251 of 321

Face Recognition],"RequestId": "57b42b73-b978-45b9-8095-8f50e9642d35","FaceModelVersion": "3.0"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

AuthFailure.InvalidAuthorization

Authentication failed.

FailedOperation.AcrossVersionsError

FailedOperation.ConflictOperation
FailedOperation.DuplicatedGroupDescription

This operation cannot be performed acrossalgorithm model versions.
The operations conflict. Do not operate on thesame person simultaneously.
The custom description field must be unique inthe group.

©2013-2022 Tencent Cloud. All rights reserved.

Page 252 of 321

Face Recognition

The face frame size is smaller than the
FailedOperation.FaceSizeTooSmall

MinFaceSize value, and the face is filtered
out.

FailedOperation.GroupInDeletedStateThe current group is being deleted. Please wait.

FailedOperation.GroupPersonMapExist

The ID of the corresponding person is alreadyin the group.

FailedOperation.GroupPersonMapNotExist

The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

FailedOperation.ImageResolutionTooSmall

FailedOperation.ImageSizeExceed

The image short edge resolution is smaller than64.
The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

FailedOperation.ServerError

The number of faces searched for exceeds thelimit.
The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.

InvalidParameterValue.FaceMatchThresholdIllegal©2013-2022 Tencent Cloud. All rights reserved.

Invalid FaceMatchThreshold parameter.

Page 253 of 321

Face Recognition

InvalidParameterValue.GroupExDescriptionsExceed

The array length of the group's custom
description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

field contains invalid characters. It can contain
only letters, - , _ , and digits.
The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

InvalidParameterValue.GroupNameIllegal
InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

InvalidParameterValue.GroupTagIllegal

The group name already exists. It must be
unique.
The group name contains invalid characters. It
can contain only letters, - , _ , and digits.
The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalidcharacters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong©2013-2022 Tencent Cloud. All rights reserved.

The group remarks field exceeds the length

Page 254 of 321

Face Recognition

limit.
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdentical

The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroup

InvalidParameterValue.PersonFaceNumExceed

The name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person
exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal
InvalidParameterValue.PersonIdAlreadyExist
InvalidParameterValue.PersonIdIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.
The person ID already exists. It must be unique.
The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It©2013-2022 Tencent Cloud. All rights reserved.

Page 255 of 321

Face Recognition

can contain only letters, - , _ , and digits.
InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.QualityControlIllegal

Invalid QualityControl parameter.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 256 of 321

Face Recognition

SearchPersons：

Last updated 2023-02-27 15:22:52

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to recognize top K persons in one or more groups who are similar to the person in a given image andrank 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 modelversion ( 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 thefeatures 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, theSearchFaces and SearchFacesReturnsByGroup 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.

We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType©2013-2022 Tencent Cloud. All rights reserved.

Description

Page 257 of 321

Face Recognition

ActionYes

StringCommon Params. The value used for this API:
SearchPersons.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

Array

List of groups to be searched in (up to 100). The arrayofelement value is the GroupId in the CreateGroup

StringAPI.

GroupIds.N

Yes

Base64-encoded image data, which cannot exceed 5 MB.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Image

No

StringIf there are multiple faces in the image, only the face with thelargest size will be selected.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
Image URL. The image cannot exceed 5 MB in size after
being Base64-encoded.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Either Url or Image must be provided; if both areprovided, only Url will be used.

Url

No

StringWe recommend storing the image in Tencent Cloud, as aTencent Cloud URL can guarantee higher download speed
and stability.
The download speed and stability of non-Tencent Cloud
URLs may be low.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
Maximum number of recognizable faces. Default value: 1 (i.e.,
detecting only the face with the largest size in the image).
Maximum value: 10.
MaxFaceNum is used to control the number of faces to be

MaxFaceNum

No

Integer

searched for if there are multiple faces in the input image tobe recognized.
For example, if the input image in Image or Url
contains multiple faces and MaxFaceNum is 5, top 5 faces
with the largest size in the image will be recognized.

MinFaceSize

No

Integer

Minimum height and width of face in px. Default value: 34. A
value below 34 will affect the search accuracy. We
recommend setting this parameter to 80.

©2013-2022 Tencent Cloud. All rights reserved.

Page 258 of 321

Face Recognition

Number of the most similar persons returned for one single
recognized face image. Default value: 5. Maximum value:

MaxPersonNum

No

Integer

100.
For example, if MaxFaceNum is 1 and MaxPersonNum
is 8, information of the top 8 most similar persons will be
returned.
The greater the value, the longer the processing time. We
recommend setting a value below 10.
Image quality control.
0: no control.
1: low quality requirement. The image has one or more of thefollowing problems: extreme blurriness, covered eyes,covered nose, and covered mouth.
2: average quality requirement. The image has at least threeof the following problems: excessive brightness, excessive
dimness, blurriness or average blurriness, covered eyebrows,
covered cheeks, and covered chin.

QualityControl

No

Integer

3: high-quality requirement. The image has one to two of thefollowing problems: excessive brightness, excessive dimness,average blurriness, covered eyebrows, covered cheeks, andcovered chin.
4: very high-quality requirement. The image is optimal in all
dimensions or only has a slight problem in one dimension.
Default value: 0.
If the image quality does not meet the requirement, thereturned result will prompt that the detected image quality is
unsatisfactory.
In the output parameter Score , the result will be returned

FaceMatchThreshold

No

Float

only if the result value is greater than or equal to theFaceMatchThreshold value. Default value: 0. Value
range: [0.0,100.0).

NeedPersonInfo

No

Integer

NeedRotateDetection

No

Integer

Whether to return person details. 0: no; 1: yes. Default value:
0. Other values will be considered as 0 by default.
Whether to enable the support for rotated image recognition.
0: no; 1: yes. Default value: 0. When the face in the image isrotated and the image has no EXIF information, if thisparameter is not enabled, the face in the image cannot becorrectly detected and recognized. If you are sure that the
input image contains EXIF information or the face in theimage will not be rotated, do not enable this parameter, as the©2013-2022 Tencent Cloud. All rights reserved.

Page 259 of 321

Face Recognition

overall time consumption may increase by hundreds ofmilliseconds after it is enabled.

3. Output Parameters
Parameter NameType

Description

Array
Resultsof

Recognition result.

ResultPersonNum

Integer

FaceModelVersion

StringRequestId

StringNumber of the persons included in searched groups. If the quality of all faces
in the input image does not meet the requirement, 0 will be returned.
Algorithm model version used for face recognition.
Note: this field may return null, indicating that no valid values can be obtained.
The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

4. Example
Example1 Searching for person
Input Example
https://iai.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,©2013-2022 Tencent Cloud. All rights reserved.

Page 260 of 321

Face Recognition"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": "",©2013-2022 Tencent Cloud. All rights reserved.

Page 261 of 321

Face Recognition"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"}}

Example2 Sample error
This example shows the error that will occur if an image URL is incorrect.
Input Example
https://iai.tencentcloudapi.com/?Action=SearchPersons&Url=http://test.image.myqcloud.com/testA&GroupIds.0=TencentShenZhenEmployee&<Common request parameters>

Output Example{"Response": {"RequestId": "527ecffe-4c6a-47c9-8217-4dd2e3f018da"}}©2013-2022 Tencent Cloud. All rights reserved.

Page 262 of 321

Face Recognition

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

AuthFailure.InvalidAuthorization

Authentication failed.

FailedOperation.AcrossVersionsError

This operation cannot be performed acrossalgorithm model versions.
The face frame size is smaller than the

FailedOperation.FaceSizeTooSmall

MinFaceSize value, and the face isfiltered out.

FailedOperation.ImageDecodeFailed
FailedOperation.ImageDownloadError
FailedOperation.ImageFacedetectFailed©2013-2022 Tencent Cloud. All rights reserved.

Image decoding failed.
An error occurred while downloading theimage.
Face detection failed.

Page 263 of 321

Face Recognition

FailedOperation.ImageResolutionExceed
FailedOperation.ImageResolutionTooSmall

FailedOperation.ImageSizeExceed

The image resolution is too high.
The image short edge resolution is smaller
than 64.
The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

FailedOperation.ServerError

The number of faces searched for exceeds thelimit.
The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.FaceMatchThresholdIllegal

Invalid FaceMatchThreshold parameter.

InvalidParameterValue.GroupIdIllegal

The group ID contains invalid characters. It
can contain only letters, digits, and special
symbols (-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.ImageEmptyError

Empty image.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.QualityControlIllegal

Invalid QualityControl parameter.

InvalidParameterValue.SearchPersonsExceed

InvalidParameterValue.UnsupportedGroupFaceModelVersion©2013-2022 Tencent Cloud. All rights reserved.

The number of persons searched for exceeds
the limit.
This operation is not supported by algorithm
model v2.0 or below.

Page 264 of 321

Face Recognition

InvalidParameterValue.UrlIllegal

Invalid URL format.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.ChargeStatusException

The account is in arrears.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.GetAuthInfoError

Failed to get the authentication information.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.LowBalanceInsufficient balance.

ResourceUnavailable.NotExist

The billing status is unknown. Please check
whether the service has been activated in the
console.

ResourceUnavailable.NotReady

The service is not activated.

ResourceUnavailable.Recover

The resource has been repossessed.

ResourceUnavailable.StopUsing

The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 265 of 321

Face Recognition

SearchPersonsReturnsByGroup：

Last updated 2023-02-27 15:22:52

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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 modelversion ( 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 thefeatures 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, theSearchFaces and SearchFacesReturnsByGroup 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.

We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

Required©2013-2022 Tencent Cloud. All rights reserved.

Type

Description

Page 266 of 321

Face Recognition

ActionYes

String

VersionYes

StringRegionNo

StringYes

SearchPersonsReturnsByGroup.
Common Params. The value used for this API: 2020-0303.
Common Params. This parameter is not required for this
API.

of

List of groups to be searched in (up to 60). The arrayelement value is the GroupId in theStringCreateGroup API.

Array
GroupIds.N

Common Params. The value used for this API:

Base64-encoded image data, which cannot exceed 5

Image

No

String

MB.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
PNG, JPG, JPEG, and BMP images are supported, while
GIF images are not.
Image URL. The image cannot exceed 5 MB in size after
being Base64-encoded.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Either Url or Image must be provided; if both areprovided, only Url will be used.

Url

No

StringWe recommend storing the image in Tencent Cloud, as aTencent Cloud URL can guarantee higher download
speed and stability.
The download speed and stability of non-Tencent Cloud
URLs may be low.
PNG, JPG, JPEG, and BMP images are supported, while
GIF images are not.
Maximum number of recognizable faces. Default value: 1(i.e., detecting only the face with the largest size in theimage). Maximum value: 10.
MaxFaceNum is used to control the number of faces to

MaxFaceNum

No

Integerbe searched for if there are multiple faces in the input
image to be recognized.
For example, if the input image in Image or Url
contains multiple faces and MaxFaceNum is 5, top 5
faces with the largest size in the image will berecognized.

MinFaceSize

No©2013-2022 Tencent Cloud. All rights reserved.

Integer

Minimum height and width of face in px. Default value:

Page 267 of 321

Face Recognition

34. A value below 34 will affect the search accuracy. We
recommend setting this parameter to 80.
Detected faces, which is corresponding to the maximum
number of returned most matching persons. Default
MaxPersonNumPerGroupNo

Integervalue: 5. Maximum value: 10.
For example, if MaxFaceNum is 3,
MaxPersonNumPerGroup is 5, and theGroupIds length is 3, up to 45 (3 * 5 * 3) persons will
be returned.
Image quality control.
0: no control.
1: low quality requirement. The image has one or more of
the following problems: extreme blurriness, covered eyes,covered nose, and covered mouth.
2: average quality requirement. The image has at least
three of the following problems: excessive brightness,
excessive dimness, blurriness or average blurriness,covered eyebrows, covered cheeks, and covered chin.

QualityControl

No

Integer

3: high-quality requirement. The image has one to two of
the following problems: excessive brightness, excessive
dimness, average blurriness, covered eyebrows, covered
cheeks, and covered chin.
4: very high-quality requirement. The image is optimal in
all dimensions or only has a slight problem in one
dimension.
Default value: 0.
If the image quality does not meet the requirement, thereturned result will prompt that the detected image quality
is unsatisfactory.
In the output parameter Score , the result will be

FaceMatchThreshold

No

Float

returned only if the result value is above the
FaceMatchThreshold value. Default value: 0.

NeedPersonInfo

No

Integer

Whether to return person details. 0: no; 1: yes. Default
value: 0. Other values will be considered as 0 by default.

NeedRotateDetection

No

Integer

Whether to enable the support for rotated image
recognition. 0: no; 1: yes. Default value: 0. When the facein the image is rotated and the image has no EXIF
information, if this parameter is not enabled, the face in
the image cannot be correctly detected and recognized. If
you are sure that the input image contains EXIF
information or the face in the image will not be rotated, do©2013-2022 Tencent Cloud. All rights reserved.

Page 268 of 321

Face Recognition

not enable this parameter, as the overall time
consumption may increase by hundreds of milliseconds
after it is enabled.

3. Output Parameters
Parameter NameType

Description
Number of the persons included in searched groups. If

PersonNum

Integerthe quality of all faces in the input image does not meetthe requirement, 0 will be returned.

ResultsReturnsByGroup

Array ofResultsReturnsByGroup

FaceModelVersion

StringRequestId

StringRecognition result.
Algorithm model version used for face recognition.
The unique request ID, which is returned for eachrequest. RequestId is required for locating a problem.

4. Example
Example1 Searching for person with results returned by group
Input Example
https://iai.tencentcloudapi.com/?Action=SearchPersonsReturnsByGroup&Url=http://test.image.myqcloud.com/testA.jpg&MaxFaceNum=1&MinFaceSize=40&MaxPersonNumPerGroup=5&GroupIds.0=TencentShenZhenEmployee&<Common request parameters>

Output Example{"Response": {"ResultsReturnsByGroup": [{"RetCode": 0,©2013-2022 Tencent Cloud. All rights reserved.

Page 269 of 321

Face Recognition"FaceRect": {"X": 375,"Y": 37,"Width": 63,"Height": 82},"GroupCandidates": [{"GroupId": "TencentShenZhenEmployee","Candidates": [{"PersonId": "testtest3","FaceId": "","Score": 100,
"PersonName": null,"Gender": null,"PersonGroupInfos": null
}
]
}
]
}
],
"PersonNum": 1,"FaceModelVersion": "3.0","RequestId": "c8a06ec5-ecb4-4dd7-a8c8-ce5e675495c2"}}

Example2 Sample error
Input Example
https://iai.tencentcloudapi.com/?Action=SearchPersonsReturnsByGroup&Url=http://test.image.myqcloud.com/testB.jpg&MaxFaceNum=1&MinFaceSize=40&MaxPersonNumPerGroup=5&GroupIds.0=TencentShenZhenEmployee&<Common request parameters>

Output Example{"Response": {©2013-2022 Tencent Cloud. All rights reserved.

Page 270 of 321

Face Recognition"RequestId": "527ecffe-4c6a-47c9-8217-4dd2e3f018da"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

6. Error CodeThe following only lists the error codes related to the API business logic. For other error codes, see Common Error
Codes.
Error Code
FailedOperation.AcrossVersionsError

FailedOperation.FaceSizeTooSmall

Description
This operation cannot be performed acrossalgorithm model versions.
The face frame size is smaller than the
MinFaceSize value, and the face isfiltered out.

FailedOperation.ImageDecodeFailed
FailedOperation.ImageDownloadError©2013-2022 Tencent Cloud. All rights reserved.

Image decoding failed.
An error occurred while downloading theimage.

Page 271 of 321

Face Recognition

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

FailedOperation.ImageResolutionTooSmall

The image short edge resolution is smaller
than 64.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.FaceMatchThresholdIllegal

Invalid FaceMatchThreshold parameter.
The group ID contains invalid characters. It

InvalidParameterValue.GroupIdIllegal

can contain only letters, digits, and special
symbols (-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdNotExists

The corresponding group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.LimitExceed

The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.QualityControlIllegal

Invalid QualityControl parameter.

©2013-2022 Tencent Cloud. All rights reserved.

Page 272 of 321

Face Recognition

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UnsupportedGroupFaceModelVersion

This operation is not supported by algorithm
model v2.0 or below.

InvalidParameterValue.UrlIllegal

Invalid URL format.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.ChargeStatusException

The account is in arrears.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.LowBalanceInsufficient balance.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.NotReady

The service is not activated.

ResourceUnavailable.Recover

The resource has been repossessed.

ResourceUnavailable.StopUsing

The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 273 of 321

Face Recognition

Face Verification APIs
VerifyPerson：

Last updated 2023-02-27 15:22:51

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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.
This API fuses the features of all face images of a person; for example, if a person has 4 face images, it will fuse thefeatures 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, andthe "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.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType©2013-2022 Tencent Cloud. All rights reserved.

Description

Page 274 of 321

Face Recognition

ActionYes

StringCommon Params. The value used for this API: VerifyPerson.

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

PersonId

Yes

StringID of the person to be verified. For more information on
PersonId , please see the group management APIs.
Base64-encoded data of the image.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.

Image

No

StringIf there are multiple faces in the image, only the face with thelargest size will be selected.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
Image URL
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Either Url or Image must be provided; if both areprovided, only Url will be used.
We recommend storing the image in Tencent Cloud, as a

Url

No

StringTencent Cloud URL can guarantee higher download speed
and stability.
The download speed and stability of non-Tencent Cloud
URLs may be low.
If there are multiple faces in the image, only the face with thelargest size will be selected.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.

QualityControl

No

Integer

Image quality control.
0: no control.
1: low quality requirement. The image has one or more of thefollowing problems: extreme blurriness, covered eyes,covered nose, and covered mouth.
2: average quality requirement. The image has at least threeof the following problems: excessive brightness, excessive
dimness, blurriness or average blurriness, covered eyebrows,
covered cheeks, and covered chin.
3: high-quality requirement. The image has one to two of thefollowing problems: excessive brightness, excessive dimness,average blurriness, covered eyebrows, covered cheeks, andcovered chin.
4: very high-quality requirement. The image is optimal in all©2013-2022 Tencent Cloud. All rights reserved.

Page 275 of 321

Face Recognition

dimensions or only has a slight problem in one dimension.
Default value: 0.
If the image quality does not meet the requirement, thereturned result will prompt that the detected image quality is
unsatisfactory.
Whether to enable the support for rotated image recognition.
0: no; 1: yes. Default value: 0. When the face in the image isrotated and the image has no EXIF information, if thisparameter is not enabled, the face in the image cannot be
NeedRotateDetection

No

Integercorrectly detected and recognized. If you are sure that the
input image contains EXIF information or the face in theimage will not be rotated, do not enable this parameter, as theoverall time consumption may increase by hundreds ofmilliseconds after it is enabled.

3. Output Parameters
Parameter Name

Type

Score

Float

IsMatchBoolean

FaceModelVersion

StringRequestId

StringDescription
Similarity between given face image and PersonId . If there are multiple
faces under the PersonId , their information will be fused for verification.
Whether the person in the image matches the PersonId .
Algorithm model version used for face recognition in the group where the
Person is, which is set when the group is created.
The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

4. Example
Example1 Verifying person
Input Example
https://iai.tencentcloudapi.com/?Action=VerifyPerson&Url=http://test.image.myqcloud.com/testA.jpg&PersonId=11111111&<Common request parameters>©2013-2022 Tencent Cloud. All rights reserved.

Page 276 of 321

Face Recognition

Output Example{"Response": {"Score": 100,
"IsMatch": true,"FaceModelVersion": "3.0","RequestId": "a8eb4545-a154-4f86-9510-57a8be9cae0c"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

6. Error CodeThe following only lists the error codes related to the API business logic. For other error codes, see Common Error
Codes.
Error Code
FailedOperation.FaceQualityNotQualified
FailedOperation.FaceSizeTooSmall©2013-2022 Tencent Cloud. All rights reserved.

Description
The face image quality does not meet therequirement.
The face frame size is smaller than the

Page 277 of 321

Face Recognition

MinFaceSize value, and the face isfiltered out.
FailedOperation.ImageDecodeFailed
FailedOperation.ImageDownloadError

Image decoding failed.
An error occurred while downloading theimage.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

FailedOperation.ImageResolutionTooSmall

The image short edge resolution is smaller
than 64.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.QualityControlIllegal

Invalid QualityControl parameter.

InvalidParameterValue.UnsupportedGroupFaceModelVersion
InvalidParameterValue.UrlIllegal©2013-2022 Tencent Cloud. All rights reserved.

This operation is not supported by algorithm
model v2.0 or below.
Invalid URL format.

Page 278 of 321

Face Recognition

LimitExceeded

The quota limit is reached.

ResourceUnavailable.ChargeStatusException

The account is in arrears.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.GetAuthInfoError

Failed to get the authentication information.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.LowBalanceInsufficient balance.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.NotReady

The service is not activated.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 279 of 321

Face Recognition

VerifyFace：

Last updated 2023-02-27 15:22:52

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
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.
The VerifyFace API judges whether a person is someone specified whose information is stored in a group, andthere may be multiple face images of "someone". By contrast, the CompareFace API judges the similarity between two
faces.
This API recognizes each face image of a person as an independent one. By contrast, the VerifyPerson API fuses thefeatures of all face images of a person; for example, if a person has 4 face images, the VerifyPerson API will fuse thefeatures 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 theparameter SignatureMethod to TC3-HMAC-SHA256 .
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

Description

ActionYes

StringCommon Params. The value used for this API: VerifyFace.

©2013-2022 Tencent Cloud. All rights reserved.

Page 280 of 321

Face Recognition

VersionYes

StringCommon Params. The value used for this API: 2020-03-03.

RegionNo

StringCommon Params. This parameter is not required for this API.

PersonId

Yes

StringID of the person to be verified. For more information on
PersonId , please see the group management APIs.
Base64-encoded image data, which cannot exceed 5 MB.
The long side cannot exceed 4,000 px for images in JPG

Image

No

Stringformat or 2,000 px for images in other formats.
If there are multiple faces in the image, only the face with thelargest size will be selected.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.
Image URL. The image cannot exceed 5 MB in size after
being Base64-encoded.
The long side cannot exceed 4,000 px for images in JPG
format or 2,000 px for images in other formats.
Either Url or Image must be provided; if both areprovided, only Url will be used.
We recommend storing the image in Tencent Cloud, as a

Url

No

StringTencent Cloud URL can guarantee higher download speed
and stability.
The download speed and stability of non-Tencent Cloud
URLs may be low.
If there are multiple faces in the image, only the face with thelargest size will be selected.
PNG, JPG, JPEG, and BMP images are supported, while GIF
images are not.

QualityControl

No

Integer

Image quality control.
0: no control.
1: low quality requirement. The image has one or more of thefollowing problems: extreme blurriness, covered eyes,covered nose, and covered mouth.
2: average quality requirement. The image has at least threeof the following problems: excessive brightness, excessive
dimness, blurriness or average blurriness, covered eyebrows,
covered cheeks, and covered chin.
3: high-quality requirement. The image has one to two of thefollowing problems: excessive brightness, excessive dimness,average blurriness, covered eyebrows, covered cheeks, andcovered chin.
4: very high-quality requirement. The image is optimal in all
dimensions or only has a slight problem in one dimension.

©2013-2022 Tencent Cloud. All rights reserved.

Page 281 of 321

Face Recognition

Default value: 0.
If the image quality does not meet the requirement, thereturned result will prompt that the detected image quality is
unsatisfactory.
Whether to enable the support for rotated image recognition.
0: no; 1: yes. Default value: 0. When the face in the image isrotated and the image has no EXIF information, if thisparameter is not enabled, the face in the image cannot be
NeedRotateDetection

No

Integercorrectly detected and recognized. If you are sure that the
input image contains EXIF information or the face in theimage will not be rotated, do not enable this parameter, as theoverall time consumption may increase by hundreds ofmilliseconds after it is enabled.

3. Output Parameters
Parameter NameType

Description
Similarity between given face image and PersonId . If there are multiple
faces under the PersonId , the score of the highest similarity will be
returned.

Score

Float

The returned similarity score varies by algorithm version.
If you need to verify whether the faces in the two images are the same
person, then the 0.1%, 0.01%, and 0.001% FARs on v3.0 correspond toscores of 40, 50, and 60, respectively. Generally, if the score is above 50, it
can be judged that they are the same person.
The 0.1%, 0.01%, and 0.001% FARs on v2.0 correspond to scores of 70, 80,
and 90, respectively. Generally, if the score is above 80, it can be judged thatthey are the same person.
Whether the person is the one in the image. The fixed threshold score is 60. If

IsMatchBooleanyou want to adjust the threshold more flexibly, you can take the returned
Score parameter value for judgment.

FaceModelVersion

StringAlgorithm model version used for face recognition in the group where the
Person is, which is set when the group is created.

RequestId

String

The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

©2013-2022 Tencent Cloud. All rights reserved.

Page 282 of 321

Face Recognition

4. Example
Example1 Verifying a face
Input Example
POST / HTTP/1.1
Host: iai.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: VerifyFace<Common request parameters>{"Url": "http://test.image.myqcloud.com/testA.jpg","PersonId": "11111111"}

Output Example{"Response": {"Score": 100,
"IsMatch": true,"FaceModelVersion": "3.0","RequestId": "a8eb4545-a154-4f86-9510-57a8be9cae0c"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET

©2013-2022 Tencent Cloud. All rights reserved.

Page 283 of 321

Face Recognition

Tencent Cloud SDK 3.0 for C++

Command Line Interface
Tencent Cloud CLI 3.0

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

AuthFailure.InvalidAuthorization

Authentication failed.

FailedOperation.ConflictOperation

FailedOperation.DuplicatedGroupDescription

FailedOperation.FaceQualityNotQualified

FailedOperation.FaceSizeTooSmall

The operations conflict. Do not operate on thesame person simultaneously.
The custom description field must be unique inthe group.
The face image quality does not meet therequirement.
The face frame size is smaller than the
MinFaceSize value, and the face is filtered
out.

FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist

FailedOperation.GroupPersonMapNotExist

The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.
The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

FailedOperation.ImageResolutionTooSmall©2013-2022 Tencent Cloud. All rights reserved.

The image short edge resolution is smaller than
64.

Page 284 of 321

Face Recognition

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.SearchFacesExceed

FailedOperation.ServerError

The number of faces searched for exceeds thelimit.
The algorithm service is exceptional. Please
retry.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds theInvalidParameterValue.DeleteFaceNumExceed

limit. Every person must have at least one face
image.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

©2013-2022 Tencent Cloud. All rights reserved.

Page 285 of 321

Face Recognition

InvalidParameterValue.GroupIdsExceed
InvalidParameterValue.GroupNameAlreadyExist

InvalidParameterValue.GroupNameIllegal
InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed

InvalidParameterValue.GroupNumPerPersonExceed

The list of groups passed in exceeds the limit.
The group name already exists. It must be
unique.
The group name contains invalid characters. It
can contain only letters, - , _ , and digits.
The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalid

InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong
InvalidParameterValue.ImageEmpty
InvalidParameterValue.LimitExceed

The group remarks field exceeds the length
limit.
Empty image.
The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

InvalidParameterValue.PersonExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields are allowed.
The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

The name of the person's custom description
field exceeds the length limit.

©2013-2022 Tencent Cloud. All rights reserved.

Page 286 of 321

Face Recognition

InvalidParameterValue.PersonExistInGroupThe ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

InvalidParameterValue.PersonGenderIllegal
InvalidParameterValue.PersonIdAlreadyExist
InvalidParameterValue.PersonIdIllegal

exceeds the limit. One person can have up to 5
face images.
An error occurred while setting person gender.
0: empty; 1: male; 2: female.
The person ID already exists. It must be unique.
The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.QualityControlIllegal

Invalid QualityControl parameter.

InvalidParameterValue.SearchPersonsExceed

The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.Recover©2013-2022 Tencent Cloud. All rights reserved.

The resource has been repossessed.

Page 287 of 321

Face Recognition

ResourceUnavailable.StopUsing

The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 288 of 321

Face Recognition

Image-based Liveness Detection (HighPrecision) APIs
DetectLiveFaceAccurate：

Last updated 2023-02-27 15:22:46

1. API Description
Domain name for API request: iai.tencentcloudapi.com.
This API is used to detect the liveness of faces in images uploaded by users and determine whether these images arephotographed.
Compared with normal Image-based Liveness Detection services, this API enhances the defense capability against
attacks from HD screens, printed photos, and 3D masks, as well as improves attack blocking four to five times thecompeting products, while maintaining high accuracy. It also supports face verification in different use cases, andsatisfies the image-based liveness detection needs on mobile or PCs, making it ideal for liveness detection
applications in various industries.
Pay-as-you-go billing officially started for this API at 00:00, August 1, 2022. For more information, see Billing
Overview.
We recommend you to use API Explorer
Try itAPI 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 thecomplete common parameter list, see Common Request Parameters.
Parameter Name

RequiredType

ActionYes

String

VersionYes

String©2013-2022 Tencent Cloud. All rights reserved.

Description
Common Params. The value used for this API:
DetectLiveFaceAccurate.
Common Params. The value used for this API: 2020-03-03.

Page 289 of 321

Face Recognition

RegionNo

StringCommon Params. This parameter is not required for this API.
Base64-encoded image data, which cannot exceed 5 MB.
The long side cannot exceed 4,000 px for images in .jpg format or

Image

No

String2,000 px for images in other formats.
The recommended image aspect ratio is 3:4 (generally, theaspect ratio of images taken by mobile phones).
The face must be greater than 100*100 px in size.
Supported image formats are PNG, JPG, JPEG, and BMP. GIF
is currently not supported.
Image URL. The image cannot exceed 5 MB in size after being
Base64-encoded.
The long side cannot exceed 4,000 px for images in .jpg format or
2,000 px for images in other formats.
Either Url or Image must be provided; if both areprovided, only Url will be used.
The recommended image aspect ratio is 3:4 (generally, the

Url

No

Stringaspect ratio of images taken by mobile phones).
The face must be greater than 100*100 px in size.
We recommend you store the image in Tencent Cloud, as aTencent Cloud URL can guarantee higher download speed andstability. The download speed and stability of non-Tencent Cloud
URLs may be low.
Supported image formats are PNG, JPG, JPEG, and BMP. GIF
is currently not supported.

FaceModelVersion

No

StringAlgorithm model version used for face recognition. Valid value:
3.0 .

3. Output Parameters
Parameter NameType

Description
Liveness score. Value range: [0, 100]. You can set several thresholds such as

Score

Float

5, 10, 40, 70 and 90 to determine whether the image is photographed. We
recommend you use the threshold of 40.

FaceModelVersion

StringRequestId

StringAlgorithm model version used for face recognition.
The unique request ID, which is returned for each request. RequestId isrequired for locating a problem.

©2013-2022 Tencent Cloud. All rights reserved.

Page 290 of 321

Face Recognition

4. Example
Example1 Detecting the liveness of faces in images (high precision)
Input Example
POST / HTTP/1.1
Host: iai.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DetectLiveFaceAccurate<Common request parameters>{"Url": "http://test.image.myqcloud.com/testA.jpg"}

Output Example{"Response": {"Score": 99,"FaceModelVersion": "3.0","RequestId": "048a5eb3-f7a9-4c1f-a982-00e90b6b892c"}}

5. Developer Resources
SDK
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call
APIs.
Tencent Cloud SDK 3.0 for Python
Tencent Cloud SDK 3.0 for Java
Tencent Cloud SDK 3.0 for PHP
Tencent Cloud SDK 3.0 for Go
Tencent Cloud SDK 3.0 for NodeJS
Tencent Cloud SDK 3.0 for .NET
Tencent Cloud SDK 3.0 for C++©2013-2022 Tencent Cloud. All rights reserved.

Page 291 of 321

Face Recognition

Command Line Interface
Tencent Cloud CLI 3.0

6. Error CodeThe following only lists the error codes related to the API business logic. For other error codes, see Common Error
Codes.
Error Code
FailedOperation.ConflictOperation

FailedOperation.DuplicatedGroupDescription

Description
The operations conflict. Do not operate on thesame person simultaneously.
The custom description field must be unique inthe group.
The face frame size is smaller than the

FailedOperation.FaceSizeTooSmall

MinFaceSize value, and the face is filtered
out.

FailedOperation.GroupInDeletedState
FailedOperation.GroupPersonMapExist

FailedOperation.GroupPersonMapNotExist

The current group is being deleted. Please wait.
The ID of the corresponding person is alreadyin the group.
The ID of the corresponding person is not in thegroup.

FailedOperation.ImageDecodeFailed

Image decoding failed.

FailedOperation.ImageDownloadError

An error occurred while downloading the image.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

FailedOperation.ImageResolutionTooSmall

The image short edge resolution is smaller than64.

FailedOperation.ImageSizeExceed

The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

©2013-2022 Tencent Cloud. All rights reserved.

Page 292 of 321

Face Recognition

FailedOperation.RpcFailFailedOperation.SearchFacesExceed

FailedOperation.ServerError

The RPC call failed.
The number of faces searched for exceeds thelimit.
The algorithm service is exceptional. Please
retry.

FailedOperation.UnKnowError

An internal error occurred.

InternalError

Internal error.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

InvalidParameterValue.DeleteFaceNumExceed

The number of faces in the account exceeds thelimit.
The number of faces to be deleted exceeds thelimit. Every person must have at least one face
image.

InvalidParameterValue.FaceModelVersionIllegal

The algorithm model version is invalid.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

description fields exceeds the limit. Up to 5
fields can be created.

InvalidParameterValue.GroupExDescriptionsNameIdentical

The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It can

InvalidParameterValue.GroupIdIllegal

contain only letters, digits, and special symbols(-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

©2013-2022 Tencent Cloud. All rights reserved.

Page 293 of 321

Face Recognition

InvalidParameterValue.GroupIdsExceed
InvalidParameterValue.GroupNameAlreadyExist

The list of groups passed in exceeds the limit.
The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.

InvalidParameterValue.GroupNameTooLong

The group name exceeds the length limit.

InvalidParameterValue.GroupNumExceed

The number of groups exceeds the limit. If you
need more, please contact us.

InvalidParameterValue.GroupNumPerPersonExceed

The number of groups exceeds the limit. One
person can be added to up to 100 groups.
The group remarks field contains invalid

InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong

The group remarks field exceeds the length
limit.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.LimitExceed

The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

InvalidParameterValue.PersonExDescriptionInfosExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom
description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdenticalInvalidParameterValue.PersonExDescriptionsNameIllegal

The name of the person's custom description
field must be unique.
The name of the person's custom description
field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong©2013-2022 Tencent Cloud. All rights reserved.

The name of the person's custom description

Page 294 of 321

Face Recognition

field exceeds the length limit.
InvalidParameterValue.PersonExistInGroupThe ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal

An error occurred while setting person gender.
0: empty; 1: male; 2: female.

InvalidParameterValue.PersonIdAlreadyExist

The person ID already exists. It must be unique.

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.

InvalidParameterValue.PersonNameIllegal
InvalidParameterValue.PersonNameTooLong
InvalidParameterValue.SearchPersonsExceed

The person name contains invalid characters. It
can contain only letters, - , _ , and digits.
The person name exceeds the length limit.
The number of persons searched for exceeds
the limit.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.InArrears

The account is in arrears.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.Recover©2013-2022 Tencent Cloud. All rights reserved.

The resource has been repossessed.

Page 295 of 321

Face Recognition

ResourceUnavailable.StopUsing

The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 296 of 321

Face Recognition

Data Types：

Last updated 2023-02-27 15:22:54

AttributeItem
Face attribute information
Used by actions: DetectFaceAttributes.
Name

Type

Description

Type

Integer

Attribute value

Probability

Float

Probability of recognizing Type , which indicates the probability of correct
recognition. Value range: [0,1].

Candidate
Most matching candidate recognized
Used by actions: SearchFaces, SearchFacesReturnsByGroup, SearchPersons, SearchPersonsReturnsByGroup.
Name

Type

Description

PersonId

StringPerson ID
Face ID, which is valid only when returned by the SearchFaces

FaceIdStringor SearchFacesReturnsByGroup API. User search APIs use
facial feature fusion to search for users, for which this field ismeaningless.

Score

Float

Match score of candidate.
In a face base library containing 10,000 faces, the 1%, 0.1%, and
0.01% FARs correspond to scores of 70, 80, and 90, respectively;
In a face base library containing 100,000 faces, the 1%, 0.1%, and
0.01% FARs correspond to scores of 80, 90, and 100, respectively;
In a face base library containing 300,000 faces, the 1% and 0.1%
FARs correspond to scores of 85 and 95, respectively.
Generally, the score of 80 is suitable for most scenarios. We©2013-2022 Tencent Cloud. All rights reserved.

Page 297 of 321

Face Recognition

recommend choosing an appropriate score based on the actual
situation, preferably no more than 90.
Person name
PersonName

StringNote: this field may return null, indicating that no valid values can beobtained.
Person gender

GenderInteger

PersonGroupInfos

Note: this field may return null, indicating that no valid values can beobtained.
List of groups containing this person and their description fields

Array of
PersonGroupInfo

Note: this field may return null, indicating that no valid values can beobtained.

Eye
Eye information
Used by actions: DetectFaceAttributes.
Name

Type

Description
Whether glasses are worn.

Glass

AttributeItem

The Type values of the AttributeItem include: 0: no glasses; 1:
general glasses; 2: sunglasses.

EyeOpenAttributeItem

EyelidType

AttributeItem

Whether the eyes are open.
The Type values of the AttributeItem include: 0: open; 1: closed.
Whether the person has double eyelids.
The Type values of the AttributeItem include: 0: no; 1: yes.
Eye size.

EyeSize

AttributeItem

The Type values of the AttributeItem include: 0: small eyes; 1:
general eyes; 2: big eyes.

Eyebrow
Eyebrow information
Used by actions: DetectFaceAttributes.

©2013-2022 Tencent Cloud. All rights reserved.

Page 298 of 321

Face Recognition

Name

Type

Description

EyebrowDensity

AttributeItem

Eyebrow thickness.
The Type values of the AttributeItem include: 0: light; 1: thick.

EyebrowCurve

AttributeItem

Eyebrow curve.
The Type values of the AttributeItem include: 0: flat; 1: curved.

EyebrowLength

AttributeItem

Eyebrow length.
The Type values of the AttributeItem include: 0: short; 1: long.

FaceAttributesInfo
Face attributes, including gender, age, expression,
beauty, glass, mask, hair, and pose (pitch, roll, yaw). Valid information will be returned only if
NeedFaceAttributes is set to 1. The face attribute information of up to 5 largest faces in the image will be
returned, and FaceAttributesInfo of the 6th and rest faces is meaningless.
Used by actions: DetectFace.
Name

Type

Description
Gender. The gender is female for the value range [0,49] and male for

GenderIntegerthe value range [50,100]. The closer the value to 0 or 100, the higher
the confidence. If NeedFaceAttributes is not 1 or more than 5
faces are detected, this parameter will still be returned but
meaningless.
Age. Value range: [0,100]. If NeedFaceAttributes is not 1 orAge

Integermore than 5 faces are detected, this parameter will still be returned
but meaningless.
Expression. Value range: [0 (normal)–50 (smile)–100 (laugh)]. If

Expression

Integer

NeedFaceAttributes is not 1 or more than 5 faces aredetected, this parameter will still be returned but meaningless.
Whether glasses are present. Valid values: true, false. If

Glass

BooleanNeedFaceAttributes is not 1 or more than 5 faces aredetected, this parameter will still be returned but meaningless.

Pitch

Integer

Vertical offset in degrees. Value range: [-30,30]. If
NeedFaceAttributes is not 1 or more than 5 faces aredetected, this parameter will still be returned but meaningless.

©2013-2022 Tencent Cloud. All rights reserved.

Page 299 of 321

Face Recognition

We recommend selecting images in the [-10,10] range for adding
faces.
Horizontal offset in degrees. Value range: [-30,30]. If
NeedFaceAttributes is not 1 or more than 5 faces are
Yaw

Integerdetected, this parameter will still be returned but meaningless.
We recommend selecting images in the [-10,10] range for adding
faces.
Horizontal rotation in degrees. Value range: [-180,180]. If
NeedFaceAttributes is not 1 or more than 5 faces are

Roll

Integerdetected, this parameter will still be returned but meaningless.
We recommend selecting images in the [-20,20] range for adding
faces.
Beauty. Value range: [0,100]. If NeedFaceAttributes is not 1 or

BeautyIntegermore than 5 faces are detected, this parameter will still be returned
but meaningless.
Whether hat is present. Valid values: true, false. If
NeedFaceAttributes is not 1 or more than 5 faces are

Hat

Booleandetected, this parameter will still be returned but meaningless.
Note: this field may return null, indicating that no valid values can beobtained.
Whether mask is present. Valid values: true, false. If
NeedFaceAttributes is not 1 or more than 5 faces are

Mask

Booleandetected, this parameter will still be returned but meaningless.
Note: this field may return null, indicating that no valid values can beobtained.
Hair information, including length, bang, and color. If
NeedFaceAttributes is not 1 or more than 5 faces are

Hair

FaceHairAttributesInfo

detected, this parameter will still be returned but meaningless.
Note: this field may return null, indicating that no valid values can beobtained.
Whether the eyes are open. Valid values: true, false. As long as there
is more than one eye closed, false will be returned. If

EyeOpenBooleanNeedFaceAttributes is not 1 or more than 5 faces aredetected, this parameter will still be returned but meaningless.
Note: this field may return null, indicating that no valid values can beobtained.

©2013-2022 Tencent Cloud. All rights reserved.

Page 300 of 321

Face Recognition

FaceDetailAttributesInfo
Face attribute information. According to the types specified in FaceAttributesType , the following face
attributes will be returned: Age, Beauty,
Emotion, Eye, Eyebrow, Gender,
Hair, Hat, Headpose, Mask, Mouth, Moustache,
Nose, Shape, Skin, Smile, etc.
If no types are specified in FaceAttributesType , the details returned by FaceDetaiAttributesInfo will
be meaningless.
Used by actions: DetectFaceAttributes.
Name

Type

Description
Age. Value range: [0,65], where 65 indicates 65 years old or above.

Age

Integer

If FaceAttributesType does not include Age or more than 5 faces aredetected, this parameter will still be returned but meaningless.
Beauty score. Value range: [0,100].

BeautyInteger

If FaceAttributesType does not include Beauty or more than 5 faces
are detected, this parameter will still be returned but meaningless.
Emotion, including relaxed, happy, surprised, angry, sad, disgusted, andEmotionAttributeItem

scared.
The Type values of the AttributeItem include: 0: relaxed; 1: happy; 2:surprised; 3: angry; 4: sad; 5: disgusted; 6: scared.
If FaceAttributesType does not include Emotion or more than 5
faces are detected, this parameter will still be returned but meaningless.
Eye information, including whether glasses are worn, whether eyes are closed,

Eye

Eye

whether the person has double eyelids, and the eye size.
If FaceAttributesType does not include Eye or more than 5 faces aredetected, this parameter will still be returned but meaningless.
Eyebrow information, including whether the eyebrows are thick, curved, or long.

Eyebrow

Eyebrow

If FaceAttributesType does not include Eyebrow or more than 5
faces are detected, this parameter will still be returned but meaningless.
Gender information.

GenderAttributeItem

The Type values of the AttributeItem include: 0: male; 1: female.
If FaceAttributesType does not include Gender or more than 5 faces
are detected, this parameter will still be returned but meaningless.

Hair

Hair

Hair information, including length, bang, and color.

©2013-2022 Tencent Cloud. All rights reserved.

Page 301 of 321

Face Recognition

If FaceAttributesType does not include Hair or more than 5 faces
are detected, this parameter will still be returned but meaningless.
Hat information, including whether a hat is worn, hat style, and hat color.
Hat

Hat

If FaceAttributesType does not include Hat or more than 5 faces aredetected, this parameter will still be returned but meaningless.

HeadPose

HeadPose

Pose information, including the face pitch, yaw, and roll.
If FaceAttributesType does not include Headpose or more than 5
faces are detected, this parameter will still be returned but meaningless.
Mask information.
The Type values of the AttributeItem include: 0: no mask; 1: theMask

AttributeItem

mask is worn and does not cover the face; 2: the mask is worn and covers thechin; 3: the mask is worn and covers the mouth; 4: the mask is worn properly.
If FaceAttributesType does not include Mask or more than 5 faces
are detected, this parameter will still be returned but meaningless.
Mouth information, including whether the mouth is open and the lip thickness.

Mouth

Mouth

If FaceAttributesType does not include Mouth or more than 5 faces
are detected, this parameter will still be returned but meaningless.
Beard information.
The Type values of the AttributeItem include: 0: no beard; 1: beard

Moustache

AttributeItem

detected.
If FaceAttributesType does not include Moustache or more than 5
faces are detected, this parameter will still be returned but meaningless.
Nose information.
The Type values of the AttributeItem include: 0: upturned nose; 1:NoseAttributeItem

aquiline nose; 2: general nose; 3: bulbous nose.
If FaceAttributesType does not include Nose or more than 5 faces
are detected, this parameter will still be returned but meaningless.
Face shape information.
The Type values of the AttributeItem include: 0: square; 1: triangular;

Shape

AttributeItem

2: oval; 3: heart-shaped; 4: round.
If FaceAttributesType does not include Shape or more than 5 faces
are detected, this parameter will still be returned but meaningless.
Skin color information.
The Type values of the AttributeItem include: 0: yellow; 1: brown; 2:Skin

AttributeItem

black; 3: white.
If FaceAttributesType does not include Skin or more than 5 faces
are detected, this parameter will still be returned but meaningless.

©2013-2022 Tencent Cloud. All rights reserved.

Page 302 of 321

Face Recognition

Smile

IntegerSmile level. Value range: [0,100].
If FaceAttributesType does not include Smile or more than 5 faces
are detected, this parameter will still be returned but meaningless.

FaceDetailInfo
Face information list.
Used by actions: DetectFaceAttributes.
Name

Type

Description

FaceRect

FaceRect

Position of the detected face frame.
Face attribute information. According to the types
specified in FaceAttributesType , the following
face attributes will be returned: age (Age), beauty score(Beauty),emotion (Emotion), eye information (Eye), eyebrow
information (Eyebrow), gender (Gender),FaceDetailAttributesInfo

FaceDetailAttributesInfo

hair information (Hair), hat information (Hat), pose
(Headpose), mask information (Mask), mouth
information (Mouse), beard information (Moustache),nose information (Nose), face shape (Shape), skincolor (Skin), and smile information (Smile), etc.
If no types are specified in FaceAttributesType ,the detailed items returned byFaceDetaiAttributesInfo will be meaningless.

FaceHairAttributesInfo
Hair information in face attributes.
Used by actions: DetectFace.
Name

Type

LengthInteger

Bang

Integer

Description
0: shaved head, 1: short hair, 2: medium hair, 3: long hair, 4: braid
Note: this field may return null, indicating that no valid values can be obtained.
0: with bangs, 1: no bangs
Note: this field may return null, indicating that no valid values can be obtained.

©2013-2022 Tencent Cloud. All rights reserved.

Page 303 of 321

Face Recognition

Color

Integer

0: black, 1: golden, 2: brown, 3: grayNote: this field may return null, indicating that no valid values can be obtained.

FaceInfo
Face information list.
Used by actions: DetectFace.
Name

Type

Description
Horizontal coordinate of the top-left vertex of the face frame.
The face frame encompasses the facial features and is extended
accordingly. If it is larger than the image, the coordinates will be

XInteger

negative.
If you want to capture a complete face, you can set the negative
coordinates to 0 if the completeness score meets therequirement.
Vertical coordinate of the top-left vertex of the face frame.
The face frame encompasses the facial features and is extended
accordingly. If it is larger than the image, the coordinates will be

YInteger

negative.
If you want to capture a complete face, you can set the negative
coordinates to 0 if the completeness score meets therequirement.

WidthIntegerFace frame width.

HeightIntegerFace frame height.
Face attributes, including gender, age, expression,

FaceAttributesInfo

FaceAttributesInfo

beauty, glass, mask, hair, and pose (pitch, roll, yaw). Valid
information will be returned only if NeedFaceAttributes is
set to 1.
Face quality information, including score, sharpness, brightness,and completeness. Valid information will be returned only if

FaceQualityInfo

FaceQualityInfo

NeedFaceDetection is set to 1.
Note: this field may return null, indicating that no valid values canbe obtained.

FaceQualityCompleteness©2013-2022 Tencent Cloud. All rights reserved.

Page 304 of 321

Face Recognition

Completeness of facial features, which assesses the completeness of the eyebrows, eyes, nose, cheeks, mouth, andchin.
Used by actions: DetectFace.
Name

Type

Description
Eyebrow completeness. Value range: [0,100]. The higher the score, the higher the

Eyebrow

Integercompleteness.
Reference range: [0,80], which means incomplete.
Note: this field may return null, indicating that no valid values can be obtained.
Eye completeness. Value range: [0,100]. The higher the score, the higher theEyeIntegercompleteness.
Reference range: [0,80], which means incomplete.
Note: this field may return null, indicating that no valid values can be obtained.
Nose completeness. Value range: [0,100]. The higher the score, the higher theNose

Integercompleteness.
Reference range: [0,60], which means incomplete.
Note: this field may return null, indicating that no valid values can be obtained.

Cheek

Integer

Cheek completeness. Value range: [0,100]. The higher the score, the higher thecompleteness.
Reference range: [0,70], which means incomplete.
Note: this field may return null, indicating that no valid values can be obtained.
Mouth completeness. Value range: [0,100]. The higher the score, the higher the

Mouth

Integercompleteness.
Reference range: [0,50], which means incomplete.
Note: this field may return null, indicating that no valid values can be obtained.
Chin completeness. Value range: [0,100]. The higher the score, the higher the

Chin

Integercompleteness.
Reference range: [0,70], which means incomplete.
Note: this field may return null, indicating that no valid values can be obtained.

FaceQualityInfo
Face quality information, including score, sharpness, brightness, and completeness. Valid information will be returned
only if NeedFaceDetection is set to 1.
Used by actions: DetectFace.
Name

Type

©2013-2022 Tencent Cloud. All rights reserved.

Description

Page 305 of 321

Face Recognition

Quality score. Value range: [0,100]. It comprehensively
evaluates whether the image quality is suitable for facerecognition; the higher the score, the higher the quality.
In normal cases, you only need to use Score as the overall
quality standard score. Specific item scores such as
Sharpness , Brightness , Completeness are for
Score

Integerreference only.
Reference range: [0,40]: poor; [40,60]: fine; [60,80]: good;[80,100]: excellent.
We recommend selecting images with a score above 70 for
adding faces.
Note: this field may return null, indicating that no valid values
can be obtained.
Sharpness. Value range: [0,100]. It evaluates the sharpness of
the image. The higher the score, the sharper the image.
Reference range: [0,40]: very blurry; [40,60]: blurry; [60,80]:

Sharpness

Integerfine; [80,100]: sharp.
We recommend selecting images with a score above 80 for
adding faces.
Note: this field may return null, indicating that no valid values
can be obtained.
Brightness. Value range: [0,100]. The brighter the image, thehigher the score.

Brightness

Integer

Reference range: [0,30]: dark; [30,70]: normal; [70,100]: bright.
We recommend selecting images in the [30,70] range foradding faces.
Note: this field may return null, indicating that no valid values
can be obtained.
Completeness of facial features, which assesses thecompleteness of the eyebrows, eyes, nose, cheeks, mouth,

Completeness

FaceQualityCompletenessand chin.
Note: this field may return null, indicating that no valid values
can be obtained.

FaceRect
Position of detected face frame
Used by actions: CreateFace, CreatePerson, DetectFaceAttributes, SearchFaces, SearchFacesReturnsByGroup,
SearchPersons, SearchPersonsReturnsByGroup.

©2013-2022 Tencent Cloud. All rights reserved.

Page 306 of 321

Face Recognition

Name

Type

Description
Horizontal coordinate of the top-left vertex of face frame.
The face frame encompasses the facial features and is extended accordingly. If it is larger

X

Integerthan the image, the coordinates will be negative.
If you want to capture a complete face, you can set the negative coordinates to 0 if thecompleteness score meets the requirement.
Vertical coordinate of the top-left vertex of face frame.

Y

Integer

The face frame encompasses the facial features and is extended accordingly. If it is larger
than the image, the coordinates will be negative.
If you want to capture a complete face, you can set the negative coordinates to 0 if thecompleteness score meets the requirement.

WidthIntegerFace width

HeightIntegerFace height

FaceShape
Specific information of facial feature localization (facial keypoints).
Used by actions: AnalyzeFace.
Name

Type

Description

FaceProfile

Array of Point

21 points that describe the face contour.

LeftEyeArray of Point

8 points that describe the left eye.

RightEye

Array of Point

8 points that describe the right eye.

LeftEyeBrow

Array of Point

8 points that describe the left eyebrow.

RightEyeBrow

Array of Point

8 points that describe the right eyebrow.

Mouth

Array of Point

22 points that describe the mouth.

Nose

Array of Point

13 points that describe the nose.

LeftPupil

Array of Point

1 point that describes the left pupil.

RightPupil

Array of Point

1 point that describes the right pupil.

©2013-2022 Tencent Cloud. All rights reserved.

Page 307 of 321

Face Recognition

GroupCandidate
Recognition result items by group
Used by actions: SearchFacesReturnsByGroup, SearchPersonsReturnsByGroup.
Name

Type

Description

GroupId

StringGroup ID.

Candidates

Array of Candidate

Most matching candidate recognizedGroupExDescriptionInfo
Custom description field of the group to be modified, which is a key-value pair.
Used by actions: ModifyGroup.
Name

Type

Required

Description
Custom group description field index, whose value starts

GroupExDescriptionIndex

IntegerYesGroupExDescription

StringYesfrom 0.
Note: this field may return null, indicating that no valid
values can be obtained.
Content of the custom group description field to be
updatedGroupInfo
Returned group information
Used by actions: GetGroupList.
Name

Type

Description

GroupName

StringGroup nameGroupId

StringGroup ID

GroupExDescriptions

Array

Custom group description fieldofNote: this field may return null, indicating that no valid values can be

Stringobtained.

©2013-2022 Tencent Cloud. All rights reserved.

Page 308 of 321

Face Recognition

Group remarks
Tag

StringNote: this field may return null, indicating that no valid values can beobtained.
Algorithm model version used for face recognition.

FaceModelVersion

StringNote: this field may return null, indicating that no valid values can beobtained.
Group creation time and date ( CreationTimestamp ), whose value isthe number of milliseconds between the UNIX epoch time and the group
creation time.

CreationTimestamp

Integer

The UNIX epoch time is 00:00:00, Thursday, January 1, 1970, Coordinated
Universal Time (UTC). For more information, please see the UNIX time
document.
Note: this field may return null, indicating that no valid values can beobtained.

Hair
Hair information
Used by actions: DetectFaceAttributes.
Name

Type

LengthAttributeItem

Description
Hair length information.
The Type values of the AttributeItem include: 0: bald, 1: short hair, 2:
medium hair, 3: long hair, 4: braid.
Bang information.

Bang

AttributeItem

The Type values of the AttributeItem include: 0: no bang; 1: bang
detected.
Hair color information.

Color

AttributeItem

The Type values of the AttributeItem include: 0: black; 1: golden; 2:brown; 3: gray.

Hat
Hat information
Used by actions: DetectFaceAttributes.

©2013-2022 Tencent Cloud. All rights reserved.

Page 309 of 321

Face Recognition

Name

Style

Type

Description

AttributeItem

Hat wearing status information.
The Type values of the AttributeItem include: 0: no hat; 1: general hat; 2:helmet; 3: security guard hat.
Hat color.

Color

AttributeItem

The Type values of the AttributeItem include: 0: no hat; 1: red; 2: yellow; 3:
blue; 4: black; 5: gray; 6: mixed colors.

HeadPose
Pose information.
Used by actions: DetectFaceAttributes.
Name

Type

Description

Pitch

Integer

Pitch. Value range: [-30,30].

Yaw

IntegerYaw. Value range: [-30,30].

Roll

Integer

Roll. Value range: [-180,180].

Mouth
Mouth information
Used by actions: DetectFaceAttributes.
Name

Type

MouthOpen

AttributeItem

Description
Whether the mouth is open.
The Type values of the AttributeItem include: 0: closed; 1: open.

PersonExDescriptionInfo
Custom description field of the person to be modified, which is a key-value pair.
Used by actions: CreatePerson, ModifyPersonGroupInfo.

©2013-2022 Tencent Cloud. All rights reserved.

Page 310 of 321

Face Recognition

Name

Type

Required

Description
Person description field index, whose value starts from 0.

PersonExDescriptionIndex

Integer

Yes

Note: this field may return null, indicating that no valid
values can be obtained.

PersonExDescription

StringYes

Content of the person description field to be updated

PersonGroupInfo
List of groups containing this person and their description fields
Used by actions: GetPersonGroupInfo, SearchFaces, SearchFacesReturnsByGroup, SearchPersons,SearchPersonsReturnsByGroup.
Name

Type

Description

GroupId

StringID of the group that contains this person

PersonExDescriptions

Array of String

Content of person description field

PersonInfo
Returned person information
Used by actions: GetPersonList.
Name

Type

Description

PersonName

StringPerson name

PersonId

StringPerson ID

GenderInteger

Person gender

Array
PersonExDescriptionsofContent of person description field

StringArray
FaceIdsofStringList of contained face images

CreationTimestamp

Integer

Person creation time, measured in the number of milliseconds elapsed©2013-2022 Tencent Cloud. All rights reserved.

Page 311 of 321

Face Recognition

since the Unix epoch
The Unix epoch is 00:00:00, Thursday, January 1, 1970, Coordinated
Universal Time (UTC). For more information, please see the Unix time
document.

Point
Coordinates
Used by actions: AnalyzeFace.
Name

Type

Description

X

Integer

X coordinate

Y

Integer

Y coordinate

ResultFace recognition result
Used by actions: SearchFaces, SearchPersons.
Name
Candidates
FaceRect

Type
Array of
Candidate
FaceRectDescription
Most matching candidate recognized
Position of detected face frame
The status return code for the face image detected. Valid values: 0 - normal;

RetCodeInteger-1601 - the image does not meet the quality requirements, in which case
Candidate is empty; -1604 - the face similarity is not higher thanFaceMatchThreshold .

ResultsReturnsByGroup
Recognition result.
Used by actions: SearchFacesReturnsByGroup, SearchPersonsReturnsByGroup.

©2013-2022 Tencent Cloud. All rights reserved.

Page 312 of 321

Face Recognition

Name

Type

Description

FaceRect

FaceRect

Position of detected face frameGroupCandidates

Array ofGroupCandidate

Recognition result.
Status return code of detected face image. 0: normal.

RetCodeInteger-1601: the image quality control requirement is not met; in this case,
Candidate is empty.

©2013-2022 Tencent Cloud. All rights reserved.

Page 313 of 321

Face Recognition

Error Codes：

Last updated 2023-02-02 17:27:17

Feature Description
If there is an Error field in the response, it means that the API call failed. For example:{"Response": {"Error": {"Code": "AuthFailure.SignatureFailure","Message": "The provided credentials could not be validated. Please check your si
gnature is correct."},"RequestId": "ed93f3cb-f35e-473f-b9f3-0d451b8b79c6"}}
Code in Error indicates the error code, and Message indicates the specific information of the error.

Error Code List
Common Error Codes
Error CodeDescription

ActionOffline

This API has been deprecated.

AuthFailure.InvalidAuthorization

Authorization in the request header is invalid.

AuthFailure.InvalidSecretId

Invalid key (not a TencentCloud API key type).

AuthFailure.MFAFailure

MFA failed.
Key does not exist. Check if the key has been

AuthFailure.SecretIdNotFound

deleted or disabled in the console, and if not, checkif the key is correctly entered. Note that whitespaces
should not exist before or after the key.

AuthFailure.SignatureExpire

Signature expired. Timestamp and server timecannot differ by more than five minutes. Please©2013-2022 Tencent Cloud. All rights reserved.

Page 314 of 321

Face Recognition

ensure your current local time matches the standard
time.
Invalid signature. Signature calculation error. Please
AuthFailure.SignatureFailure

ensure you’ve followed the signature calculation
process described in the Signature API
documentation.

AuthFailure.TokenFailure
AuthFailure.UnauthorizedOperation

Token error.
The request is not authorized. For more information,
see the CAM documentation.
DryRun Operation. It means that the request would

DryRunOperation

have succeeded, but the DryRun parameter wasused.

FailedOperation

Operation failed.

InternalError

Internal error.

InvalidAction

The API does not exist.

InvalidParameter

Incorrect parameter.

InvalidParameterValue

Invalid parameter value.

InvalidRequest

The multipart format of the request body is incorrect.

IpInBlacklist

Your IP is in uin IP blacklist.

IpNotInWhitelistYour IP is not in uin IP whitelist.

LimitExceeded

Quota limit exceeded.

MissingParameter

A parameter is missing.

NoSuchProduct

The product does not exist.

NoSuchVersion

The API version does not exist.

RequestLimitExceeded

The number of requests exceeds the frequency limit.

RequestLimitExceeded.GlobalRegionUinLimitExceeded

Uin exceeds the frequency limit.

RequestLimitExceeded.IPLimitExceeded
RequestLimitExceeded.UinLimitExceeded©2013-2022 Tencent Cloud. All rights reserved.

The number of ip requests exceeds the frequency
limit.
The number of uin requests exceeds the frequency

Page 315 of 321

Face Recognition

limit.
RequestSizeLimitExceeded

The request size exceeds the upper limit.

ResourceInUse

Resource is in use.

ResourceInsufficientInsufficient resource.

ResourceNotFoundThe resource does not exist.

ResourceUnavailable

Resource is unavailable.

ResponseSizeLimitExceeded

The response size exceeds the upper limit.

ServiceUnavailable

Service is unavailable now.

UnauthorizedOperation

Unauthorized operation.

UnknownParameter

Unknown parameter.

UnsupportedOperation

Unsupported operation.

UnsupportedProtocol
UnsupportedRegion

HTTP(S) request protocol error; only GET and
POST requests are supported.
API does not support the requested region.

Service Error Codes
Successful API calls and failed calls with the InvalidParameterValue.NoFaceInPhoto error code will incur charges.
Error CodeDescription

FailedOperation.AcrossVersionsError

This operation cannot be performed acrossalgorithm model versions.

FailedOperation.ConflictOperation
FailedOperation.CreateFaceConcurrent
FailedOperation.DuplicatedGroupDescription

FailedOperation.FaceQualityNotQualified
FailedOperation.FaceSizeTooSmall©2013-2022 Tencent Cloud. All rights reserved.

The operations conflict. Do not operate on thesame person simultaneously.
Faces cannot be added concurrently.
The custom description field must be unique inthe group.
The face image quality does not meet therequirement.
The face frame size is smaller than the

Page 316 of 321

Face Recognition

MinFaceSize value, and the face isfiltered out.
FailedOperation.GroupInDeletedState

FailedOperation.GroupPersonMapExist

FailedOperation.GroupPersonMapNotExist
FailedOperation.ImageDecodeFailed
FailedOperation.ImageDownloadError

The current group is being deleted. Please
wait.
The ID of the corresponding person is alreadyin the group.
The ID of the corresponding person is not in
the group.
Image decoding failed.
An error occurred while downloading theimage.

FailedOperation.ImageFacedetectFailed

Face detection failed.

FailedOperation.ImageResolutionExceed

The image resolution is too high.

FailedOperation.ImageResolutionTooSmall

FailedOperation.ImageSizeExceed

The image short edge resolution is smaller
than 64.
The size of the Base64-encoded image cannot
exceed 5 MB.

FailedOperation.RequestLimitExceeded

The request frequency exceeds the limit.

FailedOperation.RequestTimeout

The backend service timed out.

FailedOperation.RpcFail

The RPC call failed.

FailedOperation.SearchFacesExceed

The number of faces searched for exceeds thelimit.

FailedOperation.ServerError

The algorithm service is exceptional. Please
retry.

FailedOperation.UnKnowError

An internal error occurred.

InvalidParameter.InvalidParameter

Invalid parameter.

InvalidParameterValue.AccountFaceNumExceed

The number of faces in the account exceeds
the limit.

InvalidParameterValue.DeleteFaceNumExceed

The number of faces to be deleted exceeds thelimit. Every person must have at least one face
image.

©2013-2022 Tencent Cloud. All rights reserved.

Page 317 of 321

Face Recognition

InvalidParameterValue.FaceMatchThresholdIllegal

Invalid FaceMatchThreshold parameter.

InvalidParameterValue.FaceModelVersionIllegal

The algorithm model version is invalid.
The array length of the group's custom

InvalidParameterValue.GroupExDescriptionsExceed

InvalidParameterValue.GroupExDescriptionsNameIdenticaldescription fields exceeds the limit. Up to 5
fields can be created.
The name of the group's custom description
field must be unique.
The name of the group's custom description

InvalidParameterValue.GroupExDescriptionsNameIllegal

InvalidParameterValue.GroupExDescriptionsNameTooLong

InvalidParameterValue.GroupFaceNumExceed
InvalidParameterValue.GroupIdAlreadyExist

field contains invalid characters. It can contain
only letters, - , _ , and digits.
The name of the group's custom description
field exceeds the length limit.
The number of faces in the group exceeds thelimit.
The group ID already exists. It must be unique.
The group ID contains invalid characters. It

InvalidParameterValue.GroupIdIllegal

can contain only letters, digits, and special
symbols (-%@#&_).

InvalidParameterValue.GroupIdNotExist

The group ID does not exist.

InvalidParameterValue.GroupIdNotExists

The corresponding group ID does not exist.

InvalidParameterValue.GroupIdTooLong

The group ID exceeds the length limit.

InvalidParameterValue.GroupIdsExceed

The list of groups passed in exceeds the limit.

InvalidParameterValue.GroupNameAlreadyExist

The group name already exists. It must be
unique.

InvalidParameterValue.GroupNameIllegal
InvalidParameterValue.GroupNameTooLong
InvalidParameterValue.GroupNumExceed
InvalidParameterValue.GroupNumPerPersonExceed

The group name contains invalid characters. It
can contain only letters, - , _ , and digits.
The group name exceeds the length limit.
The number of groups exceeds the limit. If you
need more, please contact us.
The number of groups exceeds the limit. One
person can be added to up to 100 groups.

©2013-2022 Tencent Cloud. All rights reserved.

Page 318 of 321

Face Recognition

The group remarks field contains invalid
InvalidParameterValue.GroupTagIllegal

characters. It can contain only letters, - ,_ , and digits.

InvalidParameterValue.GroupTagTooLong

The group remarks field exceeds the length
limit.

InvalidParameterValue.ImageEmpty

Empty image.

InvalidParameterValue.ImageEmptyError

Empty image.

InvalidParameterValue.LimitExceed

The number of returned results exceeds thelimit.

InvalidParameterValue.NoFaceInGroups

There are no faces in the specified group.

InvalidParameterValue.NoFaceInPhoto

There are no faces in the image.

InvalidParameterValue.OffsetExceed

The starting number is too large. Please checkthe length of the array to be requested.
The array length of the person's custom

InvalidParameterValue.PersonExDescriptionInfosExceed

description fields exceeds the limit. Up to 5
fields are allowed.

InvalidParameterValue.PersonExDescriptionsNameIdentical

The name of the person's custom description
field must be unique.
The name of the person's custom description

InvalidParameterValue.PersonExDescriptionsNameIllegal

field contains invalid characters. It can contain
only letters, - , _ , and digits.

InvalidParameterValue.PersonExDescriptionsNameTooLong

InvalidParameterValue.PersonExistInGroupThe name of the person's custom description
field exceeds the length limit.
The ID of the corresponding person is alreadyin the group.
The number of face images for the person

InvalidParameterValue.PersonFaceNumExceed

exceeds the limit. One person can have up to 5
face images.

InvalidParameterValue.PersonGenderIllegal

InvalidParameterValue.PersonIdAlreadyExist©2013-2022 Tencent Cloud. All rights reserved.

An error occurred while setting person gender.
0: empty; 1: male; 2: female.
The person ID already exists. It must be
unique.

Page 319 of 321

Face Recognition

InvalidParameterValue.PersonIdIllegal

The person ID contains invalid characters. It
can contain only letters, digits, and -%@#&_.

InvalidParameterValue.PersonIdNotExist

The person ID does not exist.

InvalidParameterValue.PersonIdTooLong

The person ID field exceeds the length limit.
The person name contains invalid characters.

InvalidParameterValue.PersonNameIllegal

It can contain only letters, - , _ , anddigits.

InvalidParameterValue.PersonNameTooLong

The person name exceeds the length limit.

InvalidParameterValue.QualityControlIllegal

Invalid QualityControl parameter.

InvalidParameterValue.SearchPersonsExceed

InvalidParameterValue.UniquePersonControlIllegal

The number of persons searched for exceeds
the limit.
Invalid UniquePersonControl
parameter.

InvalidParameterValue.UnsupportedGroupFaceModelVersion

This operation is not supported by algorithm
model v2.0 or below.

InvalidParameterValue.UploadFaceNumExceed

Up to four faces can be uploaded at a time.

InvalidParameterValue.UrlIllegal

Invalid URL format.

LimitExceeded.ErrorFaceNumExceed

The number of faces exceeds the limit.

MissingParameter.ErrorParameterEmpty

A required parameter is empty.

ResourceUnavailable.ChargeStatusException

The account is in arrears.

ResourceUnavailable.Delivering

The resource is being shipped.

ResourceUnavailable.Freeze

The account is frozen.

ResourceUnavailable.GetAuthInfoError

Failed to get the authentication information.

ResourceUnavailable.InArrears

The account is in arrears.

ResourceUnavailable.LowBalanceInsufficient balance.
The billing status is unknown. Please check

ResourceUnavailable.NotExist

whether the service has been activated in the
console.

ResourceUnavailable.NotReady

The service is not activated.

©2013-2022 Tencent Cloud. All rights reserved.

Page 320 of 321

Face Recognition

ResourceUnavailable.Recover
ResourceUnavailable.StopUsing

The resource has been repossessed.
The service has been suspended for theaccount.

ResourceUnavailable.UnknownStatus

The billing status is unknown.

ResourcesSoldOut.ChargeStatusException

The billing status is exceptional.

UnsupportedOperation.UnknowMethod

Unknown method name.

©2013-2022 Tencent Cloud. All rights reserved.

Page 321 of 321