本文介绍人脸搜索SearchFace的语法及示例。

功能描述

人脸搜索功能可以根据输入图片,在数据库中搜索并返回相似的人脸图片数据。单次搜索的人脸总数最多20万张,单次搜索可支持最多20个人脸数据库的同时搜索(跨库搜索)。如有更多需求请提工单申请。

应用场景

  • 人脸门禁:实时抓拍门禁前的人员正脸照片,与客户已获授权拥有的注册库比对,返回特征值相似度最高且超过阈值的注册库ID。客户系统可结合自己的业务规划,判断当前人员是否可以通过门禁。
  • VIP服务:在VIP会员授权前提下,VIP会员到店时,通过授权抓拍的人脸照片,与VIP会员注册库中人脸照片进行特征比对,返回最相似的人脸ID。客户的业务系统识别到VIP会员后,向会员提供更加周到细致的服务。
  • 生产安全:工地、厂区、保密区域,识别是否有未授权的人员非法进入,保障生产安全。

特色优势

  • 识别精度高:人脸检测识别等算法精度处于业内领先水平。
  • 识别效率高:毫秒级响应,支持实时识别。

前提条件

请确保您已开通人脸人体服务,若未开通服务请立即开通

说明 如果您是已经在使用的老客户,需要使用海量人脸建库和搜索的能力,请提工单申请。

输入限制

  • 图片格式:JPG、JPEG、PNG。
  • 图片大小:不超过5M。
  • 图片像素:大于5×5像素,小于4096×4096像素。人脸尺寸建议大于64×64像素。
  • URL地址中不能包含中文字符。
说明 支持图片中包含最多5个人脸,超过部分会被忽略。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String SearchFace

要执行的操作。取值:SearchFace。

ImageUrl String https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imgsearch/demo/1.png

图片URL地址。当前仅支持上海地域的OSS链接,如何生成URL请参见生成URL

Limit Integer 2

搜索结果数量限制,取值范围1~1000。

DbName String default

数据库名称。

DbNames String test1,test2,test3

数据库名称列表,以英文逗号分割,可以实现跨库查询,最大支持20个数据库。

说明 该字段为预留字段,目前还未开放。

返回数据

名称 类型 示例值 描述
Data Struct

返回的结果数据内容。

MatchList Array of MatchList

匹配的结果列表,如果输入图像中多个人脸,则这里会返回多个数据。

FaceItems Array of FaceItems

匹配的人脸数据列表。

DbName String default

数据库名称。

EntityId String U1

实体ID,用来标识用户的唯一性,如用户ID、员工ID等。每个实体可包含多张人脸图片。支持大小写字母、数字、下划线和减号的组合,长度为2~64。

ExtraData String 王小二

自定义信息(字符串)。支持字母、数字、标点符号和汉字。不超过512个字符。

FaceId String 001

人脸图片数据ID,需要全局唯一,不可重复。支持小写字母、数字和下划线的组合。长度为1~64。

Score Float 0.892133

人脸的相似度,取值范围-1.0~1.0,取小数点后6位,数值越大相似度越高。

Location Struct

输入图像中的人脸坐标信息。

Height Integer 200

高度,单位像素。

Width Integer 200

宽度,单位像素。

X Integer 5

左上角x坐标。

Y Integer 6

左上角y坐标。

RequestId String 4159e64a-0fe8-436c-a8de-ee531555db3c

请求ID。

示例

请求示例

http(s)://[Endpoint]/?Action=SearchFace
&ImageUrl=https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imgsearch/demo/1.png
&Limit=2
&<公共请求参数>

正常返回示例

XML 格式

<RequestId>4159e64a-0fe8-436c-a8de-ee531555db3c</RequestId>
<Data>
    <MatchList>
        <FaceItems>
            <EntityId>U1</EntityId>
            <FaceId>001</FaceId>
            <Score>0.89</Score>
            <DbName>default</DbName>
            <ExtraData>王小二</ExtraData>
        </FaceItems>
    </MatchList>
    <MatchList>
        <Location>
            <X>5</X>
            <Y>6</Y>
            <Height>200</Height>
            <Width>200</Width>
        </Location>
    </MatchList>
</Data>

JSON 格式

{
    "RequestId": "4159e64a-0fe8-436c-a8de-ee531555db3c",
    "Data": {
        "MatchList": [
            {
                "FaceItems": {
                    "EntityId": "U1",
                    "FaceId": 1,
                    "Score": 0.89,
                    "DbName": "default",
                    "ExtraData": "王小二"
                }
            },
            {
                "Location": {
                    "X": 5,
                    "Y": 6,
                    "Height": 200,
                    "Width": 200
                }
            }
        ]
    }
}

错误码

关于人脸搜索的错误码,详情请参见常见错误码

SDK参考

阿里云视觉AI能力支持使用SDK调用,具体可参见SDK总览下载安装。

安全声明

  • 请确保上传的图片或文件来源符合相应的法律法规。
  • 通过体验调试上传的临时文件有效期为1小时,在24小时后会被系统自动清理删除。