人脸识别SDK 人脸搜索 创建人脸数据库 查询人脸数据库列表 添加人脸样本 查询人脸样本 查询人脸样本列表 更新人脸样本 添加人脸数据 批量添加人脸数据 删除人脸 删除人脸样本 删除数据库 人脸活体检测

人脸活体检测 功能描述人脸活体检测能力可以检测图像中的人脸是否为来自认证设备端的近距离裸拍活体人脸对象，可广泛应用在人脸实时采集场景，满足人脸注册认证的真实性和安全性要求。活体判断的前置条件是图像中有人脸。　能力范围来看：　1. 认证设备端是指借助近距离裸拍活体正面人脸用于认证、通行等服务场景的含RGB摄像头的硬件设备，常见的认证设备端有手机、门禁机、考勤机、PC等智能终端认证设备。　2. 裸拍活体正面人脸是指真人未经重度PS、风格化、人工合成等后处理的含正面人脸（非模糊、遮挡、大角度的正面人脸）的照片。常见的非真人有纸张人脸、电子屏人脸等；常见经过重度PS后处理的照片有摆拍街景照、摆拍人物风景照、摆拍证件照等；常见的其他后处理及生成照片有动漫人脸、绘画人脸等。应用场景系统人脸登录防攻击：通过检测上传的图像是否为真人实拍，而非攻击及PS等后处理照片，以防止攻击者登录系统带来安全风险。门禁闸机刷脸通行：面向人脸注册和认证环节设备端实时的活体检测，实现注册与认证过程中的真人校验，防止非法分子盗用、伪造他人身份打卡通行。智慧酒店自助入住：在酒店前台自助办理入住场景中，运用活体检测技术实现无人监管场景下，住客非活体攻击（纸张人脸、电子屏人脸）的高效率拦截。金融远程身份认证：面向投资理财、基金交易、保险理赔等金融业务的活体检测需求，高效率实现对翻拍、PS图片、打印图片、高仿模具等攻击的拦截，确保用户身份真实。特色优势基于图片中人像目标的高维度特征（风格化、摩尔纹、成像畸形等），判断目标对象是否为活体，有效防止屏幕二次翻拍等作弊攻击，支持单张或多张判断逻辑。灵活支持RGB摄像头设备的实时活体检测，可有效防止翻拍、头模、打印图片等样本攻击。简单易用：可直接调用的API接口，服务简单易用，易被集成，兼容性强。输入限制图像格式：PNG、JPG、JPEG、BMP、GIF、WEBP。图像大小：不超过10 MB。如您有大图需求，请通过钉钉群（23109592）联系我们。图像分辨率：建议大于256×256像素，像素过低可能会影响识别效果。URL地址中不能包含中文字符。检测说明最长检测时间是5秒，如果在该时间内没有完成检测，系统会强制返回超时错误码。图像下载时间限制为3秒，如果下载时间超过3秒，系统会返回下载超时。图像检测接口响应时间依赖图像的下载时间。请保证被检测图像所在的存储服务稳定可靠，建议您使用阿里云OSS存储或者CDN缓存。最多可检测10张图像。目前平台提供的活体检测为静默活体，即基于图片进行检测，暂不支持摇头，张嘴、眨眼等动作的活体检测。请求参数名称类型是否必选示例值描述ActionString是DetectLivingFace系统规定参数，取值为DetectLivingFaceTasks.N.ImageURLString否http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0.domepic/facebody/DetectLivingFace/DetectLivingFace4.jpg待检测的图像URL地址，JSON数组中的每个元素是一个图片检测任务结构体（image表），最多支持10个元素，即同时最多对10张图片进行检测。推荐使用上海地域的OSS链接Tasks.N.ImageDataString否/9j/4AAQSkZJRgABAQAAAQABAAD/2*图像Base64编码字符串，当与URL方式共存时，URL方式优先返回数据名称类型示例值描述RequestIdString2EA20206-E045-4329-8BED-00677F6EF738请求IDDataObject-返回的结果数据内容ElementsArray of Element-返回的元素ImageURLStringhttp://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0.domepic/facebody/DetectLivingFace/DetectLivingFace4.jpg对应请求中的图像URL地址TaskIdStringemplowerIdWuzhTestAPIt7aZ1**该检测任务的IDResultsArray of Result-返回结果，调用成功时返回结果中包含一个或多个元素SuggestionStringreview建议执行的操作，取值范围如下：pass：图片中的活体对象为直接拍摄的图，无需进行其他操作。review：图片中的活体对象可能是翻拍图，建议审核人员进行操作。block：图片中的活体对象为翻拍图，建议进行拦截操作。如果未检测到人脸，则Suggestion返回值为blockFramesArray of Frame-（仅宇视版）输入图像为长图（宽高比大于3:1）时，会把原图裁成几张近正方形的图，Frames保存从图像中截出来的图而且是截图中的裁剪图UrlStringhttp://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0.domepic/facebody/DetectLivingFace/DetectLivingFace4.jpg?x-oss-process=image/resize,m_lfit,w_500/auto-orient,1/quality,q_90命中的截图RateFloat84.83结果为该分段的概率，取值范围为0.00 - 100.00，取值越大，表示属于该分段的概率越大。如果未检测到人脸，则Rate返回值为0.00LabelStringliveness检测结果分段，取值包括：normal：活体图片liveness：翻拍图片如果未检测到人脸，则Label返回为livenessRateFloat76.22结果为该分段的概率，取值范围为0.00 - 100.00，取值越大，表示属于该分段的概率越大RectObject-人脸的坐标信息LeftLong20检测框左上角的x坐标TopLong30检测框左上角的y坐标WidthLong50检测框宽度HeightLong60检测框高度MessageTipsStringblurred, occluded or large angle face, please check.提示信息。如输入模糊图、遮挡图或大角度等的人脸，则返回提示信息：blurred, occluded or large angle face, please check.如未检测到人脸，则返回提示信息：no face detected, try again please.FaceNumberLong1原图片中检测到的人脸数量。如果未检测到人脸，FaceNumber返回为0活体阈值参考LabelRate阈值攻击拦截率活体通过率liveness5098.7%97.85%liveness3099.03%96.96%normal（推荐）80（推荐）99.17%96.39%normal8599.27%95.55%normal9599.53%92.24%当Label是normal时，表示的是活体，Rate表示活体置信度，Rate取值范围是[80,100]。当Label是liveness时，表示的是非活体，Rate表示非活体置信度，Rate取值范围是[20,100]。关于以上数值的概念定义：攻击拦截率：如98%，代表100次作弊假体攻击，会有98次被API识破拒绝。活体通过率：如98%，代表100次真人请求，会有98次顺利通过活体验证。HTTP/1.1 200 OK Content-Type:application/json { "RequestId" : "2EEA0396-BD84-5729-B8BD-D60776FCEF2B", "Data" : { "Elements" : [ { "ImageURL" : "http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/facebody/DetectLivingFace/DetectLivingFace4.jpg", "TaskId" : "img1owc8WGskNm78OEAPJTZal-1****", "Results" : [ { "Suggestion" : "review", "Frames" : [ { "Url" : "http://aligreen-shanghai.oss-cn-shanghai.aliyuncs.com/prod/hammal/26210da42/28118541_TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png?Expires=1582703593&OSSAccessKeyId=H4sp5QfNbuDg****&Signature=%2B8iUkb5YjomYR8ujV2c8wMAavs****&x-oss-process=image%2Fcrop%2Cx_0%2Cw_288%2Fauto-orient%2C0", "Rate" : 84.83 } ], "Label" : "liveness", "Rate" : 76.22, "Rect" : { "Left" : 20, "Top" : 30, "Width" : 50, "Height" : 60 }, "MessageTips" : "blurred, occluded or large angle face, please check." } ], "FaceNumber" : 1 } ] } }

