资讯 社区 文档
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术

Face-Python-SDK-V2

简介

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

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

接口能力

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

版本更新记录

上线日期 版本号 更新内容
2018.4.9 2.2.2 新增身份验证,在线活体检测接口
2018.01.12 2.1.0 新增M:N多人脸识别
2017.12.22 2.0.0 SDK代码重构
2017.5.11 1.0.0 人脸识别服务上线

快速入门

安装人脸识别 Python SDK

人脸识别 Python SDK目录结构

├── README.md
├── aip                   //SDK目录
│   ├── __init__.py       //导出类
│   ├── base.py           //aip基类
│   ├── http.py           //http请求
│   └── face.py //人脸识别
└── setup.py              //setuptools安装

支持Python版本:2.7.+ ,3.+

安装使用Python SDK有如下方式

  • 如果已安装pip,执行pip install baidu-aip即可。
  • 如果已安装setuptools,执行python setup.py install即可。

新建AipFace

AipFace是人脸识别的Python SDK客户端,为使用人脸识别的开发人员提供了一系列的交互方法。

参考如下代码新建一个AipFace:

from aip import AipFace

""" 你的 APPID AK SK """
APP_ID = '你的 App ID'
API_KEY = '你的 Api Key'
SECRET_KEY = '你的 Secret Key'

client = AipFace(APP_ID, API_KEY, SECRET_KEY)

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

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

配置AipFace

如果用户需要配置AipFace的网络请求参数(一般不需要配置),可以在构造AipFace之后调用接口设置参数,目前只支持以下参数:

