人脸搜索
功能介绍
人脸搜索是指在已有的人脸库中，查询与目标人脸相似的一张或者多张人脸，并返回相应的置信度。
支持传入图片或者faceID进行人脸搜索，如果传入的是多张人脸图片，选取图片中检测到的最大尺寸人脸作为检索的输入。
前提条件：
- 只支持识别JPG、PNG、JPEG、BMP格式的图片。
- application/json请求的body中，请使用标准Json格式。
- Base64编码中请勿使用回车换行。
- 系统不保存用户图片。
- 图片大小小于8MB，由于过大图片会导致时延较长，并且图片信息量不大，建议小于1MB。
- 图片分辨率小于4096*2160，图片中人脸像素大于80*80，建议120*120以上。
- 为保证识别效果，人脸图片建议要求如下：
- 光照大于200lux、无反光强光阴影现象。
- 人脸无遮挡、整体清晰无拖尾抖动等运动模糊。
- 侧脸不超过30°、俯仰角小于15°、偏转角小于15°、图片中人脸保持竖置正脸。
- 其他的约束限制信息请参见约束与限制章节。
- 由于过大图片对识别算法精度无明显提升，同时会导致时延较长，建议传入图片小于1MB，一般500KB左右足够。
- OBS上存储的图片也建议小于1MB。
- 图片中人脸像素建议120*120以上。
URI
POST /v2/{project_id}/face-sets/{face_set_name}/search
|
参数 |
参数类型 |
是否必选 |
描述 |
|---|---|---|---|
|
project_id |
String |
是 |
项目ID，获取方法请参见获取项目ID/账号名/AK/SK。 |
|
face_set_name |
String |
是 |
人脸库名称。 |
请求参数
|
参数 |
是否必选 |
参数类型 |
描述 |
|---|---|---|---|
|
X-Auth-Token |
是 |
String |
用户Token。 Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限，响应消息头中X-Subject-Token的值即为Token。 |
|
Content-Type |
是 |
String |
发送的实体的MIME类型，参数值为“application/json”。 |
|
参数名 |
参数类型 |
是否必选 |
说明 |
|---|---|---|---|
|
image_url |
String |
与image_file、image_base64、face_id四选一 |
图片的URL路径，目前仅支持华为云上OBS的URL，且人脸识别服务有权限读取该OBS桶的数据。开通读取权限的操作请参见服务授权。 |
|
image_file |
File |
与image_url、image_base64、face_id四选一 |
本地图片文件，图片不能超过8MB，建议小于1MB。上传文件时，请求格式为multipart。 |
|
image_base64 |
String |
与image_file、image_url、face_id四选一 |
图像数据，Base64编码，要求：
|
|
face_id |
String |
与image_file、image_base64、image_url四选一 |
导入人脸时，系统返回的人脸编号，即人脸ID。 |
|
top_n |
Integer |
否 |
返回查询到的最相似的N张人脸，N默认为10。 N张人脸按照置信度降序排序，置信度越大越靠前。 |
|
threshold |
Double |
否 |
人脸相似度阈值，低于这个阈值则不返回，取值范围0~1，一般情况下建议取值0.93，默认为0。 |
|
sort |
JsonArray |
否 |
支持字段排序，参考sort语法。 |
|
filter |
String |
否 |
过滤条件，参考filter语法。 |
|
return_fields |
JsonArray |
否 |
指定返回的自定义字段。 |
响应参数
状态码： 200
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
faces |
Array of SearchFace objects |
查找的人脸集合，详见SearchFace。 |
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
bounding_box |
BoundingBox object |
人脸在图像中的位置。 |
|
similarity |
Double |
人脸搜索时用于被检索的相似度。 |
|
external_fields |
Object |
用户添加的额外自定义字段。 |
|
external_image_id |
String |
人脸所在的外部图片ID。 |
|
face_id |
String |
人脸ID，由系统内部生成的唯一ID。 |
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
width |
Integer |
矩形框宽度。 |
|
top_left_y |
Integer |
矩形框左上角纵坐标。 |
|
top_left_x |
Integer |
矩形框左上角横坐标。 |
|
height |
Integer |
矩形框高度。 |
状态码： 400
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
error_code |
String |
调用失败时的错误码。 调用成功时无此字段。 |
|
error_msg |
String |
调用失败时的错误信息。 调用成功时无此字段。 |
请求示例
X-Auth-Token值获取方法请参见认证鉴权。
- 请求样例（方式一：使用图片的BASE64编码）
POST https://{endpoint}/v2/{project_id}/face-sets/showFaceSet/search Request Header: Content-Type: application/json X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT... Request Body: { "image_base64": "/9j/4AAQSkZJRgABAgEASABIAAD", "sort" : [ { "timestamp" : "asc" } ], "return_fields" : ["timestamp", "id"], "filter" : "timestamp:12" } - 请求样例（方式二：使用图片文件）
POST https://{endpoint}/v2/{project_id}/face-sets/showFaceSet/search Request Header: X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT... Request Body: image_file: File(图片文件) return_fields: ["timestamp","id"] filter: timestamp:12 - 请求样例（方式三：使用图片URL）
POST https://{endpoint}/v2/{project_id}/face-sets/showFaceSet/search Request Header: Content-Type: application/json X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT... Request Body: { "image_url":"/BucketName/ObjectName", "sort" : [ { "timestamp" : "asc" } ], "return_fields" : ["timestamp", "id"], "filter" : "timestamp:12" } - 请求样例（方式四：使用人脸编号）
POST https://{endpoint}/v2/{project_id}/face-sets/showFaceSet/search Request Header: Content-Type: application/json X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT... Request Body: { "face_id":"6KLB1Ktu", "sort" : [ { "timestamp" : "asc" } ], "return_fields" : ["timestamp", "id"], "filter" : "timestamp:12" }
响应示例
状态码：200
{
"faces": [
{
"bounding_box": {
"width": 170,
"top_left_y": 37,
"top_left_x": 20,
"height": 170
},
"similarity": 0.996146,
"external_image_id": "123",
"external_fields": {
"id": "home",
"timestamp": 12
},
"face_id": "6KLB1Ktu"
},
{
"bounding_box": {
"width": 170,
"top_left_y": 37,
"top_left_x": 20,
"height": 170
},
"similarity": 0.996146,
"external_image_id": "12",
"external_fields": {
"id": "home1",
"timestamp": 12
},
"face_id": "PexOpqRj"
}
]
}状态码：400
{
"error_code": "FRS.0018",
"error_msg": "The service inner error."
}状态码
状态码请参见状态码。
错误码
错误码请参见错误码。
