Face-Python-SDK-V2

更新时间：2021-01-09

简介

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

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

在百度云控制台内提交工单，咨询问题类型请选择人工智能服务；
如有疑问，进入AI社区交流：http://ai.baidu.com/forum/topic/list/165

接口能力

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

版本更新记录

上线日期	版本号	更新内容
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_KEY与SECRET_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
人脸大小	人脸部分的大小建议长宽像素值范围：8080~200200	人脸部分不小于*100100**像素

人脸比对

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

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

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

""" 读取图片 """
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,” 表示对第一张图片做活体检测、第二张图不做活体检测； *注：需要用于判断活体的图片，图片中的人脸像素面积需要不小于100px100px，人脸长宽与图片长宽比例，不小于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(活体检测)。*注：需要用于判断活体的图片，图片中的人脸像素面积需要不小于100px100px，人脸长宽与图片长宽比例，不小于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(活体检测)。*注：需要用于判断活体的图片，图片中的人脸像素面积需要不小于100px100px，人脸长宽与图片长宽比例，不小于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(活体检测)。*注：需要用于判断活体的图片，图片中的人脸像素面积需要不小于100px100px，人脸长宽与图片长宽比例，不小于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为人脸都在图像边界内	视业务逻辑判断
人脸大小	人脸部分的大小建议长宽像素值范围：8080~200200	人脸部分不小于*100100**像素

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#语言