人脸搜索
人脸搜索
人脸搜索依赖人脸库，在使用前请先创建对应的人脸库；
人脸搜索支持单人脸搜索和多人脸搜索：
- 单人脸搜索：输入单人脸图片，返回与输入人脸最相似的用户信息，最多返回50个，如果输入图片中包括多个人，只检测图片中面积最大的那个人脸；
- 多人脸搜索：输入包括多个人脸的图片，返回每个人脸(最多支持10个用户的搜索)最相似的用户信息，最多返回20个；
人脸搜索需要指定匹配阈值，范围0~100，设置阈值后，score低于此阈值的用户信息将不会返回，此阈值设置的越高，检索速度会越快，根据场景推荐设置阈值60~80；
单人脸搜索
输入单人脸图片，返回与输入人脸最相似的用户信息；
请求Url
POST /v1/human/face/search HTTP/1.1
Request参数
| 参数 | 可选 | 类型 | 说明 |
|---|---|---|---|
| image_base64 | 必选 | String | 图片base64编码，iamge_base64和image_url二选一即可，优先使用image_base64 |
| image_url | 必选 | String | 图片url，只有当image_base64为空时才会使用image_url下载图片再base64编码，增加下载时延 |
| group_id_list | 必选 | String | 人脸库group_id列表，逗号分隔，上限10个 |
| user_id | 可选 | String | 指定用户ID，只会在该user_id的人脸中搜索 |
| match_threshold | 必选 | Integer | 人脸搜索需要指定匹配阈值，范围0~100，默认值80，设置阈值后，score低于此阈值的用户信息将不会返回 |
| quality_control | 可选 | String | 图片质量控制，默认NONE，若图片质量不满足要求，则返回结果中会提示质量检测失败 |
| liveness_control | 可选 | String | 活体检测控制，默认NONE，若活体检测结果不满足要求，则返回结果中会提示活体检测失败 |
| max_user_num | 可选 | Integer | 返回相似用户的个数，默认值1，返回最相似的用户，最多返回50个 |
Response参数
| 参数 | 类型 | 说明 |
|---|---|---|
| code | Integer | 0：请求成功，非0：请求失败 |
| message | String | 请求成功message为空，请求失败为失败提示信息 |
| data | Object | 搜索结果 |
| +face_token | String | 输入人脸的face_token |
| +user_list | List | 搜索结果用户列表 |
| ++group_id | String | 用户对应的人脸库group_id |
| ++user_id | String | 用户id |
| ++user_info | String | 用户信息 |
| ++score | String | 匹配相似度 |
多人脸搜索
输入包括多个人脸的图片，返回每个人脸最相似的用户信息；
请求Url
POST /v1/human/face/msearch HTTP/1.1
Request参数
| 参数 | 可选 | 类型 | 说明 |
|---|---|---|---|
| image_base64 | 必选 | String | 图片base64编码，iamge_base64和image_url二选一即可，优先使用image_base64 |
| image_url | 必选 | String | 图片url，只有当image_base64为空时才会使用image_url下载图片再base64编码，增加下载时延 |
| group_id_list | 必选 | String | 人脸库group_id列表，逗号分隔，上限10个 |
| max_face_num | 可选 | Integer | 最多处理的人脸数目，默认值10，最大值10，设置1功能等同于单人脸搜索 |
| match_threshold | 必选 | Integer | 人脸搜索需要指定匹配阈值，范围0~100，默认值80，设置阈值后，score低于此阈值的用户信息将不会返回 |
| max_user_num | 可选 | Integer | 返回相似用户的个数，默认值1，返回最相似的用户，最多返回20个 |
Response参数
| 参数 | 类型 | 说明 |
|---|---|---|
| code | Integer | 0：请求成功，非0：请求失败 |
| message | String | 请求成功message为空，请求失败为失败提示信息 |
| data | Object | 搜索结果 |
| +items | List | 输入图片中每个人脸的搜索结果 |
| ++face_token | String | 人脸的face_token |
| ++user_list | List | 搜索结果用户列表 |
| +++group_id | String | 用户对应的人脸库group_id |
| +++user_id | String | 用户id |
| +++user_info | String | 用户信息 |
| +++score | String | 匹配相似度 |
| +item_count | Integer | 人脸数量 |
质量控制
图片质量控制：
| 可选值 | 说明 |
|---|---|
| NONE | 不进行控制 |
| LOW | 较低的质量要求 |
| NORMAL | 一般的质量要求 |
| HIGH | 较高的质量要求 |
遮挡情况的阈值：
| 控制度 | left_eye | right_eye | nose | mouth | left_cheek | right_cheek | chin_contour |
|---|---|---|---|---|---|---|---|
| LOW | 0.8 | 0.8 | 0.8 | 0.8 | 0.8 | 0.8 | 0.8 |
| NORMAL | 0.6 | 0.6 | 0.6 | 0.6 | 0.6 | 0.6 | 0.6 |
| HIGH | 0.2 | 0.2 | 0.2 | 0.2 | 0.2 | 0.2 | 0.2 |
模糊度、完整度的阈值
| 控制度 | illumination | blurdegree | completeness |
|---|---|---|---|
| LOW | 20 | 0.8 | 0 |
| NORMAL | 40 | 0.6 | 0 |
| HIGH | 100 | 0.2 | 1 |
活体控制
活体检测控制:
| 可选值 | 说明 |
|---|---|
| NONE | 不进行控制 |
| LOW | 较低的活体要求(高通过率, 低攻击拒绝率) |
| NORMAL | 一般的活体要求(平衡的攻击拒绝率, 通过率) |
| HIGH | 较高的活体要求(高攻击拒绝率, 低通过率) |