接口 说明
setConnectionTimeoutInMillis 建立连接的超时时间(单位:毫秒
setSocketTimeoutInMillis 通过打开的连接传输数据的超时时间(单位:毫秒)

接口说明

人脸检测

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

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

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

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

""" 读取图片 """
def get_file_content(filePath):
    with open(filePath, 'rb') as fp:
        return fp.read()

image = get_file_content('example.jpg')

""" 调用人脸检测 """
client.detect(image);

""" 如果有可选参数 """
options = {}
options["max_face_num"] = 2
options["face_fields"] = "age"

""" 带参数调用人脸检测 """
client.detect(image, options)

人脸检测 请求参数详情

参数名称 是否必选 类型 默认值 说明
image string 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式
max_face_num string 1 最多处理人脸数目,默认值1
face_fields string 包括age,beauty,expression,faceshape,gender,glasses,landmark,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坐标
+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,
            "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像素

人脸比对

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

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

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

""" 读取图片 """
def get_file_content(filePath):
    with open(filePath, 'rb') as fp:
        return fp.read()

images = [
    get_file_content('example0.jpg'),
    get_file_content('example1.jpg'),
]

""" 调用人脸比对 """
client.match(images);

""" 如果有可选参数 """
options = {}
options["ext_fields"] = "qualities"
options["image_liveness"] = ",faceliveness"
options["types"] = "7,13"

""" 带参数调用人脸比对 """
client.match(images, options)

人脸比对 请求参数详情

参数名称 是否必选 类型 可选值范围 说明
images string base64编码后的多张图片数据,半角逗号分隔,单次请求总共最大20M
ext_fields string 返回质量信息,取值固定:目前支持qualities(质量检测)。(对所有图片都会做改处理)
image_liveness string faceliveness,faceliveness - 对比对的两张图片都做活体检测
,faceliveness - 对第一张图片不做活体检测、第二张图做活体检测faceliveness, - 对第一张图片做活体检测、第二张图不做活体检测
返回的活体信息,“faceliveness,faceliveness” 表示对比对的两张图片都做活体检测;“,faceliveness” 表示对第一张图片不做活体检测、第二张图做活体检测;“faceliveness,” 表示对第一张图片做活体检测、第二张图不做活体检测;
注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3
types 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,您也可以根据业务需求选择更合适的阈值。

groupId = "group1,group2"

""" 读取图片 """
def get_file_content(filePath):
    with open(filePath, 'rb') as fp:
        return fp.read()

image = get_file_content('example.jpg')

""" 调用人脸识别 """
client.identifyUser(groupId, image);

""" 如果有可选参数 """
options = {}
options["ext_fields"] = "faceliveness"
options["user_top_num"] = 3

""" 带参数调用人脸识别 """
client.identifyUser(groupId, image, options)

人脸识别 请求参数详情

参数名称 是否必选 类型 默认值 说明
group_id string 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。
产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率
image string 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式
ext_fields string 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3
user_top_num 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,这增加了验证安全度,但也增加了复杂度,具体使用哪个接口需要视您的业务场景判断。

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

uid = "user1"

groupId = "group1,group2"

""" 读取图片 """
def get_file_content(filePath):
    with open(filePath, 'rb') as fp:
        return fp.read()

image = get_file_content('example.jpg')

""" 调用人脸认证 """
client.verifyUser(uid, groupId, image);

""" 如果有可选参数 """
options = {}
options["top_num"] = 3
options["ext_fields"] = "faceliveness"

""" 带参数调用人脸认证 """
client.verifyUser(uid, groupId, image, options)

人脸认证 请求参数详情

参数名称 是否必选 类型 默认值 说明
uid string 用户id(由数字、字母、下划线组成),长度限制128B
group_id string 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。
产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率
image string 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式
top_num string 1 返回用户top数,默认为1
ext_fields 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 识别

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

groupId = "group1,group2"

""" 读取图片 """
def get_file_content(filePath):
    with open(filePath, 'rb') as fp:
        return fp.read()

image = get_file_content('example.jpg')

""" 调用M:N 识别 """
client.multiIdentify(groupId, image);

""" 如果有可选参数 """
options = {}
options["ext_fields"] = "faceliveness"
options["detect_top_num"] = 3
options["user_top_num"] = 2

""" 带参数调用M:N 识别 """
client.multiIdentify(groupId, image, options)

M:N 识别 请求参数详情

参数名称 是否必选 类型 默认值 说明
group_id string 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。
产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率
image string 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式
ext_fields string 特殊返回信息,多个用逗号分隔,取值固定: 目前支持faceliveness(活体检测)。注:需要用于判断活体的图片,图片中的人脸像素面积需要不小于100px*100px,人脸长宽与图片长宽比例,不小于1/3
detect_top_num string 1 检测多少个人脸进行比对,默认值1(最对返回10个)
user_top_num 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像素
uid = "user1"

userInfo = "user's info"

groupId = "group1,group2"

""" 读取图片 """
def get_file_content(filePath):
    with open(filePath, 'rb') as fp:
        return fp.read()

image = get_file_content('example.jpg')

""" 调用人脸注册 """
client.addUser(uid, userInfo, groupId, image);

""" 如果有可选参数 """
options = {}
options["action_type"] = "replace"

""" 带参数调用人脸注册 """
client.addUser(uid, userInfo, groupId, image, options)

人脸注册 请求参数详情

参数名称 是否必选 类型 默认值 说明
uid string 用户id(由数字、字母、下划线组成),长度限制128B
user_info string 用户资料,长度限制256B
group_id string 用户组id,标识一组用户(由数字、字母、下划线组成),长度限制128B。如果需要将一个uid注册到多个group下,group_id需要用多个逗号分隔,每个group_id长度限制为48个英文字符。注:group无需单独创建,注册用户时则会自动创建group。
产品建议:根据您的业务需求,可以将需要注册的用户,按照业务划分,分配到不同的group下,例如按照会员手机尾号作为groupid,用于刷脸支付、会员计费消费等,这样可以尽可能控制每个group下的用户数与人脸数,提升检索的准确率
image string 图像base64编码,每次仅支持单张图片,图片编码后大小不超过10M。为保证后续识别的效果较佳,建议注册的人脸,为用户正面人脸。
action_type 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,操作结果等同注册新用户。

uid = "user1"

userInfo = "user's info"

groupId = "group1"

""" 读取图片 """
def get_file_content(filePath):
    with open(filePath, 'rb') as fp:
        return fp.read()

image = get_file_content('example.jpg')

""" 调用人脸更新 """
client.updateUser(uid, userInfo, groupId, image);

""" 如果有可选参数 """
options = {}
options["action_type"] = "replace"

""" 带参数调用人脸更新 """
client.updateUser(uid, userInfo, groupId, image, options)

人脸更新 请求参数详情

参数名称 是否必选 类型 默认值 说明
uid string 用户id(由数字、字母、下划线组成),长度限制128B
user_info string 用户资料,长度限制256B
group_id string 更新指定groupid下uid对应的信息
image string 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式
action_type 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相关信息
uid = "user1"

""" 调用人脸删除 """
client.deleteUser(uid);

""" 如果有可选参数 """
options = {}
options["group_id"] = "group1"

""" 带参数调用人脸删除 """
client.deleteUser(uid, options)

人脸删除 请求参数详情

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

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

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

人脸删除 返回示例

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

用户信息查询

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

uid = "user1"

""" 调用用户信息查询 """
client.getUser(uid);

""" 如果有可选参数 """
options = {}
options["group_id"] = "group1"

""" 带参数调用用户信息查询 """
client.getUser(uid, options)

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

参数名称 是否必选 类型 说明
uid string 用户id(由数字、字母、下划线组成),长度限制128B
group_id 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
}