删除数据库 功能描述删除数据库能力用于删除指定的人脸数据库。请求参数名称类型是否必选示例值描述ActionString是DeleteFaceDb系统规定参数，取值为DeleteFaceDbNameString是default数据库名称返回数据名称类型示例值描述RequestIdString203AE658-CFE1-507D-B105-F88CD1F1F71B请求IDHTTP/1.1 200 OK Content-Type:application/json { "RequestId" : "203AE658-CFE1-507D-B105-F88CD1F1F71B" }

删除人脸样本 功能描述删除人脸样本能力用于删除人脸数据库中的人脸样本数据。请求参数名称类型是否必选示例值描述ActionString是DeleteFaceEntity系统规定参数，取值为DeleteFaceEntityDbNameString是default数据库名称EntityIdString是wood实体ID，如员工编号，可包含数字、字母和下划线返回数据名称类型示例值描述RequestIdStringDA7CAFEB-0A37-4496-9CDF-E3DBB6309CB2请求IDHTTP/1.1 200 OK Content-Type:application/json { "RequestId" : "DA7CAFEB-0A37-4496-9CDF-E3DBB6309CB2" }

删除人脸 功能描述删除人脸能力可以删除指定数据库中的人脸图片信息。请求参数名称类型是否必选示例值描述ActionString是DeleteFace系统规定参数，取值为DeleteFaceDbNameString是default数据库名称FaceIdString是001人脸数据ID返回数据名称类型示例值描述RequestIdStringFAC90D32-2F04-5AD4-B94B-BAA163AB3724请求IDHTTP/1.1 200 OK Content-Type:application/json { "RequestId" : "FAC90D32-2F04-5AD4-B94B-BAA163AB3724" }

