人脸识别

    人脸查找

    概述

    人脸识别接口分为V2和V3两个版本,本文档为V2版本接口的说明文档,请确认您在百度云后台获得的是V2版本接口权限,再来阅读本文档。

    辨别接口版本的方法是:在百度云后台进入【应用列表】,点击【应用名称】,在【API列表】中可以看到【请求地址】,若请求地址中带有【v2】标识,则您具有的是v2权限,可以阅读本文档;若请求地址中带有【v3】标识,则您具有的是v3权限,应该去阅读v3文档。 如果您对文档内容有任何疑问,可以通过以下几种方式联系我们:

    • 在百度云控制台内 提交工单,咨询问题类型请选择人工智能服务
    • 如有需要讨论的疑问,欢迎进入 AI社区 与其他开发者们一同交流。

    能力介绍

    业务能力

    • 1:N人脸识别:也称为1:N识别,在指定人脸集合中,找到最相似的人脸;
    • 1:N人脸认证:基于uid维度的1:N识别,由于uid已经锁定固定数量的人脸,所以检索范围更聚焦;
    • M:N多人脸识别:也称为M:N识别,待识别图片中含有多个人脸时,在指定人脸集合中,找到这多个人脸分别最相似的人脸;

    1:N人脸识别1:N人脸认证的差别在于:人脸识别是在指定人脸集合中进行直接地人脸检索操作,而人脸认证是基于uid,先调取这个uid对应的人脸,再在这个uid对应的人脸集合中进行检索(因为每个uid通常对应的只有一张人脸,所以通常也就变为了1:1对比);实际应用中,人脸认证需要用户或系统先输入id,这增加了验证安全度,但也增加了复杂度,具体使用哪个接口需要视您的业务场景判断。

    M:N识别的原理,相当于在多个人脸的图片中,先分别找出所有人脸,然后分别在待查找的人脸集合中,分别做1:N识别,最后将识别结果汇总在一起进行返回。

    提示:进行人脸查找相关操作前,建议先阅读 人脸库管理 相关内容。

    调用方式

    请求URL数据格式

    向API服务地址使用POST发送请求,必须在URL中带上参数access_token,可通过后台的API Key和Secret Key生成,具体方式请参考“Access Token获取”。

    获取access_token的示例代码

    {% AccessToken %}

    注意access_token的有效期为30天,切记需要每30天进行定期更换,或者每次请求都拉取新token

    例如此接口,使用HTTPS POST发送:

    https://aip.baidubce.com/rest/2.0/face/v2/identify?access_token=24.f9ba9c5341b67688ab4added8bc91dec.2592000.1485570332.282335-8574074

    POST中Body的参数,按照下方请求参数说明选择即可。

    提示:如果您为百度云老用户,正在使用其他非AI的服务,可以参考百度云AKSK鉴权方式发送请求,虽然请求方式鉴权方法和本文所介绍的不同,但请求参数和返回结果一致。

    人脸识别

    接口描述

    用于计算指定组内用户,与上传图像中人脸的相似度。识别前提为您已经创建了一个人脸库

    典型应用场景:如人脸闸机考勤签到安防监控等。

    说明:人脸识别返回值不直接判断是否是同一人,只返回用户信息及相似度分值。

    提示:进行人脸查找相关操作前,建议先阅读 人脸库管理 相关内容。

    请求说明

    注意事项

    • 请求体格式化:Content-Type为application/x-www-form-urlencoded,通过urlencode格式化请求体。
    • Base64编码:请求的图片需经过Base64编码,图片的base64编码指将图片数据编码成一串字符串,使用该字符串代替图像地址。您可以首先得到图片的二进制,然后用Base64格式编码即可。需要注意的是,图片的base64编码是不包含图片头的,如data:image/jpg;base64,
    • 图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片
    • 人脸识别接口分为V2和V3两个版本,本文档为V2版本接口的说明文档,请确认您在百度云后台获得的是V2版本接口权限,再来阅读本文档。

    辨别接口版本的方法是:在百度云后台进入【应用列表】,点击【应用名称】,在【API列表】中可以看到【请求地址】,若请求地址中带有【v2】标识,则您具有的是v2权限,可以阅读本文档;若请求地址中带有【v3】标识,则您具有的是v3权限,应该去阅读v3文档。

    请求示例

    HTTP方法:POST

    请求URL: https://aip.baidubce.com/rest/2.0/face/v2/identify

    URL参数:

    参数
    access_token 通过API Key和Secret Key获取的access_token,参考“Access Token获取

    Header:

    参数
    Content-Type application/x-www-form-urlencoded

    Body中放置请求参数,参数详情如下:

    请求参数

    参数 必选 类型 说明
    image string base64编码后的图片数据,需urlencode,每次只支持单张图片,编码后的图片大小不超过10M
    group_id string 用户组id(由数字、字母、下划线组成),长度限制128B,如果需要查询多个用户组id,用逗号分隔
    ext_fields string 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3
    user_top_num uint32 识别后返回的用户top数,默认为1,最多返回5个

    请求代码示例

    提示一:使用示例代码前,请记得替换其中的示例Token、图片地址或Base64信息。

    提示二:部分语言依赖的类或库,请在代码注释中查看下载地址。

    {% Face-API-Identify %}

    返回说明

    返回参数

    字段 必选 类型 说明
    log_id uint64 请求唯一标识码,随机数
    result_num uint32 返回结果数目,即:result数组中元素个数
    ext_info array 对应参数中的ext_fields
    +faceliveness string 活体检测分数,单帧活体检测参考阈值0.393241,超过此分值以上则可认为是活体。注意:活体检测接口主要用于判断是否为二次翻拍,需要限制用户为当场拍照获取图片;推荐配合客户端SDK有动作校验活体使用
    result array(object) 结果数组
    +group_id string 对应的这个用户的group_id
    +uid string 匹配到的用户id
    +user_info string 注册时的用户信息
    +scores array(double) 结果数组,数组元素为匹配得分,top n。得分[0,100.0]。推荐80分作为阈值,80分以上可以判断为同一人,此分值对应万分之一误识率。

    返回示例

    {
        "log_id": 73473737,
        "result_num":1,
        "result": [
            {
                "group_id" : "test1",
                "uid": "u333333",
                "user_info": "Test User",
                "scores": [
                        99.3,
                        83.4
                ]
            }
        ]
    }

    关于活体检测faceliveness的判断阈值选择,可参考以下数值信息

    拒绝率(TRR) 误拒率(FRR) 通过率(TAR) 阈值(Threshold)
    0.90325733 0.1% 99.9% 0.022403
    0.96254072 0.5% 99.5% 0.393241(推荐
    0.97557003 1% 99% 0.649192
    0.98990228 2% 98% 0.933801
    0.99446254 3% 97% 0.973637
    0.99641694 4% 96% 0.988479
    0.99739414 5% 95% 0.994058

    关于以上数值的概念介绍

    • 拒绝率(TRR):如99%,代表100次作弊假体攻击,会有99次被拒绝。
    • 误拒率(FRR):如0.5%,指1000次真人请求,会有5次因为活体分数低于阈值被错误拒绝。
    • 通过率(TAR):如99%,指100次真人请求,会有99次因为活体分数高于阈值而通过。
    • 阈值(Threshold):高于此数值,则可判断为活体。

    人脸认证

    接口描述

    用于识别上传的图片是否为指定用户,即查找前需要先确定要查找的用户在人脸库中的id。

    典型应用场景:如人脸登录人脸签到

    提示:进行人脸查找相关操作前,建议先阅读 人脸库管理 相关内容。

    请求说明

    注意事项

    • 请求体格式化:Content-Type为application/x-www-form-urlencoded,通过urlencode格式化请求体。
    • Base64编码:请求的图片需经过Base64编码,图片的base64编码指将图片数据编码成一串字符串,使用该字符串代替图像地址。您可以首先得到图片的二进制,然后用Base64格式编码即可。需要注意的是,图片的base64编码是不包含图片头的,如data:image/jpg;base64,
    • 图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片

    请求示例

    HTTP方法:POST

    请求URL: https://aip.baidubce.com/rest/2.0/face/v2/verify

    URL参数:

    参数
    access_token 通过API Key和Secret Key获取的access_token,参考“Access Token获取

    Header如下:

    参数
    Content-Type application/x-www-form-urlencoded

    Body中放置请求参数,参数详情如下:

    请求参数

    参数 必选 类型 说明
    uid string 用户id(由数字、字母、下划线组成),长度限制128B
    image string base64编码后的图片数据,需urlencode,每次只支持单张图片,编码后的图片大小不超过10M
    group_id string 用逗号分隔,表示从指定的group中查找
    top_num uint32 返回匹配得分top数,默认为1
    ext_fields string 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3

    请求代码示例

    提示一:使用示例代码前,请记得替换其中的示例Token、图片地址或Base64信息。

    提示二:部分语言依赖的类或库,请在代码注释中查看下载地址。

    {% Face-API-Verify %}

    返回说明

    返回参数

    字段 必选 类型 说明
    log_id uint64 请求唯一标识码,随机数
    result_num uint32 返回结果数目,即:result数组中元素个数
    result array(double) 结果数组,数组元素为匹配得分,top n。 得分范围[0,100.0]。超过80分可认为认证成功
    ext_info array 对应参数中的ext_fields
    +faceliveness string 活体检测分数,单帧活体检测参考阈值0.393241,超过此分值以上则可认为是活体。活体检测接口主要用于判断是否为二次翻拍,需要限制用户为当场拍照获取图片;推荐配合客户端SDK有动作校验活体使用

    返回示例

    {
        "log_id": 73473737,
        "result_num":2,
        "result": [
                99.3,
                83.6
        ]
    }

    关于活体检测faceliveness的判断阈值选择,可参考以下数值信息

    拒绝率(TRR) 误拒率(FRR) 通过率(TAR) 阈值(Threshold)
    0.90325733 0.1% 99.9% 0.022403
    0.96254072 0.5% 99.5% 0.393241(推荐
    0.97557003 1% 99% 0.649192
    0.98990228 2% 98% 0.933801
    0.99446254 3% 97% 0.973637
    0.99641694 4% 96% 0.988479
    0.99739414 5% 95% 0.994058

    关于以上数值的概念介绍

    • 拒绝率(TRR):如99%,代表100次作弊假体攻击,会有99次被拒绝。
    • 误拒率(FRR):如0.5%,指1000次真人请求,会有5次因为活体分数低于阈值被错误拒绝。
    • 通过率(TAR):如99%,指100次真人请求,会有99次因为活体分数高于阈值而通过。
    • 阈值(Threshold):高于此数值,则可判断为活体。

    M:N 识别

    待识别的图片中,存在多张人脸的情况下,支持在一个人脸库中,一次请求,同时返回图片中所有人脸的识别结果。

    提示:进行人脸查找相关操作前,建议先阅读 人脸库管理 相关内容。

    请求说明

    注意事项

    • 请求体格式化:Content-Type为application/x-www-form-urlencoded,通过urlencode格式化请求体。
    • Base64编码:请求的图片需经过Base64编码,图片的base64编码指将图片数据编码成一串字符串,使用该字符串代替图像地址。您可以首先得到图片的二进制,然后用Base64格式编码即可。需要注意的是,图片的base64编码是不包含图片头的,如data:image/jpg;base64,
    • 图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片

    请求示例

    HTTP方法:POST

    请求URL: https://aip.baidubce.com/rest/2.0/face/v2/multi-identify

    URL参数:

    参数
    access_token 通过API Key和Secret Key获取的access_token,参考“Access Token获取

    Header如下:

    参数
    Content-Type application/x-www-form-urlencoded

    Body中放置请求参数,参数详情如下:

    请求参数

    参数 必选 类型 说明
    image string base64编码后的图片数据,需urlencode,每次只支持单张图片,编码后的图片大小不超过10M
    group_id string 用户组id(由数字、字母、下划线组成),长度限制128B,用户组id,如果有多个,用逗号分隔,最多支持10个,不允许出现空ID重复ID
    ext_fields string 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3
    detect_top_num uint32 检测多少个人脸进行比对,默认值1(最对返回10个)
    user_top_num uint32 返回识别结果top数,当同一个人有多张图片时,只返回比对最高的1个分数(即,scores参数只有一个值),默认为1(最多返回20个)

    返回说明

    返回参数

    参数 字段 必选 类型 说明
    log_id - uint32 请求标识码,随机数,唯一
    result_num - float 返回结果数目,即:result数组中元素个数(PS:最终返回的个数是小于等于 “实际检测到的人脸数” * “每个人脸匹配的top人数”)
    ext_info - array 对应参数中的ext_fields
    - faceliveness string 活体检测分数,单帧活体检测参考阈值0.393241,超过此分值以上则可认为是活体。注意:活体检测接口主要用于判断是否为二次翻拍,需要限制用户为当场拍照获取图片;推荐配合客户端SDK有动作校验活体使用
    result - array(object) -
    - group_id string 对应的这个用户的group_id
    - uid string 匹配到的用户id
    - user_info string 注册时的用户信息
    - scores array(double) 结果数组,数组元素为匹配得分,得分[0,100.0];个数取决于user_top_num的设定。推荐80分以上即可判断为同一人
    - position object 人脸位置,如{top:111,left:222,width:333,height:444,degree:20}

    返回示例

    {
        "log_id": 73473737,
        "result_num":1,
        "result": [
            {
                "group_id" : "test1",
                "uid": "u333333",
                "user_info": "Test User",
                "position":{"left":726.99188232422,"top":288.37701416016,"width":44,"height":42,"degree":-4,"prob":0.91117089986801},
                "scores": [
                        99.3
                ]
            },
            {
                "group_id" : "test1",
                "uid": "u2222222",
                "user_info": "Test User",
                "position":{"left":726.99188232422,"top":288.37701416016,"width":44,"height":42,"degree":-4,"prob":0.91117089986801},
                "scores": [
                        82.3
                ]
            }
        ]
    }

    关于活体检测faceliveness的判断阈值选择,可参考以下数值信息

    拒绝率(TRR) 误拒率(FRR) 通过率(TAR) 阈值(Threshold)
    0.90325733 0.1% 99.9% 0.022403
    0.96254072 0.5% 99.5% 0.393241(推荐
    0.97557003 1% 99% 0.649192
    0.98990228 2% 98% 0.933801
    0.99446254 3% 97% 0.973637
    0.99641694 4% 96% 0.988479
    0.99739414 5% 95% 0.994058

    关于以上数值的概念介绍

    • 拒绝率(TRR):如99%,代表100次作弊假体攻击,会有99次被拒绝。
    • 误拒率(FRR):如0.5%,指1000次真人请求,会有5次因为活体分数低于阈值被错误拒绝。
    • 通过率(TAR):如99%,指100次真人请求,会有99次因为活体分数高于阈值而通过。
    • 阈值(Threshold):高于此数值,则可判断为活体。

    错误码

    请参考人脸识别错误码

    上一篇
    人脸对比
    下一篇
    人脸库管理