文档首页 > > API参考> 人脸识别API> 人脸搜索

人脸搜索

分享
更新时间: 2019/09/09 15:06

功能介绍

人脸搜索是指在已有的人脸库中,查询与目标人脸相似的一张或者多张人脸,并返回相应的置信度。

支持传入图片或者faceID进行人脸搜索,如果传入的是多张人脸图片,选取图片中检测到的最大尺寸人脸作为检索的输入。

说明:
  • 只支持识别JPG、PNG、JPEG、BMP格式的图片。
  • 图片大小小于8MB。
  • 上传的人脸图片要求:侧脸不超过30°,抬头低头不超过15°,图片中人脸保持竖置正脸。
  • 系统只存储图片的特征,不负责保存用户图片。
  • application/json请求的body中,请使用标准Json格式。
  • Base64编码中请勿使用回车换行。

URI

  • URI格式
    POST /v1/{project_id}/face-sets/{face_set_name}/search
  • 参数说明

    参数名

    参数类型

    是否必选

    说明

    project_id

    String

    项目ID,获取方法请参见获取项目ID/账号名/AK/SK

    face_set_name

    String

    人脸库名称。

请求消息

表1 请求参数

参数名

参数类型

是否必选

说明

image_url

String

与image_file、image_base64、face_id四选一

图片的URL路径,目前仅支持华为云上OBS的URL,且人脸识别服务有权限读取该OBS桶的数据。开通读取权限的操作请参见服务授权

image_file

File

与image_url、image_base64、face_id四选一

本地图片文件,图片不能超过8MB。上传文件时,请求格式为multipart。

image_base64

String

与image_file、image_url、face_id四选一

图像数据,Base64编码,要求:
  • Base64编码后大小不超过8MB。
  • 图片为JPG/JPEG/BMP/PNG格式。

face_id

String

与image_file、image_base64、image_url四选一

导入人脸时,系统返回的人脸编号,即人脸ID。

top_n

Integer

返回查询到的最相似的N张人脸,N默认为10。

threshold

Double

人脸相似度阈值,低于这个阈值则不返回,取值范围0~1,一般情况下建议取值0.93,默认为0。

sort

JsonArray

支持字段排序,参考sort语法

filter

String

过滤条件,参考filter语法

return_fields

String

指定返回的自定义字段。

响应消息

表2 响应参数

参数名

参数类型

说明

faces

List

查找的人脸集合,详见SearchFace

调用失败时无此字段。

error_code

String

调用失败时的错误码,具体请参考错误码

调用成功时无此字段。

error_msg

String

调用失败时的错误信息。

调用成功时无此字段。

示例

  • 请求样例(方式一:使用图片的BASE64编码)
    POST https://{endpoint}/v1/{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}/v1/{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}/v1/{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}/v1/{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" 
    }
  • 响应样例
    {
      "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"
        }
      ]
    }
  • 失败响应样例
    {
      "error_code": "FRS.0018",
      "error_msg": "The service inner error."
    }

状态码

状态码请参见状态码

错误码

错误码请参见错误码

分享:

    相关文档

    相关产品

文档是否有解决您的问题?

提交成功!

非常感谢您的反馈,我们会继续努力做到更好!

反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区问答频道来与我们联系探讨

跳转到云社区