批量添加人脸数据 功能描述批量添加人脸数据能力可以为已创建好的人脸样本中批量添加人脸数据，每个人脸样本最多可以添加5张人脸照片，所以批量添加最多一次添加5张人脸照片。输入限制图像格式：JPG、JPEG、PNG、BMP。图像大小：不超过5 MB。图像分辨率：大于32×32像素，小于4096×4096像素。人脸占比不低于64×64像素。URL地址中不能包含中文字符。请求参数名称类型是否必选示例值描述ActionString是BatchAddFaces系统规定参数，取值为BatchAddFacesDbNameString是default数据库名称，支持小写字母、数字、下划线组合，长度1 - 64EntityIdString是U1实体ID，用于标识用户唯一性，每个实体可包含多张人脸图片，支持大小写字母、数字、下划线、减号组合，长度2 - 64字符SimilarityScoreThresholdInEntityFloat否50.0类内相似度阈值，将新增人脸图片与EntityId内已有人脸进行相似度比对，小于该阈值则添加失败；若EntityId内没有人脸存在，则添加成功。取值范围[0.0, 100.0]，0.0或空表示不做类内相似度判断逻辑SimilarityScoreThresholdBetweenEntityFloat否50.0类间相似度阈值，将新增人脸图片与其他所有EntityId内已有人脸进行相似度比对，大于等于该阈值则表示其他EntityId内存在相似人脸，出现重复，添加失败。取值范围[0.0, 100.0]，0.0或空表示不做类间相似度判断逻辑FacesArray是-人脸信息ExtraDataString否王小二自定义信息，支持字母、数字、标点符号和汉字，不超过512个字符ImageUrlString是https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imsearch/demo/1.png人脸图像URL地址，人脸必须是正面无遮挡单人脸，推荐使用上海地域的OSS链接QualityScoreThresholdFloat否50.0质量分阈值，对新增人脸图片进行质量分析判断，得到的质量分小于该阈值则表示新增人脸图片质量不符合要求，添加失败。取值范围[0.0, 100.0]，0.0或空则表示不做质量分判断逻辑返回数据名称类型示例值描述RequestIdStringC46A46D0-3263-181A-A1EE-0901E4595390请求IDDataObject-返回的结果数据内容InsertedFacesArray of InsertedFaces-添加成功的记录结果ImageUrlStringhttps://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imsearch/demo/xxxx.png人脸图像地址，与输入的ImageUrl相同，用来标记图像记录FaceIdString16350536输出人脸IDQualityScoreFloat99.79581输入图像中的人脸质量分FailedFacesArray of failedFaces-添加失败的记录结果ImageUrlStringhttps://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imsearch/demo/xxxx.png人脸图像地址，与输入的ImageUrl相同，用来标记图像记录CodeStringClientError.IllegalArgument错误码MessageStringnot found the db=test错误信息HTTP/1.1 200 OK Content-Type:application/json { "RequestId" : "C46A46D0-3263-181A-A1EE-0901E4595390", "Data" : { "InsertedFaces" : [ { "ImageURL" : "https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imgsearch/demo/xxxx.png", "FaceId" : "16350536", "QualitieScore" : 99.79581 } ], "FailedFaces" : [ { "ImageURL" : "https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imgsearch/demo/xxxx.png", "Code" : "ClientError.IllegalArgument", "Message" : "not found the db=test" } ] } }

