人脸识别

    Face-Cpp-SDK-V2

    简介

    Hi,您好,欢迎使用百度人脸识别服务。

    本文档主要针对C++开发者,描述百度人脸识别接口服务的相关技术内容。如果您对文档内容有任何疑问,可以通过以下几种方式联系我们:

    接口能力

    接口名称 接口能力简要描述
    人脸检测 检测人脸并定位,返回五官关键点,及人脸各属性值
    人脸比对 返回两两比对的人脸相似值
    人脸查找 在一个人脸集合中找到找到相似的人脸,由一系列接口组成,包括人脸识别、人脸认证、人脸库管理相关接口(人脸注册、人脸更新、人脸删除、用户信息查询、组列表查询、组内用户列表查询、组间复制用户、组内删除用户)

    版本更新记录

    上线日期 版本号 更新内容
    2018.4.9 0.6.0 新增身份验证,在线活体检测接口
    2018.1.12 0.5.0 新增M:N多人脸识别接口
    2017.12.21 0.4.0 更改了人脸认证,更新用户,人脸更新,组件复制用户的接口参数
    2017.11.14 0.3.1 人脸检测接口升级到v2
    2017.11.9 0.3.0 初始化参数修改
    2017.10.31 0.1.0 人脸识别第一版

    快速入门

    安装人脸识别 C++ SDK

    人脸识别 C++ SDK目录结构

    ├── base
    │  ├── base.h                                // 请求客户端基类
    │  ├── base64.h                              // base64加密相关类
    │  ├── http.h                                // http请求封装类
    │  └── utils.h                               // 工具类
    └── face.h                             // 人脸识别 交互类

    最低支持 C++ 11+

    直接使用开发包步骤如下

    1.在官方网站下载C++ SDK压缩包。

    2.将下载的aip-cpp-sdk-version.zip解压, 其中文件为包含实现代码的头文件。

    3.安装依赖库libcurl(需要支持https) openssl jsoncpp(>1.6.2版本,0.x版本将不被支持)。

    4.编译工程时添加 C++11 支持 (gcc/clang 添加编译参数 -std=c++11), 添加第三方库链接参数 lcurl, lcrypto, ljsoncpp。

    5.在源码中include face.h ,引入压缩包中的头文件以使用aip命名空间下的类和方法。

    新建client

    client是人脸识别的C++客户端,为使用人脸识别的开发人员提供了一系列的交互方法。当您引入了相应头文件后就可以新建一个client对象

    用户可以参考如下代码新建一个client:

        #include "face.h"
    
        // 设置APPID/AK/SK
        std::string app_id = "你的 App ID";
        std::string api_key = "你的 Api key";
        std::string secret_key = "你的 Secret Key";
    
        aip::Face client(app_id, api_key, secret_key);

    在上面代码中,常量APP_ID在百度云控制台中创建,常量API_KEYSECRET_KEY是在创建完毕应用后,系统分配给用户的,均为字符串,用于标识用户,为访问做签名验证,可在AI服务控制台中的应用列表中查看。

    注意:如您以前是百度云的老用户,其中API_KEY对应百度云的“Access Key ID”,SECRET_KEY对应百度云的“Access Key Secret”。

    接口说明

    人脸检测

    检测请求图片中的人脸,返回人脸位置、72个关键点坐标、及人脸相关属性信息。

    检测响应速度,与图片中人脸数量相关,人脸数量较多时响应时间会有些许延长。

    典型应用场景:如人脸属性分析基于人脸关键点的加工分析人脸营销活动等。

    五官位置会标记具体坐标;72个关键点坐标也包含具体坐标,但不包含对应位置的详细位置描述。

    Json::Value result;
    
    std::string image;
    aip::get_file_content("/assets/sample.jpg", &image);
    
    // 调用人脸检测
    result = client.detect(image, aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["max_face_num"] = "2";
    options["face_fields"] = "age";
    
    // 带参数调用人脸检测
    result = client.detect(image, options);

    人脸检测 请求参数详情

    参数名称 是否必选 类型 默认值 说明
    image std::string 图片数据的二进制字符串,可以使用aip::get_file_content函数获取
    max_face_num std::string 1 最多处理人脸数目,默认值1
    face_fields std::string 包括age,beauty,expression,faceshape,gender,glasses,landmark,race,qualities信息,逗号分隔,默认只返回人脸框、概率和旋转角度

    人脸检测 返回数据参数详情

    参数 类型 必选 说明
    log_id uint64 日志id
    result_num uint32 人脸数目
    result object[] 人脸属性对象的集合
    +age double 年龄。face_fields包含age时返回
    +beauty double 美丑打分,范围0-100,越大表示越美。face_fields包含beauty时返回
    +location object 人脸在图片中的位置
    ++left uint32 人脸区域离左边界的距离
    ++top uint32 人脸区域离上边界的距离
    ++width uint32 人脸区域的宽度
    ++height uint32 人脸区域的高度
    +face_probability double 人脸置信度,范围0-1
    +rotation_angle int32 人脸框相对于竖直方向的顺时针旋转角,[-180,180]
    +yaw double 三维旋转之左右旋转角[-90(左), 90(右)]
    +pitch double 三维旋转之俯仰角度[-90(上), 90(下)]
    +roll double 平面内旋转角[-180(逆时针), 180(顺时针)]
    +expression uint32 表情,0,不笑;1,微笑;2,大笑。face_fields包含expression时返回
    +expression_probability double 表情置信度,范围0~1。face_fields包含expression时返回
    +faceshape object[] 脸型置信度。face_fields包含faceshape时返回
    ++type string 脸型:square/triangle/oval/heart/round
    ++probability double 置信度:0~1
    +gender string male、female。face_fields包含gender时返回
    +gender_probability double 性别置信度,范围0~1。face_fields包含gender时返回
    +glasses uint32 是否带眼镜,0-无眼镜,1-普通眼镜,2-墨镜。face_fields包含glasses时返回
    +glasses_probability double 眼镜置信度,范围0~1。face_fields包含glasses时返回
    +landmark object[] 4个关键点位置,左眼中心、右眼中心、鼻尖、嘴中心。face_fields包含landmark时返回
    ++x uint32 x坐标
    ++y uint32 y坐标
    +landmark72 object[] 72个特征点位置,示例图 。face_fields包含landmark时返回
    ++x uint32 x坐标
    ++y uint32 y坐标
    +race string yellow、white、black、arabs。face_fields包含race时返回
    +race_probability double 人种置信度,范围0~1。face_fields包含race时返回
    +qualities object 人脸质量信息。face_fields包含qualities时返回
    ++occlusion object 人脸各部分遮挡的概率,[0, 1],0表示完整,1表示不完整
    +++left_eye double 左眼
    +++right_eye double 右眼
    +++nose double 鼻子
    +++mouth double
    +++left_cheek double 左脸颊
    +++right_cheek double 右脸颊
    +++chin double 下巴
    ++blur double 人脸模糊程度,[0, 1]。0表示清晰,1表示模糊
    ++illumination - 取值范围在[0,255],表示脸部区域的光照程度
    ++completeness - 人脸完整度,[0, 1]。0表示完整,1表示不完整
    ++type object 真实人脸/卡通人脸置信度
    +++human - 真实人脸置信度,[0, 1]
    +++cartoon - 卡通人脸置信度,[0, 1]

    人脸检测 返回示例

    {
        "result_num": 1,
        "result": [
            {
                "location": {
                    "left": 117,
                    "top": 131,
                    "width": 172,
                    "height": 170
                },
                "face_probability": 1,
                "rotation_angle": 2,
                "yaw": -0.34859421849251,
                "pitch": 2.3033397197723,
                "roll": 1.9135693311691,
                "landmark": [
                    {
                        "x": 161.74819946289,
                        "y": 163.30244445801
                    },
                    ...
                ],
                "landmark72": [
                    {
                        "x": 115.86531066895,
                        "y": 170.0546875
                    },
                    ...
                ],
                "age": 29.298097610474,
                "beauty": 55.128883361816,
                "expression": 1,
                "expression_probablity": 0.5543018579483,
                "gender": "male",
                "gender_probability": 0.99979132413864,
                "glasses": 0,
                "glasses_probability": 0.99999964237213,
                "race": "yellow",
                "race_probability": 0.99999976158142,
                "qualities": {
                    "occlusion": {
                        "left_eye": 0,
                        "right_eye": 0,
                        "nose": 0,
                        "mouth": 0,
                        "left_cheek": 0.0064102564938366,
                        "right_cheek": 0.0057411273010075,
                        "chin": 0
                    },
                    "blur": 1.1886881756684e-10,
                    "illumination": 141,
                    "completeness": 1,
                    "type": {
                        "human": 0.99935841560364,
                        "cartoon": 0.00064159056637436
                    }
                }
            }
        ],
        "log_id": 2493878179101621
    }

    质量判断

    可通过人脸检测接口,基于以下字段和对应阈值,进行质量检测的判断,以保证人脸质量符合后续业务操作要求。

    指标 字段与解释 推荐数值界限
    遮挡范围 occlusion(0~1),0为无遮挡,1是完全遮挡
    含有多个具体子字段,表示脸部多个部位
    通常用作判断头发、墨镜、口罩等遮挡
    left_eye : 0.6, #左眼被遮挡的阈值
    right_eye : 0.6, #右眼被遮挡的阈值
    nose : 0.7, #鼻子被遮挡的阈值
    mouth : 0.7, #嘴巴被遮挡的阈值
    left_check : 0.8, #左脸颊被遮挡的阈值
    right_check : 0.8, #右脸颊被遮挡的阈值
    chin_contour : 0.6, #下巴被遮挡阈值
    模糊度范围 Blur(0~1),0是最清晰,1是最模糊 小于0.7
    光照范围 illumination(0~255)
    脸部光照的灰度值,0表示光照不好
    以及对应客户端SDK中,YUV的Y分量
    大于40
    姿态角度 Pitch:三维旋转之俯仰角度[-90(上), 90(下)]
    Roll:平面内旋转角[-180(逆时针), 180(顺时针)]
    Yaw:三维旋转之左右旋转角[-90(左), 90(右)]
    分别小于20度
    人脸完整度 completeness(0或1),0代表完整,1代表不完整 小于0.4
    人脸大小 人脸部分的大小
    建议长宽像素值范围:80*80~200*200
    人脸部分不小于100*100像素

    人脸比对

    该请求用于比对多张图片中的人脸相似度并返回两两比对的得分,可用于判断两张脸是否是同一人的可能性大小。

    典型应用场景:如人证合一验证用户认证等,可与您现有的人脸库进行比对验证。

    说明:支持对比对的两张图片做在线活体检测

    Json::Value result;
    
    std::vector<std::string> images;
    std::string temp_file_str;
    aip::get_file_content("/assets/sample1.jpg", &temp_file_str);
    images.emplace_back(std::move(temp_file_str));
    aip::get_file_content("/assets/sample2.jpg", &temp_file_str);
    images.emplace_back(std::move(temp_file_str));
    
    // 调用人脸比对
    result = client.match(images, aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["ext_fields"] = "qualities";
    options["image_liveness"] = ",faceliveness";
    options["types"] = "7,13";
    
    // 带参数调用人脸比对
    result = client.match(images, options);

    人脸比对 请求参数详情

    参数名称 是否必选 类型 可选值范围 说明
    images std::vector<std::string> 图片数据的二进制字符串组成的vector,
    可以使用aip::get_file_content函数获取单个图片信息,然后加入vector容器
    ext_fields std::string 返回质量信息,取值固定:目前支持qualities(质量检测)。(对所有图片都会做改处理)
    image_liveness std::string faceliveness,faceliveness - 对比对的两张图片都做活体检测
    ,faceliveness - 对第一张图片不做活体检测、第二张图做活体检测faceliveness, - 对第一张图片做活体检测、第二张图不做活体检测
    返回的活体信息,“faceliveness,faceliveness” 表示对比对的两张图片都做活体检测;“,faceliveness” 表示对第一张图片不做活体检测、第二张图做活体检测;“faceliveness,” 表示对第一张图片做活体检测、第二张图不做活体检测;
    注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3
    types std::string 请求对比的两张图片的类型,示例:“7,13”
    12表示带水印证件照:一般为带水印的小图,如公安网小图
    7表示生活照:通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等
    13表示证件照片:如拍摄的身份证、工卡、护照、学生证等证件图片,:需要确保人脸部分不可太小,通常为100px*100px

    人脸比对 返回数据参数详情

    字段 必选 类型 说明
    log_id uint64 请求唯一标识码,随机数
    result_num uint32 返回结果数目,即:result数组中元素个数
    result array(object) 结果数据,index和请求图片index对应。数组元素为每张图片的匹配得分数组,top n。 得分[0,100.0]
    +index_i uint32 比对图片1的index
    +index_j uint32 比对图片2的index
    +score double 比对得分
    ext_info array(dict) 对应参数中的ext_fields
    +qualities string 质量相关的信息,无特殊需求可以不使用
    +faceliveness string 活体分数,如0.49999。单帧活体检测参考阈值0.393241,超过此分值以上则可认为是活体。注意:活体检测接口主要用于判断是否为二次翻拍,需要限制用户为当场拍照获取图片;推荐配合客户端SDK有动作校验活体使用

    人脸比对 返回示例

    //请求两张图片
    {
        "log_id": 73473737,
        "result_num":1,
        "result": [
            {
                "index_i": 0,
                "index_j": 1,
                "score": 44.3
            }
        ]
    }

    人脸识别

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

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

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

    说明:推荐可判断为同一人的相似度分值为80,您也可以根据业务需求选择更合适的阈值。

    Json::Value result;
    
    std::string group_id = "group1,group2";
    
    std::string image;
    aip::get_file_content("/assets/sample.jpg", &image);
    
    // 调用人脸识别
    result = client.identify(group_id, image, aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["ext_fields"] = "faceliveness";
    options["user_top_num"] = "3";
    
    // 带参数调用人脸识别
    result = client.identify(group_id, image, options);

    人脸识别 请求参数详情

    参数名称 是否必选 类型 默认值 说明
    group_id std::string 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。
    产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率
    image std::string 图片数据的二进制字符串,可以使用aip::get_file_content函数获取
    ext_fields std::string 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3
    user_top_num std::string 1 返回用户top数,默认为1,最多返回5个

    人脸识别 返回数据参数详情

    字段 必选 类型 说明
    log_id uint64 请求唯一标识码,随机数
    result_num uint32 返回结果数目,即:result数组中元素个数
    ext_info array 对应参数中的ext_fields
    +faceliveness string 活体分数,如0.49999。单帧活体检测参考阈值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]

    人脸识别 返回示例

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

    人脸认证

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

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

    说明:人脸认证与人脸识别的差别在于:人脸识别需要指定一个待查找的人脸库中的组;而人脸认证需要指定具体的用户id即可,不需要指定具体的人脸库中的组;实际应用中,人脸认证需要用户或系统先输入id,这增加了验证安全度,但也增加了复杂度,具体使用哪个接口需要视您的业务场景判断。

    说明:请求参数中,新增在线活体检测

    Json::Value result;
    
    std::string uid = "user1";
    
    std::string group_id = "group1,group2";
    
    std::string image;
    aip::get_file_content("/assets/sample.jpg", &image);
    
    // 调用人脸认证
    result = client.verify(uid, group_id, image, aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["top_num"] = "3";
    options["ext_fields"] = "faceliveness";
    
    // 带参数调用人脸认证
    result = client.verify(uid, group_id, image, options);

    人脸认证 请求参数详情

    参数名称 是否必选 类型 默认值 说明
    uid std::string 用户id(由数字、字母、下划线组成),长度限制128B
    group_id std::string 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。
    产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率
    image std::string 图片数据的二进制字符串,可以使用aip::get_file_content函数获取
    top_num std::string 1 返回用户top数,默认为1
    ext_fields std::string 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3

    人脸认证 返回数据参数详情

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

    人脸认证 返回示例

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

    M:N 识别

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

    Json::Value result;
    
    std::string group_id = "group1,group2";
    
    std::string image;
    aip::get_file_content("/assets/sample.jpg", &image);
    
    // 调用M:N 识别
    result = client.multi_identify(group_id, image, aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["ext_fields"] = "faceliveness";
    options["detect_top_num"] = "3";
    options["user_top_num"] = "2";
    
    // 带参数调用M:N 识别
    result = client.multi_identify(group_id, image, options);

    M:N 识别 请求参数详情

    参数名称 是否必选 类型 默认值 说明
    group_id std::string 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。
    产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率
    image std::string 图片数据的二进制字符串,可以使用aip::get_file_content函数获取
    ext_fields std::string 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3
    detect_top_num std::string 1 检测多少个人脸进行比对,默认值1(最对返回10个)
    user_top_num std::string 1 返回识别结果top人数”,当同一个人有多张图片时,只返回比对最高的1个分数(即,scores参数只有一个值),默认为1(最多返回20个)

    M:N 识别 返回数据参数详情

    参数 字段 必选 类型 说明
    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}

    M:N 识别 返回示例

    {
        "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
                ]
            }
        ]
    }

    人脸注册

    用于从人脸库中新增用户,可以设定多个用户所在组,及组内用户的人脸图片,

    典型应用场景:构建您的人脸库,如会员人脸注册已有用户补全人脸信息等。

    人脸库、用户组、用户、用户下的人脸层级关系如下所示:

    |- 人脸库
       |- 用户组一
          |- 用户01
             |- 人脸
          |- 用户02
             |- 人脸
             |- 人脸
             ....
           ....
       |- 用户组二
       |- 用户组三
       |- 用户组四
       ....

    关于人脸库的设置限制

    • 每个开发者账号可以创建100个appid;
    • 每个appid对应一个人脸库,且不同appid之间,人脸库互不相通
    • 每个人脸库下,可以创建多个用户组,用户组(group)数量没有限制
    • 每个用户组(group)下,可添加最多无限张人脸,无限个uid;
    • 每个用户(uid)所能注册的最大人脸数量没有限制

    为了保证识别效果,请控制注册人脸的质量(通过/detect人脸检测接口判断),具体参数可详见下表所示:

    质量判断

    可通过人脸检测接口,基于以下字段和对应阈值,进行质量检测的判断,以保证人脸质量符合后续业务操作要求。

    指标 字段与解释 推荐数值界限
    遮挡范围 occlusion(0~1),0为无遮挡,1是完全遮挡
    含有多个具体子字段,表示脸部多个部位
    通常用作判断头发、墨镜、口罩等遮挡
    left_eye : 0.6, #左眼被遮挡的阈值
    right_eye : 0.6, #右眼被遮挡的阈值
    nose : 0.7, #鼻子被遮挡的阈值
    mouth : 0.7, #嘴巴被遮挡的阈值
    left_check : 0.8, #左脸颊被遮挡的阈值
    right_check : 0.8, #右脸颊被遮挡的阈值
    chin_contour : 0.6, #下巴被遮挡阈值
    模糊度范围 Blur(0~1),0是最清晰,1是最模糊 小于0.7
    光照范围 illumination(0~255)
    脸部光照的灰度值,0表示光照不好
    以及对应客户端SDK中,YUV的Y分量
    大于40
    姿态角度 Pitch:三维旋转之俯仰角度[-90(上), 90(下)]
    Roll:平面内旋转角[-180(逆时针), 180(顺时针)]
    Yaw:三维旋转之左右旋转角[-90(左), 90(右)]
    分别小于20度
    人脸完整度 completeness(0或1),0为人脸溢出图像边界,1为人脸都在图像边界内 视业务逻辑判断
    人脸大小 人脸部分的大小
    建议长宽像素值范围:80*80~200*200
    人脸部分不小于100*100像素
    Json::Value result;
    
    std::string uid = "user1";
    
    std::string user_info = "user's info";
    
    std::string group_id = "group1,group2";
    
    std::string image;
    aip::get_file_content("/assets/sample.jpg", &image);
    
    // 调用人脸注册
    result = client.user_add(uid, user_info, group_id, image, aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["action_type"] = "replace";
    
    // 带参数调用人脸注册
    result = client.user_add(uid, user_info, group_id, image, options);

    人脸注册 请求参数详情

    参数名称 是否必选 类型 默认值 说明
    uid std::string 用户id(由数字、字母、下划线组成),长度限制128B
    user_info std::string 用户资料,长度限制256B
    group_id std::string 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。
    产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率
    image std::string 图片数据的二进制字符串,可以使用aip::get_file_content函数获取
    action_type std::string append 参数包含append、replace。如果为“replace”,则每次注册时进行替换replace(新增或更新)操作,默认为append操作。例如:uid在库中已经存在时,对此uid重复注册时,新注册的图片默认会追加到该uid下,如果手动选择action_type:replace,则会用新图替换库中该uid下所有图片。

    人脸注册 返回数据参数详情

    字段 是否必选 类型 说明
    log_id uint64 请求唯一标识码,随机数

    人脸注册 返回示例

    // 注册成功
    {
        "log_id": 73473737,
    }
    // 注册发生错误
    {
      "error_code": 216616,
      "log_id": 674786177,
      "error_msg": "image exist"
    }

    人脸更新

    用于对人脸库中指定用户,更新其下的人脸图像。

    说明:针对一个uid执行更新操作,新上传的人脸图像将覆盖此uid原有所有图像。

    说明:执行更新操作,如果该uid不存在时,会返回错误。如果添加了action_type:replace,则不会报错,并自动注册该uid,操作结果等同注册新用户。

    Json::Value result;
    
    std::string uid = "user1";
    
    std::string user_info = "user's info";
    
    std::string group_id = "group1";
    
    std::string image;
    aip::get_file_content("/assets/sample.jpg", &image);
    
    // 调用人脸更新
    result = client.user_update(uid, user_info, group_id, image, aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["action_type"] = "replace";
    
    // 带参数调用人脸更新
    result = client.user_update(uid, user_info, group_id, image, options);

    人脸更新 请求参数详情

    参数名称 是否必选 类型 默认值 说明
    uid std::string 用户id(由数字、字母、下划线组成),长度限制128B
    user_info std::string 用户资料,长度限制256B
    group_id std::string 更新指定groupid下uid对应的信息
    image std::string 图片数据的二进制字符串,可以使用aip::get_file_content函数获取
    action_type std::string append 目前仅支持replace,uid不存在时,不报错,会自动变为注册操作;未选择该参数时,如果uid不存在会提示错误

    人脸更新 返回数据参数详情

    字段 是否必选 类型 说明
    log_id uint64 请求唯一标识码,随机数

    人脸更新 返回示例

    // 更新成功
    {
        "log_id": 73473737,
    }
    // 更新发生错误
    {
      "error_code": 216612,
      "log_id": 1137508902,
      "error_msg": "user not exist"
    }

    人脸删除

    用于从人脸库中删除一个用户。

    人脸删除注意事项:

    • 删除的内容,包括用户所有图像和身份信息;
    • 如果一个uid存在于多个用户组内,将会同时将从各个组中把用户删除
    • 如果指定了group_id,则只删除此group下的uid相关信息
    Json::Value result;
    
    std::string uid = "user1";
    
    // 调用人脸删除
    result = client.user_delete(uid, aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["group_id"] = "group1";
    
    // 带参数调用人脸删除
    result = client.user_delete(uid, options);

    人脸删除 请求参数详情

    参数名称 是否必选 类型 说明
    uid std::string 用户id(由数字、字母、下划线组成),长度限制128B
    group_id std::string 删除指定groupid下uid对应的信息

    人脸删除 返回数据参数详情

    字段 是否必选 类型 说明
    log_id uint64 请求唯一标识码,随机数

    人脸删除 返回示例

    // 删除成功
    {
        "log_id": 73473737,
    }
    // 删除发生错误
    {
      "error_code": 216612,
      "log_id": 1137508902,
      "error_msg": "user not exist"
    }

    用户信息查询

    用于查询人脸库中某用户的详细信息。

    Json::Value result;
    
    std::string uid = "user1";
    
    // 调用用户信息查询
    result = client.user_get(uid, aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["group_id"] = "group1";
    
    // 带参数调用用户信息查询
    result = client.user_get(uid, options);

    用户信息查询 请求参数详情

    参数名称 是否必选 类型 说明
    uid std::string 用户id(由数字、字母、下划线组成),长度限制128B
    group_id std::string 选择指定group_id则只查找group列表下的uid内容,如果不指定则查找所有group下对应uid的信息

    用户信息查询 返回数据参数详情

    字段 是否必选 类型 说明
    log_id uint64 请求标识码,随机数,唯一
    result array(double) 结果数组
    +uid string 匹配到的用户id
    +user_info string 注册时的用户信息
    +groups array(string) 用户所属组列表

    用户信息查询 返回示例

    {
    “result_num” : 2
        "result": {
            [
                "uid": "testuser2",
                "user_info": "registed user info ...",
                "group_id": "grep1",
            ],
            [
                "uid": "testuser2",
                "user_info": "registed user info2 ...",
                "group_id": "grep2",
            ],
        },
        "log_id": 2979357502
    }

    组列表查询

    用于查询用户组的列表。

    Json::Value result;
    
    // 调用组列表查询
    result = client.group_getlist(aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["start"] = "0";
    options["num"] = "50";
    
    // 带参数调用组列表查询
    result = client.group_getlist(options);

    组列表查询 请求参数详情

    参数名称 是否必选 类型 默认值 说明
    start std::string 0 默认值0,起始序号
    num std::string 100 返回数量,默认值100,最大值1000

    组列表查询 返回数据参数详情

    字段 是否必选 类型 说明
    result_num number 返回个数
    result array(string) group_id列表

    组列表查询 返回示例

    {
        "result_num": 2,
        "result": [
            "grp1",
            "grp2"
        ],
        "log_id": 3314921889
    }

    组内用户列表查询

    用于查询指定用户组中的用户列表。

    Json::Value result;
    
    std::string group_id = "group1";
    
    // 调用组内用户列表查询
    result = client.group_getusers(group_id, aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["start"] = "0";
    options["num"] = "50";
    
    // 带参数调用组内用户列表查询
    result = client.group_getusers(group_id, options);

    组内用户列表查询 请求参数详情

    参数名称 是否必选 类型 默认值 说明
    group_id std::string 用户组id(由数字、字母、下划线组成),长度限制128B
    start std::string 0 默认值0,起始序号
    num std::string 100 返回数量,默认值100,最大值1000

    组内用户列表查询 返回数据参数详情

    字段 是否必选 类型 说明
    log_id uint64 请求标识码,随机数,唯一
    result_num uint32 返回个数
    result array(object) user列表
    +uid string 用户id
    +user_info string 用户信息

    组内用户列表查询 返回示例

    {
        "log_id": 3314921889,
        "result_num": 2,
        "result": [
            {
                "uid": "uid1",
                "user_info": "user info 1"
            },
            {
                "uid": "uid2",
                "user_info": "user info 2"
            }
        ]
    }

    组间复制用户

    用于将已经存在于人脸库中的用户复制到一个新的组。

    说明:并不是向一个指定组内添加用户,而是直接从其它组复制用户信息 如果需要注册用户,请直接使用人脸注册接口

    Json::Value result;
    
    std::string src_group_id = "group1";
    
    std::string group_id = "group1,group2";
    
    std::string uid = "user1";
    
    // 调用组间复制用户
    result = client.group_adduser(src_group_id, group_id, uid, aip::null);

    组间复制用户 请求参数详情

    参数名称 是否必选 类型 说明
    src_group_id std::string 从指定group里复制信息
    group_id std::string 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。
    产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率
    uid std::string 用户id(由数字、字母、下划线组成),长度限制128B

    组间复制用户 返回数据参数详情

    字段 是否必选 类型 说明
    log_id uint64 请求标识码,随机数,唯一

    组间复制用户 返回示例

    // 正确返回值
    {
        "log_id": 3314921889,
    }
    // 发生错误时返回值
    {
      "error_code": 216100,
      "log_id": 3111284097,
      "error_msg": "already add"
    }

    组内删除用户

    用于将用户从某个组中删除,但不会删除用户在其它组的信息。

    说明:当用户仅属于单个分组时,本接口将返回错误,请使用人脸删除接口

    Json::Value result;
    
    std::string group_id = "group1,group2";
    
    std::string uid = "user1";
    
    // 调用组内删除用户
    result = client.group_deleteuser(group_id, uid, aip::null);

    组内删除用户 请求参数详情

    参数名称 是否必选 类型 说明
    group_id std::string 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。
    产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率
    uid std::string 用户id(由数字、字母、下划线组成),长度限制128B

    组内删除用户 返回数据参数详情

    字段 是否必选 类型 说明
    log_id uint64 请求标识码,随机数,唯一

    组内删除用户 返回示例

    // 正确返回值
    {
        "log_id": 3314921889,
    }
    // 发生错误时返回值
    {
      "error_code": 216619,
      "log_id": 815967402,
      "error_msg": "user must be in one group at least"
    }

    身份验证

    质量检测(可选)活体检测(可选)公安验证(必选)

    Json::Value result;
    
    std::string image;
    aip::get_file_content("/assets/sample.jpg", &image);
    
    std::string id_card_number = "110233112299822211";
    
    std::string name = "张三";
    
    // 调用身份验证
    result = client.person_verify(image, id_card_number, name, aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["quality"] = "use";
    options["quality_conf"] = "{\"left_eye\": 0.6, \"right_eye\": 0.6}";
    options["faceliveness"] = "use";
    options["faceliveness_conf"] = "{\"faceliveness\": 0.834963}";
    options["ext_fields"] = "qualities";
    
    // 带参数调用身份验证
    result = client.person_verify(image, id_card_number, name, options);

    身份验证 请求参数详情

    参数名称 是否必选 类型 说明
    image std::string 图片数据的二进制字符串,可以使用aip::get_file_content函数获取
    id_card_number std::string 身份证号(真实身份证号号码)。我们的服务端会做格式校验,并通过错误码返回,但是为了您的产品反馈体验更及时,建议在产品前端做一下号码格式校验与反馈
    name std::string utf8,姓名(真实姓名,和身份证号匹配)
    quality std::string 判断图片中的人脸质量是否符合条件。use表示需要做质量控制,质量不符合条件的照片会被直接拒绝
    quality_conf std::string 人脸质量检测中每一项指标的具体阈值设定,json串形式,当指定quality:use时生效
    faceliveness std::string 判断活体值是否达标。use表示需要做活体检测,低于活体阈值的照片会直接拒绝
    faceliveness_conf std::string 人脸活体检测的阈值设定,json串形式,当指定faceliveness:use时生效。默认使用的阈值如下:{faceliveness:0.834963}
    ext_fields std::string 可选项为faceliveness,qualities。选择具体的项,则返回参数中将会显示相应的扩展字段。如faceliveness表示返回结果中包含活体相关内容,qualities表示返回结果中包含质量检测相关内容

    身份验证 返回数据参数详情

    参数 必须 类型 说明
    log_id uint64 日志id
    result float 与公安小图相似度可能性,用于验证生活照与公安小图是否为同一人,有正常分数时为[0~1],推荐阈值0.8,超过即判断为同一人
    ext_info string 拓展信息json串,只有选择了ext_fields时才会返回具体信息。选择faceliveness返回具体活体分值信息,选择qualities返回人脸质量检测信息。两者可以同时选择,半角逗号分割。
    +faceliveness string 活体检测值,单帧图片建议阈值,小于此值则认为不是活体,超过则判断为活体
    +qualities string 质量检测结果
    ++occlusion string 人脸遮挡情况
    +++left_eye string 左眼被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.6
    +++right_eye string 右眼被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.6
    +++nose string 鼻子被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.7
    +++mouth string 嘴巴被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.7
    +++left_cheek string 左脸颊被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.8
    +++right_cheek string 右脸颊被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.8
    +++chin string 下巴被遮挡的比例,取值范围[0~1],数值越大遮挡越多;小于阈值时有返回,默认阈值0.8
    ++blur string 人脸模糊度阈值,取值范围[0~1],数值越大越模糊;小于阈值时有返回,默认阈值0.7
    ++illumination string 脸部光照的灰度值阈值,取值范围[0~255],数值越大光照越强;大于阈值时有返回,默认阈值30
    ++completeness string 人脸完整度,0或1, 0为人脸溢出图像边界,1为人脸都在图像边界内

    身份验证 返回示例

    {
      "result":0.03419,
      "ext_info":{
        "faceliveness":0.834963
      },
      "log_id":772889134072410
    }

    在线活体检测

    人脸基础信息,人脸质量检测,基于图片的活体检测

    Json::Value result;
    
    std::string image;
    aip::get_file_content("/assets/sample.jpg", &image);
    
    // 调用在线活体检测
    result = client.faceverify(image, aip::null);
    
    // 如果有可选参数
    std::map<std::string, std::string> options;
    options["max_face_num"] = "2";
    options["face_fields"] = "qualities";
    
    // 带参数调用在线活体检测
    result = client.faceverify(image, options);

    在线活体检测 请求参数详情

    参数名称 是否必选 类型 默认值 说明
    image std::string 图片数据的二进制字符串,可以使用aip::get_file_content函数获取
    max_face_num std::string 1 最多处理人脸数目,默认值1
    face_fields std::string 如不选择此项,返回结果默认只有人脸框、概率和旋转角度。可选参数为qualities、faceliveness。qualities:图片质量相关判断;faceliveness:活体判断。如果两个参数都需要选择,请使用半角逗号分隔。

    在线活体检测 返回数据参数详情

    参数 类型 是否必须 说明
    log_id uint64 日志id
    result_num uint32 人脸数目
    result object[] 人脸属性对象的集合
    +faceliveness float 活体分数,face_fields包括qualities时返回
    +location bject 人脸在图片中的位置
    ++left uint32 人脸区域离左边界的距离
    ++top uint32 人脸区域离上边界的距离
    ++width uint32 人脸区域的宽度
    ++height uint32 人脸区域的高度
    +face_probability double 人脸置信度,范围0-1
    +rotation_angle int32 人脸框相对于竖直方向的顺时针旋转角,[-180,180]
    +yaw double 三维旋转之左右旋转角[-90(左), 90(右)]
    +pitch double 三维旋转之俯仰角度[-90(上), 90(下)]
    +roll double 平面内旋转角[-180(逆时针), 180(顺时针)]
    +qualities object 人脸质量信息。face_fields包含qualities时返回
    ++occlusion object 人脸各部分遮挡的概率,区间[0, 1]
    +++left_eye double 左眼
    +++right_eye double 右眼
    +++nose double 鼻子
    +++mouth double
    +++left_cheek double 左脸颊
    +++right_cheek double 右脸颊
    +++chin double 下巴
    ++blur double 人脸模糊程度,[0, 1]。0表示清晰,1表示模糊
    ++illumination double 取值范围在[0,255],表示脸部区域的光照程度
    ++completeness double 人脸完整度,[0, 1]。0表示完整,1表示不完整
    ++type object 真实人脸/卡通人脸置信度
    +++human double 真实人脸置信度,[0, 1]
    +++cartoon double 卡通人脸置信度,[0, 1]

    在线活体检测 返回示例

    {
        log_id: 1900901488032821,
        result_num: 1,
        result: [
            {
                rotation_angle: 10,
                yaw: 11.357421875,
                faceliveness: 8.1253347161692e-05,
                location: {
                    width: 96,
                    top: 73,
                    height: 96,
                    left: 283
                },
                qualities: {
                    illumination: 211,
                    occlusion: {
                        right_eye: 0,
                        left_eye: 0.039751552045345,
                        left_cheek: 0.12623985111713,
                        mouth: 0,
                        nose: 0,
                        chin: 0.037661049515009,
                        right_cheek: 0.024720622226596
                    },
                    completeness: 1,
                    type: {
                        cartoon: 0,
                        human: 0
                    },
                    blur: 2.5251445032182e-11
                },
                pitch: 1.0063140392303,
                roll: 12.760620117188,
                face_probability: 1
            }
        ]
    }

    错误信息

    错误返回格式

    若请求错误,服务器将返回的JSON文本包含以下参数:

    • error_code:错误码。
    • error_msg:错误描述信息,帮助理解和解决发生的错误。

    错误码

    错误码 错误信息 描述
    4 Open api request limit reached 集群超限额
    14 IAM Certification failed IAM鉴权失败,建议用户参照文档自查生成sign的方式是否正确,或换用控制台中ak sk的方式调用
    17 Open api daily request limit reached 每天流量超限额
    18 Open api qps request limit reached QPS超限额
    19 Open api total request limit reached 请求总量超限额
    100 Invalid parameter 无效参数
    110 Access token invalid or no longer valid Access Token失效
    111 Access token expired Access token过期
    216015 module closed 模块关闭
    216100 invalid param 参数异常
    216101 not enough param 缺少必须的参数
    216102 service not support 请求了不支持的服务,请检查调用的url
    216103 param too long 请求超长,一般为一次传入图片个数超过系统限制
    216110 appid not exist appid不存在,请重新检查后台应用列表中的应用信息
    216111 invalid userid userid信息非法,请检查对应的参数
    216200 empty image 图片为空或者base64解码错误
    216201 image format error 图片格式错误
    216202 image size error 图片大小错误
    216300 db error 数据库异常,少量发生时重试即可
    216400 backend error 后端识别服务异常,可以根据具体msg查看错误原因
    216401 internal error 内部错误
    216402 face not found 未找到人脸,请检查图片是否含有人脸
    216500 unknown error 未知错误
    216611 user not exist 用户不存在,请确认该用户是否注册或注册已经生效(需要已经注册超过5s
    216613 fail to delete user record 删除用户图片记录失败,重试即可
    216614 not enough images 两两比对中图片数少于2张,无法比较
    216615 fail to process images 服务处理该图片失败,发生后重试即可
    216616 image existed 图片已存在
    216617 fail to add user 新增用户图片失败
    216618 no user in group 组内用户为空,确认该group是否存在或已经生效(需要已经注册超过5s)
    216631 request add user overlimit 本次请求添加的用户数量超限
    上一篇
    C#语言
    下一篇
    Nodejs语言