本文介绍人脸搜索SearchFace的语法及示例。
功能描述
人脸搜索功能可以根据输入图片,在数据库中搜索并返回相似的人脸图片数据。单次搜索的人脸总数最多20万张,单次搜索可支持最多20个人脸数据库的同时搜索(跨库搜索)。如有更多需求请提工单申请。
应用场景
- 人脸门禁:实时抓拍门禁前的人员正脸照片,与客户已获授权拥有的注册库比对,返回特征值相似度最高且超过阈值的注册库ID。客户系统可结合自己的业务规划,判断当前人员是否可以通过门禁。
- VIP服务:在VIP会员授权前提下,VIP会员到店时,通过授权抓拍的人脸照片,与VIP会员注册库中人脸照片进行特征比对,返回最相似的人脸ID。客户的业务系统识别到VIP会员后,向会员提供更加周到细致的服务。
- 生产安全:工地、厂区、保密区域,识别是否有未授权的人员非法进入,保障生产安全。
特色优势
- 识别精度高:人脸检测识别等算法精度处于业内领先水平。
- 识别效率高:毫秒级响应,支持实时识别。
前提条件
输入限制
- 图片格式:JPG、JPEG、PNG。
- 图片大小:不超过5M。
- 图片像素:大于5×5像素,小于4096×4096像素。人脸尺寸建议大于64×64像素。
- URL地址中不能包含中文字符。
调试
您可以在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小时后会被系统自动清理删除。
在文档使用中是否遇到以下问题
更多建议
匿名提交