组列表查询

用于查询用户组的列表。

""" 调用组列表查询 """
client.getGroupList();

""" 如果有可选参数 """
options = {}
options["start"] = 0
options["num"] = 50

""" 带参数调用组列表查询 """
client.getGroupList(, options)

组列表查询 请求参数详情

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

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

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

组列表查询 返回示例

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

组内用户列表查询

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

groupId = "group1"

""" 调用组内用户列表查询 """
client.getGroupUsers(groupId);

""" 如果有可选参数 """
options = {}
options["start"] = 0
options["num"] = 50

""" 带参数调用组内用户列表查询 """
client.getGroupUsers(groupId, options)

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

参数名称 是否必选 类型 默认值 说明
group_id string 用户组id(由数字、字母、下划线组成),长度限制128B
start string 0 默认值0,起始序号
num 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"
        }
    ]
}

组间复制用户

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

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

srcGroupId = "group1"

groupId = "group1,group2"

uid = "user1"

""" 调用组间复制用户 """
client.addGroupUser(srcGroupId, groupId, uid);

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

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

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

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

组间复制用户 返回示例

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

组内删除用户

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

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

groupId = "group1,group2"

uid = "user1"

""" 调用组内删除用户 """
client.deleteGroupUser(groupId, uid);

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

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

身份验证

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

""" 读取图片 """
def get_file_content(filePath):
    with open(filePath, 'rb') as fp:
        return fp.read()

image = get_file_content('example.jpg')
idCardNumber = "110233112299822211"

name = "张三"

""" 调用身份验证 """
client.personVerify(image, idCardNumber, name);

""" 如果有可选参数 """
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"

""" 带参数调用身份验证 """
client.personVerify(image, idCardNumber, name, options)

身份验证 请求参数详情

参数名称 是否必选 类型 说明
image string 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式
id_card_number string 身份证号(真实身份证号号码)。我们的服务端会做格式校验,并通过错误码返回,但是为了您的产品反馈体验更及时,建议在产品前端做一下号码格式校验与反馈
name string utf8,姓名(真实姓名,和身份证号匹配)
quality string 判断图片中的人脸质量是否符合条件。use表示需要做质量控制,质量不符合条件的照片会被直接拒绝
quality_conf string 人脸质量检测中每一项指标的具体阈值设定,json串形式,当指定quality:use时生效
faceliveness string 判断活体值是否达标。use表示需要做活体检测,低于活体阈值的照片会直接拒绝
faceliveness_conf string 人脸活体检测的阈值设定,json串形式,当指定faceliveness:use时生效。默认使用的阈值如下:{faceliveness:0.834963}
ext_fields 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
}

在线活体检测

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

""" 读取图片 """
def get_file_content(filePath):
    with open(filePath, 'rb') as fp:
        return fp.read()

image = get_file_content('example.jpg')

""" 调用在线活体检测 """
client.faceverify(image);

""" 如果有可选参数 """
options = {}
options["max_face_num"] = 2
options["face_fields"] = "qualities"

""" 带参数调用在线活体检测 """
client.faceverify(image, options)

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

参数名称 是否必选 类型 默认值 说明
image string 图像数据,base64编码,要求base64编码后大小不超过4M,最短边至少15px,最长边最大4096px,支持jpg/png/bmp格式
max_face_num string 1 最多处理人脸数目,默认值1
face_fields 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 本次请求添加的用户数量超限
上一篇
PHP语言
下一篇
C#语言