接口请求域名： iai.intl.tencentcloudapi.com 。
用于对一张待识别的人脸图片，在一个或多个人员库中识别出最相似的 TopK 人员，按照相似度从大到小排列。
支持一次性识别图片中的最多 10 张人脸，支持一次性跨 100 个人员库（Group）搜索。
单次搜索的人员库人脸总数量和人员库的算法模型版本（FaceModelVersion）相关。算法模型版本为2.0的人员库，单次搜索人员库人脸总数量不得超过 100 万张；算法模型版本为3.0的人员库，单次搜索人员库人脸总数量不得超过 300 万张。
本接口会将该人员（Person）下的所有人脸（Face）进行融合特征处理，即若某个 Person 下有4张 Face ，本接口会将4张 Face 的特征进行融合处理，生成对应这个 Person 的特征，使人员搜索（确定待识别的人脸图片是某人）更加准确。而人脸搜索及人脸搜索按库返回接口将该人员（Person）下的每个人脸（Face）都作为单独个体进行搜索。
注意：若人员库超过1年未调用，平台将对人员库资源进行删除，以确保用户信息安全。
- 公共参数中的签名方式请使用V3版本，即配置SignatureMethod参数为TC3-HMAC-SHA256。
- 仅支持算法模型版本（FaceModelVersion）为3.0的人员库。
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：SearchPersons。 |
| Version | 是 | String | 公共参数，本接口取值：2020-03-03。 |
| Region | 是 | String | 公共参数，详见产品支持的 地域列表，本接口仅支持其中的: ap-beijing, ap-chengdu, ap-chongqing, ap-guangzhou, ap-jakarta, ap-nanjing, ap-shanghai, ap-singapore 。 |
| GroupIds.N | 是 | Array of String | 希望搜索的人员库列表，上限100个。数组元素取值为创建人员库接口中的GroupId。 |
| Image | 否 | String | 图片 base64 数据。
|
| Url | 否 | String | 图片的 Url 。
|
| MaxFaceNum | 否 | Integer | 最多识别的人脸数目。
|
| MinFaceSize | 否 | Integer | 人脸长和宽的最小尺寸，单位为像素。
|
| MaxPersonNum | 否 | Integer | 单张被识别的人脸返回的最相似人员数量。
|
| QualityControl | 否 | Integer | 图片质量控制。
|
| FaceMatchThreshold | 否 | Float | 出参Score中，只有大于等于FaceMatchThreshold值的结果才会返回。
|
| NeedPersonInfo | 否 | Integer | 是否返回人员具体信息。
|
| NeedRotateDetection | 否 | Integer | 是否开启图片旋转识别支持。
|
| Encryption | 否 | Encryption | 是否需要对请求信息进行全包体加密。支持的加密算法:AES-256-CBC。有加密需求的用户可使用此参数。 |
| EncryptedBody | 否 | String | 加密后的密文。加密前的数据格式如下:{"Url":"","Image":""}。 |
| 参数名称 | 类型 | 描述 |
|---|---|---|
| Results | Array of Result | 识别结果。 |
| PersonNum | Integer | 搜索的人员库中包含的人员数。若输入图片中所有人脸均不符合质量要求，则返回0。 |
| FaceModelVersion | String | 人脸识别所用的算法模型版本。 |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
https://iai.intl.tencentcloudapi.com/?Action=SearchPersons
&Url=http://test.image.myqcloud.com/testA
&GroupIds.0=TencentShenZhenEmployee
&<公共请求参数>{
"Response": {
"Error": {
"Code": "FailedOperation.ImageDownloadError",
"Message": "图片下载错误。"
},
"RequestId": "527ecffe-4c6a-47c9-8217-4dd2e3f018da"
}
}https://iai.intl.tencentcloudapi.com/?Action=SearchPersons
&Url=http://test.image.myqcloud.com/testA.jpg
&MaxFaceNum=2
&MinFaceSize=40
&MaxPersonNum=3
&GroupIds.0=TencentShenZhenEmployee
&<公共请求参数>{
"Response": {
"Results": [
{
"RetCode": 0,
"Candidates": [
{
"PersonId": "person1",
"FaceId": "",
"Score": 100,
"PersonName": null,
"Gender": null,
"PersonGroupInfos": null
},
{
"PersonId": "person2",
"FaceId": "",
"Score": 60,
"PersonName": null,
"Gender": null,
"PersonGroupInfos": null
},
{
"PersonId": "person3",
"FaceId": "",
"Score": 50,
"PersonName": null,
"Gender": null,
"PersonGroupInfos": null
}
],
"FaceRect": {
"X": 139,
"Y": 59,
"Width": 124,
"Height": 162
}
},
{
"RetCode": 0,
"Candidates": [
{
"PersonId": "person2",
"FaceId": "",
"Score": 100,
"PersonName": null,
"Gender": null,
"PersonGroupInfos": null
},
{
"PersonId": "person1",
"FaceId": "",
"Score": 60,
"PersonName": null,
"Gender": null,
"PersonGroupInfos": null
},
{
"PersonId": "person3",
"FaceId": "",
"Score": 20,
"PersonName": null,
"Gender": null,
"PersonGroupInfos": null
}
],
"FaceRect": {
"X": 328,
"Y": 70,
"Width": 119,
"Height": 162
}
}
],
"PersonNum": 5,
"FaceModelVersion": "3.0",
"RequestId": "c4608852-ff60-4a01-8dc3-367f6046baaf"
}
}云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| AuthFailure.InvalidAuthorization | 认证失败。 |
| FailedOperation.AcrossVersionsError | 该操作不支持跨算法模型版本。 |
| FailedOperation.DecryptSystemError | Decryption failed. |
| FailedOperation.FaceSizeTooSmall | 人脸框大小小于MinFaceSize设置，人脸被过滤。 |
| FailedOperation.ImageDecodeFailed | 图片解码失败。 |
| FailedOperation.ImageDownloadError | 图片下载错误。 |
| FailedOperation.ImageFacedetectFailed | 人脸检测失败。 |
| FailedOperation.ImageResolutionExceed | 图片分辨率过大。 |
| FailedOperation.ImageResolutionTooSmall | 图片短边分辨率小于64。 |
| FailedOperation.ImageSizeExceed | base64编码后的图片数据大小不超过5M。 |
| FailedOperation.RequestLimitExceeded | 请求频率超过限制。 |
| FailedOperation.RequestTimeout | 后端服务超时。 |
| FailedOperation.SearchFacesExceed | 检索人脸个数超过限制。 |
| FailedOperation.ServerError | 算法服务异常，请重试。 |
| InternalError | 内部错误。 |
| InvalidParameter.InvalidParameter | 参数不合法。 |
| InvalidParameterValue.FaceMatchThresholdIllegal | FaceMatchThreshold参数不合法。 |
| InvalidParameterValue.GroupIdIllegal | 人员库ID包含非法字符。人员库ID只支持英文、数字、-%@#&_。 |
| InvalidParameterValue.GroupIdNotExist | 人员库ID不存在。 |
| InvalidParameterValue.GroupIdTooLong | 人员库ID超出长度限制。 |
| InvalidParameterValue.GroupIdsExceed | 传入的人员库列表超过限制。 |
| InvalidParameterValue.ImageEmpty | 图片为空。 |
| InvalidParameterValue.ImageEmptyError | 图片为空。 |
| InvalidParameterValue.InvalidParameter | Invalid encryption parameters. |
| InvalidParameterValue.NoFaceInGroups | 指定分组中没有人脸。 |
| InvalidParameterValue.NoFaceInPhoto | 图片中没有人脸。 |
| InvalidParameterValue.QualityControlIllegal | QualityControl参数不合法。 |
| InvalidParameterValue.SearchPersonsExceed | 搜索的人员数目超过限制。 |
| InvalidParameterValue.UnsupportedGroupFaceModelVersion | 该操作不支持算法模型版本2.0及以下版本。 |
| InvalidParameterValue.UrlIllegal | URL格式不合法。 |
| MissingParameter.ErrorParameterEmpty | 必选参数为空。 |
| ResourceUnavailable.ChargeStatusException | 账号已欠费。 |
| ResourceUnavailable.Freeze | 账号已被冻结。 |
| ResourceUnavailable.GetAuthInfoError | 获取认证信息失败。 |
| ResourceUnavailable.InArrears | 账号已欠费。 |
| ResourceUnavailable.LowBalance | 余额不足。 |
| ResourceUnavailable.NotExist | 计费状态未知，请确认是否已在控制台开通服务。 |
| ResourceUnavailable.NotReady | 服务未开通。 |
| ResourceUnavailable.Recover | 资源已被回收。 |
| ResourceUnavailable.StopUsing | 账号已停服。 |
| ResourceUnavailable.UnknownStatus | 计费状态未知。 |
| ResourcesSoldOut.ChargeStatusException | 计费状态异常。 |
| UnsupportedOperation.UnknowMethod | 未知方法名。 |
文档反馈