添加人脸数据 功能描述添加人脸数据能力可以为指定数据库添加人脸数据，单个人脸数据库支持最多5万张人脸照片入库，人脸数据是在已创建好的人脸样本中添加，每个人脸样本最多可以添加5张人脸照片。人脸照片入库量以及每个人脸样本最多添加的照片量暂不支持扩容。输入限制图像格式：JPG、JPEG、PNG。图像大小：不超过5 MB。图像分辨率：大于32×32像素，小于4096×4096像素。人脸占比不低于64×64像素。URL地址中不能包含中文字符。图片中若包含多个人脸，会取最大的人脸进行添加。请求参数名称类型是否必选示例值描述ActionString是AddFace系统规定参数，取值为AddFaceDbNameString是default数据库名称，支持小写字母、数字、下划线的组合，长度1 - 64ImageUrlString是https://viapi-test.oss-cn-shanghai.aliyuncs.com/test/imsearch/demo/1.png人脸图片地址，人脸须为正面无遮挡人脸（若包含多张人脸则取最大人脸添加），推荐使用上海地域OSS链接EntityIdString是U1实体ID，用于标识用户唯一性，每个实体可包含多张人脸图片，支持大小写字母、数字、下划线、减号组合，长度1 - 64字符ExtraDataString否王小二自定义信息，支持字母、数字、标点符号和汉字，不超过512个字符QualityScoreThresholdFloat否50.0质量分阈值，对新增人脸图片进行质量分析，质量分小于该阈值则添加失败，取值范围[0.0,100.0]，0.0或空表示不做质量判断SimilarityScoreThresholdInEntityFloat否50.0类内相似度阈值，将新增人脸图片与EntityId内已有人脸进行相似度比对，小于该阈值则添加失败，取值范围[0.0,100.0]，0.0或空表示不做类内相似度判断SimilarityScoreThresholdBetweenEntityFloat否50.0类间相似度阈值，将新增人脸图片与其他所有EntityId内已有人脸进行相似度比对，大于等于该阈值则添加失败，取值范围[0.0,100.0]，0.0或空表示不做类间相似度判断返回数据名称类型示例值描述RequestIdString2B93C43A-F824-40C8-AF79-844342B0F43A请求IDDataObject-返回的结果数据内容FaceIdString5输出人脸IDQualityScoreFloat99.79581输入图像中的人脸质量分HTTP/1.1 200 OK Content-Type:application/json { "RequestId" : "2B93C43A-F824-40C8-AF79-844342B0F43A", "Data" : { "FaceId" : "5", "QualitieScore" : 99.79581 } }

更新人脸样本 功能描述更新人脸样本能力用于更新人脸数据库中的人脸样本数据。请求参数名称类型是否必选示例值描述DbNameString是default数据库名称EntityIdString是mm2实体ID，如用户ID、员工ID等LabelsString否鹿班标签名称，最多可以添加10个标签返回数据名称类型示例值描述RequestIdStringDA7CAFEB-0A37-4496-9CDF-E3DBB6309CB2请求IDHTTP/1.1 200 OK Content-Type:application/json { "RequestId" : "DA7CAFEB-0A37-4496-9CDF-E3DBB6309CB2" }

查询人脸样本列表 功能描述查询人脸样本列表能力用于查询人脸数据库中的人脸样本列表。这两张图片展示了列出人脸实体接口的请求参数和返回数据结构。请求参数名称类型是否必选示例值描述DbNameString是default数据库名称OffsetInteger否1起始记录，取值范围0~2000LimitInteger否50每页最多显示的样本数目，取值范围1~200TokenString否2当查询结果超过2000条时，需用上一次请求返回的Token作为请求下一页的参数LabelsString否鹿班标签，最多支持10个，多个标签以英文逗号分割EntityIdPrefixString否U1样本ID前缀，包含数字、字母和下划线OrderString否asc排列方式，包括asc（升序）和desc（降序）返回数据名称类型示例值描述RequestIdStringDA7CAFEB-0A37-4496-9CDF-E3DBB6309CB2请求IDDataObject-返回的结果数据内容TokenString2当查询结果超过2000条时，可使用Token查询下一页数据TotalCountInteger200人脸样本的总数量EntitiesArray of Entity-查询到的实体数据DbNameStringdefault人脸样本所在的数据库名称EntityIdString222实体ID，如员工编号LabelsString鹿班查询到的人脸数据标签CreatedAtLong1589203871832人脸样本的创建时间FaceCountInteger3人脸样本包含的人脸数量UpdatedAtLong1589203871832人脸样本的更新时间HTTP/1.1 200 OK Content-Type:application/json { "RequestId" : "DA7CAFEB-0A37-4496-9CDF-E3DBB6309CB2", "Data" : { "Token" : "2", "TotalCount" : "200", "Entities" : [ { "DbName" : "default", "EntityId" : "222", "FaceCount" : "3", "Labels" : "鹿班", "CreatedAt" : "1589203871832", "UpdatedAt" : "1589203871832" } ] } }

查询人脸样本 功能描述查询人脸样本能力用于查询人脸数据库中的人脸样本数据。请求参数名称类型是否必选示例值描述DbNameString是default数据库名称EntityIdString是66实体ID，可以包含数字、字母和下划线返回数据名称类型示例值描述RequestIdStringDA7CAFEB-0A37-4496-9CDF-E3DBB6309CB2请求IDDataObject-返回的结果数据内容DbNameStringdefault数据库名称EntityIdString66实体IDLabelsString工厂查询到的人脸标签FacesArray of Face-查询到的人脸数据FaceIdString3人脸数据IDHTTP/1.1 200 OK Content-Type:application/json { "RequestId" : "DA7CAFEB-0A37-4496-9CDF-E3DBB6309CB2", "Data" : { "DbName" : "default", "EntityId" : "66", "Labels" : "工厂", "Faces" : [ { "FaceId" : "3" } ] } }