接口文档

更新时间：2026-02-05

1.总体说明

私有化部署包部署成功后，即可获得与公有云基本完全相同的接口，人脸识别的相关接口将会启动，即可开始调用。

1.1 接口能力

在私有化部署包中会提供如下5类接口：

Appid管理

业务能力

创建Appid：用于创建一个Appid

查询Appid：用于查询此业务中已经创建哪个Appid

注：创建方式为：通过调用“创建用户组”接口来创建appid，即：在“创建用户组”接口中可以自定义一个Appid，当组创建成功后，此Appid即可生效。

人脸检测与属性分析

接口能力

① 人脸检测：检测图片中的人脸并标记出位置信息;
② 人脸关键点：展示人脸的核心关键点信息，及72个关键点信息;
③ 人脸属性值：展示人脸属性信息，如年龄、性别等;
④ 人脸质量信息：返回人脸各部分的遮挡、光照、模糊、完整度、置信度等信息。

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

人脸比对

接口能力

① 两张人脸图片相似度对比：比对两张图片中人脸的相似度，并返回相似度分值；
② 多种图片类型：支持生活照、证件照、身份证芯片照、带网纹照四种类型的人脸对比；
③ 活体检测控制：基于图片中的破绽分析，判断其中的人脸是否为二次翻拍；（举例：如用户A用手机拍摄了一张包含人脸的图片一，用户B翻拍了图片一得到了图片二，并用图片二伪造成用户A去进行识别操作，这种情况普遍发生在金融开户、实名认证等环节。）
④ 质量检测控制：分析图片的中人脸的模糊度、角度、光照强度等特征，判断图片质量。

业务应用

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

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

人脸搜索

业务能力

① 1：N人脸搜索：也称为1：N识别，在指定人脸集合中，找到最相似的人脸；
② 1：N人脸认证：基于uid维度的1：N识别，由于uid已经锁定固定数量的人脸，所以检索范围更聚焦。

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

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

人脸库管理

业务能力

要完成1：N或者M：N识别，首先需要构建一个人脸库，用于存放所有人脸特征，相关接口如下：

人脸注册：向人脸库中添加人脸
① 人脸更新：更新人脸库中指定用户下的人脸信息
② 人脸删除：删除指定用户的某张人脸
③ 用户信息查询：查询人脸库中某个用户的详细信息
④ 获取用户人脸列表：获取某个用户组中的全部人脸列表
⑤ 获取用户列表：查询指定用户组中的用户列表
⑥ 复制用户：将指定用户复制到另外的人脸组
⑦ 创建用户组：创建一个新的用户组
⑧ 删除用户组：删除指定用户组
⑨ 组列表查询：查询人脸库中用户组的列表

人脸库结构

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

|- 人脸库(appid)
   |- 用户组一（group_id）
      |- 用户01（uid）
         |- 人脸（faceid）
      |- 用户02（uid）
         |- 人脸（faceid）
         |- 人脸（faceid）
         ....
       ....
   |- 用户组二（group_id）
   |- 用户组三（group_id）
   ....

关于人脸库的设置限制

① 每个私有化部署包建议对应1个appid，每个appid对应一个人脸库；
② 每个人脸库下，可以创建多个用户组，用户组（group）数量没有限制；
③ 每个用户组（group）下，可添加无限个user_id，无限张人脸（注：为了保证查询速度，单个group中的人脸容量上限建议为80万）；
④ 每个用户（user_id）所能注册的最大人脸数量没有限制。

提醒：每个人脸库对应一个appid，一定不要轻易删除appid，删除后则此人脸库将失效，无法进行查找！

1.2 接口格式说明

变量类型定义

类型	定义
string	普通的字符串，可能会有长度要求，具体参见接口说明中的备注。
uint32	整形数字，最大取值为4字节int，自然数。
int64	整形数字，最大取值为8字节int，允许负数。
json	无论是request还是response中某个字段定义为json，那么它其实是一个json格式的字符串，需要二次解析。
array	request的query中表示array请使用key[] 。response的json中的array即为jsonArray。
double	双精度，小数点后最大8位四舍五入。
encryption	加密格式，一般用于人脸服务各模块间交互数据使用。

注意事项

① 所有ID定义必须为小于等于32字节的数字字母组合，尽量使用无意义的组合，并且不可以使用系统保留关键字：all、self、me、this、next。
② 所有接口POSTDATA 应当小于等于8M。
③ 单个group中的图片容量上限建议为80万。
④ 人脸图片需要人脸像素在100x100以上，否则可能检测不出来人脸。

请求方式

请求方式统一使用application/json请求 直接请求
直接请求时需要将appid参数拼接在请求url中，不要放在json body中注意：如果是直接对线上单台机器发起请求，需要在接口路径前加上/api的前缀。

返回格式
① error_code、error_msg即错误码和错误描述，详细含义请参考错误码表, error_code为0代表请求成功；
② result是接口返回的详细信息, 格式为数组;
③ log_id是请求的日志id, 13位长(bigint), 用于定位请求。

{
    "error_code" : 0,  //错误码 0代表成功
    "error_msg"  : "SUCCESS", //错误信息
    "result" : {...} //返回结果 具体内容详见相关接口
    "log_id" : 3535325235 //请求的日志id
    "timestamp" : 1512391548 //请求到达的时间戳 精确到秒级
    "cached" : 0 //未启用 无需处理
}

阈值说明

识别得分阈值

说明：识别得分即match比对，identify、midentfiy检索接口返回的得分。

阈值	误识率
60	1%
70	0.1%
80（推荐）	0.01%
90	0.001%
95	0.0001%

质量控制阈值

说明：不同的控制度下所对应的质量控制阈值如果检测出来的质量信息某一项不符合控制阈值的要求，则会返回错误。

控制度	left_eye	right_eye	nose	mouth	left_cheek	right_cheek	chin_contour	illumination	blurdegree	completeness
LOW	0.8	0.8	0.8	0.8	0.8	0.8	0.8	20	0.8	0
NORMAL	0.6	0.6	0.6	0.6	0.6	0.6	0.6	40	0.6	0
HIGH	0.2	0.2	0.2	0.2	0.2	0.2	0.2	100	0.2	1

参数说明

参数	说明
left_eye	左眼被遮挡的比例。取值范围[0-1] ，1表示完全遮挡。
right_eye	右眼被遮挡的比例。取值范围[0-1]，1表示完全遮挡。
nose	鼻子被遮挡的比例。取值范围[0-1]，1表示完全遮挡。
mouth	嘴巴被遮挡的比例。取值范围[0-1]，1表示完全遮挡。
left_cheek	左脸颊被遮挡比例。取值范围[0-1]， 1表示完全遮挡。
right_cheek	右脸颊被遮挡比例。取值范围[0-1] ，1表示完全遮挡。
chin_contour	下巴被遮挡的比例。取值范围[0-1]，1表示完全遮挡。
illumination	光照度数值。取值范围 [0-255] ，0表示光照不好。
blurdegree	图片模糊度。取值范围 [0-1] ，1表示完全模糊。
completeness	人脸完整度。取值范围[0 或 1] 。0为人脸溢出图像边界，1为人脸都在图像边界内。

活体控制阈值

不同的控制度下所对应的活体控制阈值如果检测出来的活体分数小于控制阈值，则会返回错误。

控制度	阈值	说明
LOW	0.05	0.01%活体误拒率，对应的通过率为99.99%，攻击拒绝率为82.27%。
NORMAL	0.3	0.1%活体误拒率，对应的通过率为99.9%，攻击拒绝率为89.70%。
HIGH	0.9	1%活体误拒率，对应的通过率为99%，攻击拒绝率为98.18%。

误拒率（FRR）：如0.5%，指1000次真人请求，会有5次因为活体分数低于阈值被错误拒绝。

通过率（TAR）：如99%，指100次真人请求，会有99次因为活体分数高于阈值而通过。

攻击拒绝率（TRR）：如99%，代表100次作弊假体攻击，会有99次被拒绝。

误拒率越高，其对攻击的防范能力也会越高。

合成图控制阈值

说明：不同的控制档位下所对应的合成图检测（PS、人脸融合等）阈值有所不同。如果检测出来的合成图分数大于合成图控制档位阈值分数，则会返回错误信息。

备注：合成图控制档位越高，表明图片要求的合成图分数越低，图片真实性越高。

控制档位	合成图阈值	误拒率	通过率	攻击拒绝率
HIGH	0.00023	1.6%	98.4%	95.48%
NORMAL（推荐）	0.00048(推荐)	0.7%	99.3%	93.14%
LOW	0.00109	0.5%	99.5%	86.27%

误拒率：把正常图片识别为合成图片的概率。阈值越低，安全性越高，要求也就越高，对应的误识率就越高。

通过率 = 1 - 误拒率

阈值（Threshold）：高于此数值，则可判断为是合成图攻击。

1.3 调用准备

1、调用接口的地址示例：[192.168.0.1]:8300/face-api/v3/face/detect，其中ip需要替换为用户自己服务器的ip，端口固定为：8300，接口地址需要替换为下述接口的地址。

2、调用接口时需要指定appid，此appid为用户自定的id，目前可以通过调用“创建用户组”接口来创建appid。

2. 接口详情

2.1 基础能力接口

2.1.1 人脸检测

检测图片中的人脸并获得位置信息, 属性信息, 质量信息等。

请求路径

/api/face-api/v3/face/detect

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
image	是	string	图片信息(*总数据大小应小于10M，分辨率应小于19201080**)
image_type	是	string	图片类型 BASE64：图片的base64值
face_field	否	string	包括age、beauty、expression、face_shape、gender、glasses、landmark、landmark150、race、quality、face_type、eye_status、mask、emotion、feature、spoofing信息使用，逗号分隔。默认只返回face_token、人脸框、概率和旋转角度。
get_feature	否	string	是否保存特征值 YES 保存特征值 NO 不保存特征值（默认） 2019.12.12以后部署的模型提供此接口请求参数，之前部署的模型若需要保存特征值，请在face_field字段中添加feature字段或者更新模型，更新方式请参考这里。
max_face_num	否	uint32	最多处理人脸的数目默认值为1，仅检测图片中面积最大的那个人脸；最大值10，检测图片中面积最大的几张人脸。若您想修改最大人脸检测数量数值，请参考接口调用问题文档。
face_type	否	string	人脸的类型 LIVE表示生活照：通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等（默认） CERT表示证件照片：如拍摄的身份证、工卡、护照、学生证等证件图片
liveness_control	否	string	活体控制：检测结果中不符合要求的人脸会被过滤 NONE：不进行控制（默认） LOW：较低的活体要求(高通过率，低攻击拒绝率) NORMAL：一般的活体要求(平衡的攻击拒绝率与通过率) HIGH：较高的活体要求(高攻击拒绝率，低通过率)
face_sort_type	否	int	人脸检测排序类型 0：代表按人脸框面积排序（默认） 1：代表使用近图像中心点策略

请求示例

{
    "image": "/9j/4AAQ...",
    "image_type": "BASE64",
    "face_field": "age,face_shape"
}

返回结果

字段	必选	类型	说明
face_num	是	int	检测到的图片中的人脸数量
face_list	是	array	人脸信息列表，具体包含的参数参考下面的列表。
face_token	是	string	人脸图片的唯一标识
location	是	array	人脸在图片中的位置
+left	是	double	人脸区域离左边界的距离
+top	是	double	人脸区域离上边界的距离
+width	是	double	人脸区域的宽度
+height	是	double	人脸区域的高度
+rotation	是	int64	人脸框相对于竖直方向的顺时针旋转角，[-180,180]。
face_probability	是	double	人脸置信度，范围【0~1】，代表这是一张人脸的概率，0最小、1最大。
angel	是	array	人脸旋转角度参数
+yaw	是	double	三维旋转之左右旋转角，[-90(左), 90(右)]。
+pitch	是	double	三维旋转之俯仰角度，[-90(上), 90(下)]。
+roll	是	double	平面内旋转角，[-180(逆时针), 180(顺时针)]。
age	否	double	年龄，当face_field包含age时返回。
beauty	否	int64	美丑打分，范围0-100，越大表示越美。face_field包含beauty时返回。
expression	否	array	表情，当 face_field包含expression时返回。
+type	否	string	none:不笑；smile:微笑；laugh:大笑
+probability	否	double	表情置信度，范围【0~1】，0最小、1最大。
face_shape	否	array	脸型，当face_field包含face_shape时返回。
+type	否	double	square: 正方形 triangle:三角形 oval: 椭圆 heart: 心形 round: 圆形
+probability	否	double	置信度，范围【0~1】，代表这是人脸形状判断正确的概率，0最小、1最大。
gender	否	array	性别，face_field包含gender时返回。
+type	否	string	male:男性 female:女性
+probability	否	double	性别置信度，范围【0~1】，0代表概率最小、1代表最大。
glasses	否	array	是否带眼镜，face_field包含glasses时返回。
+type	否	string	none:无眼镜，common:普通眼镜，sun:墨镜
+probability	否	double	眼镜置信度，范围【0~1】，0代表概率最小、1代表最大。
eye_status	否	array	双眼状态（睁开/闭合）， face_field包含eye_status时返回。
+left_eye	否	double	左眼状态 [0,1]取值，越接近0闭合的可能性越大。
+right_eye	否	double	右眼状态 [0,1]取值，越接近0闭合的可能性越大。
emotion	否	array	情绪，face_field包含emotion时返回。
+type	否	string	angry:愤怒 disgust:厌恶 fear:恐惧 happy:高兴 sad:伤心 surprise:惊讶 neutral:无情绪 pouty: 撅嘴 grimace:鬼脸
+probability	否	double	情绪置信度，范围0~1。
race	否	array	人种face_field包含race时返回。
+type	否	string	yellow: 黄种人 white: 白种人 black:黑种人 arabs: 阿拉伯人
+probability	否	double	人种置信度，范围0~1。
face_type	否	array	真实人脸/卡通人脸，face_field包含face_type时返回。
+type	否	string	human: 真实人脸 cartoon: 卡通人脸
+probability	否	double	人脸类型判断正确的置信度，范围【0~1】，0代表概率最小、1代表最大。
mask	否	array	口罩识别，face_field包含mask时返回。
+type	否	int	0：代表没戴口罩 1：代表戴口罩
+probability	否	double	置信度，范围0~1。
landmark	否	array	4个关键点位置，左眼中心、右眼中心、鼻尖、嘴中心。face_field包含landmark时返回。
landmark72	否	array	72个特征点位置，face_field包含landmark72时返回。
landmark150	否	array	150个特征点位置，face_field包含landmark150时返回。
quality	否	array	人脸质量信息，face_field包含quality时返回。
+occlusion	否	array	人脸各部分遮挡的概率，范围[0~1]，0表示完整，1表示不完整。
++left_eye	否	double	左眼遮挡比例，[0-1]，1表示完全遮挡。
++right_eye	否	double	右眼遮挡比例，[0-1]，1表示完全遮挡。
++nose	否	double	鼻子遮挡比例，[0-1]，1表示完全遮挡。
++mouth	否	double	嘴巴遮挡比例，[0-1]，1表示完全遮挡。
++left_cheek	否	double	左脸颊遮挡比例，[0-1]，1表示完全遮挡。
++right_cheek	否	double	右脸颊遮挡比例，[0-1]，1表示完全遮挡。
+++chin_contour	否	double	下巴遮挡比例，[0-1]，1表示完全遮挡。
+blur	否	double	人脸模糊程度，范围[0~1]，0表示清晰，1表示模糊。
+illumination	否	double	取值范围在[0~255], 表示脸部区域的光照程度越大表示光照越好。
+completeness	否	int64	人脸完整度，0或1，0为人脸溢出图像边界，1为人脸都在图像边界内。
spoofing	否	double	判断图片是否合成图功能 face_field包含时返回spoofing。

返回示例

{
   "error_code": 0,
   "error_msg": "SUCCESS",
   "log_id": 1234567890123,
   "timestamp": 1533094400,
   "cached": 0,
   "result": {
       "face_num": 1,
       "face_list": [
           {
               "face_token": "aaaaaaaaa....",
               "location": {
                   "left": 117,
                   "top": 131,
                   "width": 172,
                   "height": 170,
                   "rotation": 4
               },
               "face_probability": 1,
               "angle": {
                   "yaw": -0.34859421849251,
                   "pitch": 1.9135693311691,
                   "roll": 2.3033397197723
               },
               "landmark": [
                 {
                     "x": 61.67,
                     "y": 133.44
                 },
                 {
                     "x": 99.73,
                     "y": 129.72
                 },
                 {
                     "x": 85.88,
                     "y": 155.07
                 },
                 {
                     "x": 85.82,
                     "y": 173.16
                 }
               ],
               "age": 29.298097610474,
               "beauty": 55.128883361816,
               "expression": {
                   "type": "smile",
                   "probability": 0.5543018579483
               },
               "gender": {
                   "type": "male",
                   "probability": 0.99979132413864
               },
               "glasses": {
                   "type": "sun",
                   "probability": 0.99999964237213
               },
               "eye_status": {
                   "left_eye": 0.9999974966,
                   "right_eye": 0.9999724627
               },
               "race": {
                   "type": "yellow",
                   "probability": 0.99999976158142
               },
               "face_shape": {
                   "type": "triangle",
                   "probability": 0.5543018579483
               },
               "quality": {
                   "occlusion": {
                       "left_eye": 0,
                       "right_eye": 0.015625,
                       "nose": 0,
                       "mouth": 0,
                       "left_cheek": 0.03078358248,
                       "right_cheek": 0.03356481344,
                       "chin_contour": 0.006372549105
                   },
                   "blur": 5.188863383e-7,
                   "illumination": 131,
                   "completeness": 1
               },
               "lib_language": {
						"char": "0",
                     "probability": 0.67
               },
               "skin": {
                 "color": 3,
                 "smooth": 4
             }
           }
       ]
   }
}

72个关键点分布图（对应landmark72个点的顺序，序号从0-71）：

150个关键点分布图（对应landmark150个点的顺序，序号从0-150）：

2.1.2 人脸对比

两张人脸图片相似度对比：比对两张图片中人脸的相似度，并返回相似度分值。

请求路径

/api/face-api/v3/face/match

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B

Header

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
image	是	string	图片信息(*数据大小应小于10M 分辨率应小于19201080**)
image_type	是	string	图片类型 BASE64:图片的base64值
face_type	否	string	人脸的类型 LIVE：表示生活照：通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等。（默认） CERT：表示证件照片：如拍摄的身份证、工卡、护照、学生证等证件图片。备注：当上传两张图片face_type参数值均为LIVE（不传或传值为空时为默认LIVE）时，使用生活照模型进行检测、比对；除此之外均使用证件照模型进行检测、比对。
quality_control	否	string	图片质量控制 NONE: 不进行控制（默认） LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求
liveness_control	否	string	活体检测控制 NONE: 不进行活体控制（默认） LOW:较低的活体要求(高通过率+低攻击拒绝率) NORMAL: 一般的活体要求(中通过率+中攻击拒绝率) HIGH: 较高的活体要求(低通过率+高攻击拒绝率)
spoofing_control	否	string	合成图控制 NONE: 不进行合成图控制（默认） LOW:较低的合成图要求(高通过率+低攻击拒绝率) NORMAL: 一般的合成图要求(中通过率+中攻击拒绝率) HIGH: 较高的合成图要求(低通过率+高攻击拒绝率)
face_sort_type	否	int	人脸检测排序类型 0：代表按人脸框面积排序（默认） 1：代表使用近图像中心点策略以第二个请求体face_sort_type为最终检测排序值

注意：请求体要求为json格式，可以参考请求示例。

请求示例

[
    {
        "image": "sfasq35sadvsvqwr5q...",
        "image_type": "BASE64",
        "face_type": "LIVE",
        "quality_control": "LOW",
        "liveness_control": "HIGH"
    },
    {
        "image": "sfasq35sadvsvqwr5q...",
        "image_type": "BASE64",
        "face_type": "IDCARD",
        "quality_control": "LOW",
        "liveness_control": "HIGH"
    }
]

返回结果

参数名	必选	类型	说明
score	是	float	人脸相似度得分分数范围为[0-100]；80分以上可以判断为同一人。此分值对应万分之一误识率。
face_list	是	array	人脸信息列表
+face_token	是	string	人脸的唯一标志

返回示例

{
 "error_code": 0,
 "error_msg": "SUCCESS",
 "log_id": 1234567890123,
 "timestamp": 1533094576,
 "cached": 0,
 "result": {
     "score": 44.3,
     "face_list": [
         {
             "face_token": "fid1"
         },
         {
             "face_token": "fid2"
         }
     ]
 }
}

2.1.3 单人脸搜索

在指定人脸集合中，找到最相似的人脸

请求路径

/api/face-api/v3/face/identify

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
image	是	string	图片信息(*数据大小应小于10M 分辨率应小于1920108**)
image_type	是	string	图片类型 BASE64:图片的base64值
group_id_list	是	string	从指定的group中进行查找用逗号分隔，上限10个。
quality_control	否	string	图片质量控制 NONE: 不进行控制（默认） LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求
liveness_control	否	string	活体检测控制 NONE: 不进行活体控制（默认） LOW:较低的活体要求(高通过率+低攻击拒绝率) NORMAL: 一般的活体要求(中通过率+中攻击拒绝率) HIGH: 较高的活体要求(低通过率+高攻击拒绝率)
user_id	否	string	指定user_id进行匹配（服务会只在该user_id的数据查找匹配的人脸）
match_threshold	否	int	匹配阈值（设置阈值后，score低于此阈值的用户信息将不会返回）最大100 最小0 默认0 此阈值设置得越高，检索速度将会越快，推荐使用80的阈值。
spoofing_control	否	string	合成图控制 NONE: 不进行合成图控制（默认） LOW:较低的合成图要求(高通过率+低攻击拒绝率) NORMAL: 一般的合成图要求(中通过率+中攻击拒绝率) HIGH: 较高的合成图要求(低通过率+高攻击拒绝率)
max_user_num	否	unit32	查找后返回的用户数量。返回相似度最高的几个用户，默认为1，最多返回50个,若您想要修改最大返回人脸数量，请参考4.如何控制1：N返回的最大人脸数问题文档。

请求示例

  {
      "image": "027d8308a2ec665acb1bdf63e513bcb9",
      "image_type": "FACE_TOKEN",
      "group_id_list": "group_repeat,group_233",
      "quality_control": "LOW",
      "liveness_control": "NORMAL"
  }

返回结果

字段	必选	类型	说明
face_token	是	string	人脸标志
user_list	是	array	匹配的用户信息列表
+group_id	是	string	用户所属的group_id
+user_id	是	string	用户的user_id
+user_info	是	string	注册用户时携带的user_info
+score	是	float	用户的匹配得分 80分以上可以判断为同一人，此分值对应万分之一误识率。

{
    "error_code": 0,
    "error_msg": "SUCCESS",
    "log_id": 1234567890123,
    "timestamp": 1533094591,
    "cached": 0,
    "result": {
        "face_token": "fid",
        "user_list": [
            {
                "group_id": "test1",
                "user_id": "u333333",
                "user_info": "Test User",
                "score": 99.3
            }
        ]
    }
}

2.1.4 M:N 多人脸搜索

使用多人脸的图片, 在指定人脸集合中，查找最相似的人脸

请求路径 /api/face-api/v3/face/midentify
URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
image	是	string	图片信息(*数据大小应小于10M 分辨率应小于19201080**)
image_type	是	string	图片类型 BASE64:图片的base64值
group_id_list	是	string	从指定的group中进行查找用逗号分隔，上限10个。
max_face_num	否	int	最多处理人脸的数目默认值为1(仅检测图片中面积最大的那个人脸)，最大值10。
max_user_num	否	unit32	识别返回的最大用户数，默认为1，最大值20。
match_threshold	否	int	匹配阈值（设置阈值后，score低于此阈值的用户信息将不会返回）最大100 最小0 默认80 此阈值设置得越高，检索速度将会越快，推荐使用默认阈值`80`。
quality_control	否	string	图片质量控制 NONE: 不进行控制（默认） LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求质量不符合要求的人脸不会出现在返回结果中
liveness_control	否	string	活体检测控制 NONE: 不进行活体控制（默认） LOW:较低的活体要求(高通过率+低攻击拒绝率) NORMAL: 一般的活体要求(中通过率+中攻击拒绝率) HIGH: 较高的活体要求(低通过率+高攻击拒绝率) 活体分数不符合要求的人脸不会出现在返回结果中
spoofing_control	否	string	合成图控制 NONE: 不进行合成图控制（默认） LOW:较低的合成图要求(高通过率+低攻击拒绝率) NORMAL: 一般的合成图要求(中通过率+中攻击拒绝率) HIGH: 较高的合成图要求(低通过率+高攻击拒绝率) 合成分数不符合要求的人脸不会出现在返回结果中

多人脸的情况下如果设置了质量控制、活体控制参数，不合格的人脸将被过滤，不会出现在结果中。

请求示例

{
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKD...",
"image_type": "BASE64",
"group_id_list": "group1", 
"max_face_num" : 5,
"quality_control": "LOW",
"liveness_control": "NORMAL"
}

返回结果

字段	必选	类型	说明
face_num	是	int	图片中的人脸数量
face_list	是	array	人脸信息列表
+face_token	是	string	人脸标志
+location	是	array	人脸在图片中的位置
++left	是	double	人脸区域离左边界的距离
++top	是	double	人脸区域离上边界的距离
++width	是	double	人脸区域的宽度
++height	是	double	人脸区域的高度
++rotation	是	int64	人脸框相对于竖直方向的顺时针旋转角，[-180,180]。
+user_list	是	array	匹配的用户信息列表
++group_id	是	string	用户所属的group_id
++user_id	是	string	用户的user_id
++user_info	是	string	注册用户时携带的user_info
++score	是	float	用户的匹配得分 80分以上可以判断为同一人，此分值对应万分之一误识率。

返回示例

{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "log_id": 240483475,
  "timestamp": 1535533440,
  "cached": 0,
  "result": {
      "face_num": 2,
      "face_list": [
          {
              "face_token": "6fe19a6ee0c4233db9b5bba4dc2b9233",
              "location": {
                  "left": 31.95568085,
                  "top": 120.3764267,
                  "width": 87,
                  "height": 85,
                  "rotation": -5
              },
              "user_list": [
                  {
                      "group_id": "group1",
                      "user_id": "5abd24fd062e49bfa906b257ec40d284",
                      "user_info": "userinfo1",
                      "score": 69.85684967041
                  },
                  {
                      "group_id": "group1",
                      "user_id": "2abf89cffb31473a9948268fde9e1c3f",
                      "user_info": "userinfo2",
                      "score": 66.586112976074
                  }
              ]
          },
          {
              "face_token": "fde61e9c074f48cf2bbb319e42634f41",
              "location": {
                  "left": 219.4467773,
                  "top": 104.7486954,
                  "width": 81,
                  "height": 77,
                  "rotation": 3
              },
              "user_list": [
                  {
                      "group_id": "group1",
                      "user_id": "088717532b094c3990755e91250adf7d",
                      "user_info": "userinfo",
                      "score": 65.154159545898
                  }
              ]
          }
      ]
  }
}

2.1.5 图片活体检测

多图活体检测接口，支持送入1/3/8张图片进行活体检测(如果传入一个人的多张图片，活体判断会更准确)

请求路径

/api/face-api/v3/face/liveness

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B

Header：

参数	值
Content-Type	application/json

Body请求参数

参数名	必选	类型	说明
image	是	string	图片信息(总数据大小应小于10M)，图片上传方式根据image_type来判断。可以上传同一个用户的1张、3张或8张图片来进行活体判断，注：后端会选择每组照片中的最高分数作为整体分数。
image_type	是	string	图片类型 BASE64:图片的base64值，base64编码后的图片数据，需urlencode，编码后的图片大小不超过2M。
face_field	否	string	包括age、beauty、expression、face_shape、gender、glasses、landmark、landmark150、race、quality、face_type、eye_status、mask、emotion、feature、spoofing 信息使用，逗号分隔。默认只返回face_token、人脸框、概率和旋转角度。
option	否	string	场景信息，程序会视不同的场景选用相对应的模型。当前支持的场景有COMMON(通用场景)，GATE(闸机场景)，默认使用COMMON。注意：如果请求参数中存在多个option值时，则取第一个option的值。
close_liveness_strategy	否	string	关闭活体检测策略。包含暗光检测 dark、编辑图检测 ps。需要关闭多个策略时两者用逗号分隔。eg：dark,ps 默认为开启暗光、编辑图检测备注：此策略字段值需要赋值到第一个图片项中，然后对所有的图片生效。

注意：请求体要求为json格式，具体请参考请求示例。如果需要送入多张图片，在json中按格式追加数据即可。

请求示例

[
    {
        "image": "sfasq35sadvsvqwr5q...",
        "image_type": "BASE64",
        "face_field": "age",
        "option": "COMMON"
    },
    {
        "image": "http://xxx.baidu.com/image1.png",
        "image_type": "URL",
        "face_field": "age",
        "option": "COMMON"
    },
    {
        "image": "9f30d19f86f89f2f07ce88b69557061a",
        "image_type": "FACE_TOKEN",
        "face_field": "age",
        "option": "COMMON"
    }
]

返回结果

参数	必选	类型	说明
thresholds	是	array	由服务端返回最新的阈值数据（随着模型的优化，阈值可能会变化），将此参数与返回的face_liveness进行比较，可以作为活体判断的依据（当分数>阈值，即可判断为活体）。 frr_1e-4：万分之一误识率的阈值 frr_1e-3：千分之一误识率的阈值 frr_1e-2：百分之一误识率的阈值。误识率越低，准确率越高，相应的拒绝率也越高。
face_liveness	是	float	所有图片的总体活体打分，范围[0~1]。备注：分值为 max(face_list.liveness.livemapscore)
avg_livemapscore	是	float	所有图片的平均活体得分，范围[0~1]。备注：分值为 avg(face_list.liveness.livemapscore)
mid_livemapscore	是	float	所有图片的活体中位数得分，范围[0~1]。备注：分值为 mid(face_list.liveness.livemapscore)
face_list	是	array	每张图片的详细信息描述，如果只上传一张图片，则只返回一个结果。
face_token	是	string	人脸图片的唯一标识
location	是	array	人脸在图片中的位置
+left	是	double	人脸区域离左边界的距离
+top	是	double	人脸区域离上边界的距离
+width	是	double	人脸区域的宽度
+height	是	double	人脸区域的高度
+rotation	是	int64	人脸框相对于竖直方向的顺时针旋转角，[-180,180]。
face_probability	是	double	人脸置信度，范围【0~1】，代表这是一张人脸的概率，0最小、1最大。
angle	是	array	人脸旋转角度参数
+yaw	是	double	三维旋转之左右旋转角[-90(左), 90(右)]。
+pitch	是	double	三维旋转之俯仰角度[-90(上), 90(下)]。
+roll	是	double	平面内旋转角[-180(逆时针), 180(顺时针)]。
age	否	double	年龄，当face_field包含age时返回。
beauty	否	int64	美丑打分，范围0-100，越大表示越美。face_field包含beauty时返回。
expression	否	array	表情，当 face_field包含expression时返回。
+type	否	string	none:不笑；smile:微笑；laugh:大笑
+probability	否	double	表情置信度，范围【0~1】，0最小、1最大。
face_shape	否	array	脸型，当face_field包含face_shape时返回。
+type	否	double	square: 正方形 triangle:三角形 oval: 椭圆 heart: 心形 round: 圆形
+probability	否	double	置信度，范围【0~1】，代表这是人脸形状判断正确的概率，0最小、1最大。
gender	否	array	性别，face_field包含gender时返回。
+type	否	string	male:男性 female:女性
+probability	否	double	性别置信度，范围【0~1】，0代表概率最小、1代表最大。
glasses	否	array	是否带眼镜，face_field包含glasses时返回。
+type	否	string	none:无眼镜，common:普通眼镜，sun:墨镜
+probability	否	double	眼镜置信度，范围【0~1】，0代表概率最小、1代表最大。
eye_status	否	array	双眼状态（睁开/闭合） face_field包含eye_status时返回。
+left_eye	否	double	左眼状态 [0,1]取值，越接近0闭合的可能性越大。
+right_eye	否	double	右眼状态 [0,1]取值，越接近0闭合的可能性越大。
emotion	否	array	情绪， face_field包含emotion时返回。
+type	否	string	angry:愤怒 disgust:厌恶 fear:恐惧 happy:高兴 sad:伤心 surprise:惊讶 neutral:无情绪 pouty: 撅嘴 grimace:鬼脸
+probability	否	double	情绪置信度，范围0~1。
race	否	array	人种，face_field包含race时返回。
+type	否	string	yellow: 黄种人 white: 白种人 black:黑种人 arabs: 阿拉伯人
+probability	否	double	人种置信度，范围0~1。
face_type	否	array	真实人脸/卡通人脸，face_field包含face_type时返回。
+type	否	string	human: 真实人脸 cartoon: 卡通人脸
+probability	否	double	人脸类型判断正确的置信度，范围【0~1】，0代表概率最小、1代表最大。
mask	否	array	口罩识别，face_field包含mask时返回。
+type	否	int	0：代表没戴口罩 1：代表戴口罩
+probability	否	double	置信度，范围0~1。
landmark	否	array	4个关键点位置，左眼中心、右眼中心、鼻尖、嘴中心。face_field包含landmark时返回。
landmark72	否	array	72个特征点位置，face_field包含landmark时返回。
landmark150	否	array	150个特征点位置，face_field包含landmark150时返回。
quality	否	array	人脸质量信息，face_field包含quality时返回。
+occlusion	否	array	人脸各部分遮挡的概率，范围[0~1]，0表示完整，1表示不完整。
++left_eye	否	double	左眼遮挡比例，[0-1] ， 1表示完全遮挡。
++right_eye	否	double	右眼遮挡比例，[0-1] ， 1表示完全遮挡。
++nose	否	double	鼻子遮挡比例，[0-1] ， 1表示完全遮挡。
++mouth	否	double	嘴巴遮挡比例，[0-1] ， 1表示完全遮挡。
++left_cheek	否	double	左脸颊遮挡比例，[0-1] ， 1表示完全遮挡。
++right_cheek	否	double	右脸颊遮挡比例，[0-1] ， 1表示完全遮挡。
++chin_contour	否	double	下巴遮挡比例，，[0-1] ， 1表示完全遮挡。
+blur	否	double	人脸模糊程度，范围[0~1]，0表示清晰，1表示模糊。
+illumination	否	double	取值范围在[0~255], 表示脸部区域的光照程度越大表示光照越好。
+completeness	否	int64	人脸完整度，0或1, 0为人脸溢出图像边界，1为人脸都在图像边界内。
liveness	否	array	单张图片活体检测结果
+livemapscore	否	double	单张图片的活体打分，范围[0~1]。
spoofing	否	double	判断图片是否合成图功能

返回示例

{
    "error_code": 0,
    "error_msg": "SUCCESS",
    "log_id": 1234567890123,
    "timestamp": 1533094517,
    "cached": 0,
    "result": {
        "thresholds": {
            "frr_1e-4": 0.05,
            "frr_1e-3": 0.3,
            "frr_1e-2": 0.9
        },
        "face_liveness": 0.05532243927,
        "face_list": [
            {
                "face_token": "aaaaaaxxadqeqaaaaaa....",
                "location": {
                    "left": 328.9026489,
                    "top": 97.16340637,
                    "width": 162,
                    "height": 154,
                    "rotation": 32
                },
                "face_probability": 1,
                "angle": {
                    "yaw": 10.16196251,
                    "pitch": 2.244354248,
                    "roll": 33.82199097
                },
                "liveness": {
                    "livemapscore": 0.04492170034
                },
                "age": 23,
                "beauty": 20.23693275
            },
            {
                "face_token": "aaaaaaaaaaaaa...",
                "location": {
                    "left": 411.4876404,
                    "top": 166.3593445,
                    "width": 329,
                    "height": 308,
                    "rotation": 45
                },
                "face_probability": 0.9194830656,
                "angle": {
                    "yaw": -1.716423035,
                    "pitch": 7.344647408,
                    "roll": 45.79914856
                },
                "liveness": {
                    "livemapscore": 0.001787073661
                },
                "age": 23,
                "beauty": 12.6438179
            },
            {
                "face_token": "aaaaaaaaaaaaa.....",
                "location": {
                    "left": 161.4559937,
                    "top": 199.8726501,
                    "width": 218,
                    "height": 201,
                    "rotation": -1
                },
                "face_probability": 1,
                "angle": {
                    "yaw": -8.187754631,
                    "pitch": 6.973727226,
                    "roll": -1.25429821
                },
                "liveness": {
                    "livemapscore": 0.05532243927
                },
                "age": 23,
                "beauty": 8.20657444
            }
        ]
    }
}

活体阈值说明

阈值	误拒率	通过率	攻击拒绝率
0.05	0.01%	99.99%	58.62%
0.1	0.05%	99.95%	79.28%
0.3	0.1%	99.9%	83.77%
0.5	0.5%	99.5%	94.98%
0.9	1%	99%	97.30%

合成图阈值说明

合成图阈值	误拒率	通过率	攻击拒绝率
0.00023	5%	95%	94.93%
0.00048（推荐）	1%	99%	89.71%
0.00066	0.5%	99.5%	88.02%
0.00109	0.1%	99.9%	84.57%
0.00171	0.05%	99.95%	81.52%
0.00547	0.01%	99.99%	65.52%

阈值（Threshold）：高于此数值，则可判断为活体。（视用户的业务场景需求，选用合适的阈值）

误拒率（FRR）：如0.5%，指1000次真人请求，会有5次因为活体分数低于阈值被错误拒绝。

通过率（TAR）：如99%，指100次真人请求，会有99次因为活体分数高于阈值而通过。

攻击拒绝率（TRR）：如99%，代表100次作弊假体攻击，会有99次被拒绝。

2.1.6 多人脸对比

两张人脸图片相似度对比：上传图片A中m个人脸与上传图B中n个人脸互相比对并返回相似度分

请求路径

/api/face-api/v3/face/multi-match

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B

Header：

参数	值
Content-Type	application/json

Body请求参数

参数名	必选	类型	说明
image	是	string	图片信息(*数据大小应小于10M 分辨率应小于19201080**)
image_type	是	string	图片类型 BASE64:图片的base64值

注意：请求体要求为json格式，可以参考请求示例

请求示例

[
      {
          "image": "sfasq35sadvsvqwr5q...",
          "image_type": "BASE64",
      },
      {
          "image": "sfasq35sadvsvqwr5q...",
          "image_type": "BASE64",
      }
]

返回结果

参数名	必选	类型	说明
max_match_score	是	float	上传图A中m个人脸与上传图B中n个人脸互相比对得分集合中的最高得分
image_face_list	是	array	上传图片所检测出来的人脸信息
image_index	是	int	图片索引
image_face_index	是	int	图片检测出的人脸索引
face_token	是	string	人脸标志ID
liveness_score	是	float	人脸活体得分
spoofing_score	是	float	人脸合成图得分
face_location	是	array	人脸位置信息+ left
+left	是	float	人脸区域离左边界的距离
+top	是	float	人脸区域离上边界的距离
+width	是	float	人脸区域的宽度
+height	是	float	人脸区域的高度
+rotation	是	int64	人脸框相对于竖直方向的顺时针旋转角，[-180,180]
face_match_list	是	array	人脸比对列表
match_score	是	float	两个人脸比对相似得分。分数范围为[0-100]；80分以上可以判断为同一人。此分值对应万分之一误识率
face_list	是	array	进行比对的两个人脸标志ID, 每个元素为string 类型

返回示例

{
    "error_code": 0,
    "error_msg": "SUCCESS",
    "log_id": 743874065,
    "timestamp": 1718880326,
    "cached": 0,
    "result": {
        "max_match_score":26.92814636,
        "image_face_list": [
            [
                {
                    "image_index": 0,
                    "image_face_index": 0,
                    "face_token": "68f8b78b9847ec9ef5f1d96be7263069",
                    "liveness_score": 0.9995498657,
                    "spoofing_score": 3.576278718e-10,
                    "face_location": {
                        "left": 369.6,
                        "top": 112.89,
                        "width": 151,
                        "height": 191,
                        "rotation": -5
                    }
                },
                {
                    "image_index": 0,
                    "image_face_index": 1,
                    "face_token": "b16ae98382226f8c61c4a728e515ef98",
                    "liveness_score": 0.9995416403,
                    "spoofing_score": 1.192092869e-9,
                    "face_location": {
                        "left": 153.06,
                        "top": 114.46,
                        "width": 116,
                        "height": 123,
                        "rotation": 4
                    }
                }
            ],
            [
                {
                    "image_index": 1,
                    "image_face_index": 0,
                    "face_token": "0014742de2deb6da31b0aa1be496f357",
                    "liveness_score": 0.6367498636,
                    "spoofing_score": 3.552436922e-8,
                    "face_location": {
                        "left": 1204.54,
                        "top": 325.69,
                        "width": 32,
                        "height": 26,
                        "rotation": -7
                    }
                },
                {
                    "image_index": 1,
                    "image_face_index": 1,
                    "face_token": "6db8c6a65deb7e308a0049e4ac99b344",
                    "liveness_score": 0.3154625893,
                    "spoofing_score": 5.519390101e-8,
                    "face_location": {
                        "left": 1153.56,
                        "top": 325.17,
                        "width": 25,
                        "height": 24,
                        "rotation": 3
                    }
                },
                {
                    "image_index": 1,
                    "image_face_index": 2,
                    "face_token": "36ee9609231109708ecdbf5011679fb0",
                    "liveness_score": 0.13139534,
                    "spoofing_score": 0.9980351925,
                    "face_location": {
                        "left": 897.34,
                        "top": 278.02,
                        "width": 23,
                        "height": 20,
                        "rotation": 152
                    }
                },
                {
                    "image_index": 1,
                    "image_face_index": 3,
                    "face_token": "b33fa3cb06a26c461ef8699817064397",
                    "liveness_score": 0.06778178364,
                    "spoofing_score": 1.894831598e-7,
                    "face_location": {
                        "left": 1090.03,
                        "top": 397.86,
                        "width": 21,
                        "height": 15,
                        "rotation": 5
                    }
                },
                {
                    "image_index": 1,
                    "image_face_index": 4,
                    "face_token": "729c9000d6777adf1ecc5c6e8d45bd52",
                    "liveness_score": 0.9925355911,
                    "spoofing_score": 0.9294455051,
                    "face_location": {
                        "left": 480.71,
                        "top": 316.77,
                        "width": 15,
                        "height": 16,
                        "rotation": -5
                    }
                }
            ]
        ],
        "face_match_list": [
            {
                "match_score": 26.92814636,
                "face_list": [
                    "68f8b78b9847ec9ef5f1d96be7263069",
                    "0014742de2deb6da31b0aa1be496f357"
                ]
            },
            {
                "match_score": 0,
                "face_list": [
                    "68f8b78b9847ec9ef5f1d96be7263069",
                    "6db8c6a65deb7e308a0049e4ac99b344"
                ]
            },
            {
                "match_score": 0,
                "face_list": [
                    "68f8b78b9847ec9ef5f1d96be7263069",
                    "36ee9609231109708ecdbf5011679fb0"
                ]
            },
            {
                "match_score": 0,
                "face_list": [
                    "68f8b78b9847ec9ef5f1d96be7263069",
                    "b33fa3cb06a26c461ef8699817064397"
                ]
            },
            {
                "match_score": 0,
                "face_list": [
                    "68f8b78b9847ec9ef5f1d96be7263069",
                    "729c9000d6777adf1ecc5c6e8d45bd52"
                ]
            },
            {
                "match_score": 2.084144592,
                "face_list": [
                    "b16ae98382226f8c61c4a728e515ef98",
                    "0014742de2deb6da31b0aa1be496f357"
                ]
            },
            {
                "match_score": 16.59023285,
                "face_list": [
                    "b16ae98382226f8c61c4a728e515ef98",
                    "6db8c6a65deb7e308a0049e4ac99b344"
                ]
            },
            {
                "match_score": 0,
                "face_list": [
                    "b16ae98382226f8c61c4a728e515ef98",
                    "36ee9609231109708ecdbf5011679fb0"
                ]
            },
            {
                "match_score": 5.201381683,
                "face_list": [
                    "b16ae98382226f8c61c4a728e515ef98",
                    "b33fa3cb06a26c461ef8699817064397"
                ]
            },
            {
                "match_score": 3.063270569,
                "face_list": [
                    "b16ae98382226f8c61c4a728e515ef98",
                    "729c9000d6777adf1ecc5c6e8d45bd52"
                ]
            }
        ]
    }
}

2.2 人脸管理接口

2.2.1 人脸注册

向人脸库中添加人脸(如果group,uid不存在, 则会自动创建用户组和注册用户)。组下单个用户的人脸数目限制为20张（如果不同组下有同一个user_id，每个组的user_id下的人脸数目都是限制20，不会合并计算）

请求路径:

api/face-api/v3/face/add

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
user_id	是	string	用户id（由数字、字母、下划线组成），长度限制48B。
group_id	是	string	用户组id，标识一组用户（由数字、字母、下划线组成），长度限制48B。
image	是	string	图片信息(*数据大小应小于10M 分辨率应小于19201080**)
image_type	是	string	图片类型 BASE64：图片的base64值
user_info	否	string	用户资料，长度限制256B，
option	否	string	人脸的类型 LIVE：表示生活照：通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等。（默认） CERT：表示证件照片：如拍摄的身份证、工卡、护照、学生证等证件图片。
quality_control	否	string	质量控制 NONE:不进行质量控制（默认） LOW:较低的质量要求 NORMAL：一般的质量要求 HIGH：较高的质量要求
liveness_control	否	string	活体控制 NONE：不进行活体控制（默认） LOW：较低的活体要求【高通过率 + 低攻击拒绝率】 NORMAL：一般的活体要求【中通过率 + 中攻击拒绝率】 HIGH：较高的活体要求【低通过率 + 高攻击拒绝率】
spoofing_control	否	string	合成图控制 NONE：不进行合成图控制（默认） LOW：较低的合成图要求【高通过率 + 低攻击拒绝率)】 NORMAL：一般的合成图要求【中通过率 + 中攻击拒绝率)】 HIGH：较高的合成图要求【低通过率 + 高攻击拒绝率)】
action_type	否	string	操作方式 APPEND：当user_id在库中已经存在时，对此user_id重复注册时，新注册的图片默认会追加到该user_id下。（默认） REPLACE：当对此user_id重复注册时,则会用新图替换库中该user_id下所有图片。
face_sort_type	否	int	人脸检测排序类型： 0：代表按人脸框面积排序（默认） 1：代表使用近图像中心点策略

请求示例

  {
      "image": "027d8308a2ec665acb1bdf63e513bcb9",
      "image_type": "FACE_TOKEN",
      "group_id": "group_repeat",
      "user_id" : "user1",
      "user_info" : "abc",
      "quality_control": "LOW",
      "liveness_control": "NORMAL"
  }

返回结果

字段	必选	类型	说明
face_token	是	string	人脸图片的唯一标识
location	是	array	人脸在图片中的位置
+left	是	double	人脸区域离左边界的距离
+top	是	double	人脸区域离上边界的距离
+width	是	double	人脸区域的宽度
+height	是	double	人脸区域的高度
+rotation	是	int64	人脸框相对于竖直方向的顺时针旋转角，[-180,180]

每个face_token在用户组下都是唯一的，即同一张人脸无法在同一个用户组下注册多次

返回示例

{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "log_id": 1234567890123,
  "timestamp": 1533094602,
  "cached": 0,
  "result": {
      "face_token": "2fa64a88a9d5118916f9a303782a97d3",
      "location": {
          "left": 117,
          "top": 131,
          "width": 172,
          "height": 170,
          "rotation": 4
      }
  }
}

2.2.2 人脸更新

用于对人脸库中指定用户，更新其下的人脸图像。
说明：针对一个user_id执行更新操作，新上传的人脸图像将覆盖该group_id中user_id的原有所有图像。

请求路径:

/face-api/v3/face/update

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
user_id	是	string	用户id（由数字、字母、下划线组成），长度限制48B。
group_id	是	string	用户组id，标识一组用户（由数字、字母、下划线组成），长度限制48B。
image	是	string	图片信息(*数据大小应小于10M 分辨率应小于19201080**)
image_type	是	string	图片类型 BASE64：图片的base64值
user_info	否	string	用户资料，长度限制256B。
option	否	string	人脸的类型 LIVE：表示生活照：通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等。（默认） CERT：表示证件照片：如拍摄的身份证、工卡、护照、学生证等证件图片。
quality_control	否	string	质量控制 NONE: 不进行质量控制（默认） LOW: 较低的质量要求 NORMAL：一般的质量要求 HIGH：较高的质量要求
liveness_control	否	string	活体控制 NONE：不进行活体控制（默认） LOW：较低的活体要求【高通过率 + 低攻击拒绝率】 NORMAL：一般的活体要求【中通过率 + 中攻击拒绝率】 HIGH：较高的活体要求【低通过率 + 高攻击拒绝率】
spoofing_control	否	string	合成图控制 NONE：不进行合成图控制（默认） LOW：较低的合成图要求【高通过率 + 低攻击拒绝率)】 NORMAL：一般的合成图要求【中通过率 + 中攻击拒绝率)】 HIGH：较高的合成图要求【低通过率 + 高攻击拒绝率)】
action_type	否	string	操作方式 UPDATE：会使用新图替换库中该user_id下所有图片, 若user_id不存在则会报错。（默认） REPLACE ：当user_id不存在时, 则会注册这个user_id的用户。

请求示例

  {
      "image": "027d8308a2ec665acb1bdf63e513bcb9",
      "image_type": "FACE_TOKEN",
      "group_id": "group_repeat",
      "user_id" : "user1",
      "user_info" : "cba",
      "quality_control": "LOW",
      "liveness_control": "NORMAL"
  }

返回结果

字段	必选	类型	说明
face_token	是	string	人脸图片的唯一标识
location	是	array	人脸在图片中的位置
+left	是	double	人脸区域离左边界的距离
+top	是	double	人脸区域离上边界的距离
+width	是	double	人脸区域的宽度
+height	是	double	人脸区域的高度
+rotation	是	int64	人脸框相对于竖直方向的顺时针旋转角，[-180,180]

返回示例

{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "log_id": 1234567890123,
  "timestamp": 1533094612,
  "cached": 0,
  "result": {
      "face_token": "2fa64a88a9d5118916f9a303782a97d3",
      "location": {
          "left": 117,
          "top": 131,
          "width": 172,
          "height": 170,
          "rotation": 4
      }
  }
}

2.2.3 人脸列表

获取一个用户下的人脸列表

请求路径

api/face-api/v3/face/list

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
user_id	是	string	用户id（由数字、字母、下划线组成），长度限制4B。
group_id	是	string	用户组id（由数字、字母、下划线组成）长度限制48B。
image_type	否	string	说明：是否返回图片face_token关联图片的BASE64值传值：BASE64 或是不使用此参数字段

请求示例

{
    "user_id": "user1",
    "group_id": "group1",
	"image_type": "BASE64", //可选请求字段
}

返回结果

字段	必选	类型	说明
face_list	是	array	人脸信息列表
+face_token	是	string	人脸标志
+ctime	是	string	人脸创建时间
+image_base64	否	string	face_token关联图片的base64值

返回示例

{
    "error_code": 0,
    "error_msg": "SUCCESS",
    "log_id": 1234567890123,
    "timestamp": 1533094619,
    "cached": 0,
    "result": {
        "face_list": [
            {
                "face_token": "fid1",
                "ctime": "2018-01-01 00:00:00",
				  "image_base64": "4AAQSkZJRgABAQAAAQABAAD....",	//非必须返回字段

            },
            {
                "face_token": "fid2",
                "ctime": "2018-01-01 10:00:00"
            }
        ]
    }
}

2.2.4 删除人脸

删除用户下的某一张人脸如果该用户下没有其他人脸了则同时删除用户

请求路径

api/face-api/v3/face/delete

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
user_id	是	string	用户id（由数字、字母、下划线组成），长度限制48B。
group_id	是	string	用户组id（由数字、字母、下划线组成），长度限制48B。
face_token	是	string	人脸id（由数字、字母、下划线组成），长度限制64B。

请求示例

  {
      "user_id": "user1",
      "group_id": "group1",
      "face_token": "2fa64a88a9d5118916f9a303782a97d3"
  }

返回结果通过返回的error_code判断是否成功如失败则查看error_msg获得具体错误信息

  {
      "error_code": 0,
      "error_msg": "SUCCESS",
      "log_id": 1234567890123,
      "timestamp": 1533094650,
      "cached": 0,
      "result": null
  }

2.3 用户管理接口

2.3.1 复制用户

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

请求路径

api/face-api/v3/user/copy

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B。

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
user_id	是	string	用户id
src_group_id	是	string	从指定group里复制，长度限制48B。
dst_group_id	是	string	需要添加用户的组id，长度限制48B。

请求示例

  {
      "user_id": "user1",
      "src_group_id": "group1",
      "dst_group_id": "group2"
  }

返回结果通过返回的error_code判断是否成功如失败则查看error_msg获得具体错误信息

  {
      "error_code": 0,
      "error_msg": "SUCCESS",
      "log_id": 1234567890123,
      "timestamp": 1533094714,
      "cached": 0,
      "result": null
  }

2.3.2 获取用户信息

获取人脸库中某个用户的信息(user_info信息和用户所属的组)

请求路径

api/face-api/v3/user/get

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B。

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
user_id	是	string	用户id（由数字、字母、下划线组成），长度限制48B。
group_id	是	string	用户组id(由数字、字母、下划线组成，长度限制48B) 如传入@ALL则从所有组中查询用户信息

请求示例

  {
      "user_id": "user1",
      "group_id": "group1"
  }

返回结果

字段	必选	类型	说明
user_list	是	array	用户信息列表
+user_info	是	string	用户注册时携带的用户信息
+group_id	是	string	用户所属的group_id

返回示例

  {
      "error_code": 0,
      "error_msg": "SUCCESS",
      "log_id": 1234567890123,
      "timestamp": 1533094729,
      "cached": 0,
      "result": {
          "user_list": [
              {
                  "user_info": "user info ...",
                  "group_id": "gid1"
              },
              {
                  "user_info": "user info2 ...",
                  "group_id": "gid2"
              }
          ]
      }
  }

2.3.3 用户列表

获取用户组中的用户列表

请求路径

api/face-api/v3/user/list

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B。

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
group_id	是	string	用户组id
start	否	uint32	默认值0，起始序号
length	否	uint32	返回数量，默认值100，最大值1000。

请求示例

  {
   	"group_id": "group1"   
  }

返回结果

字段	必选	类型	说明
user_id_list	是	array	用户ID列表

返回示例

  {
      "error_code": 0,
      "error_msg": "SUCCESS",
      "log_id": 1234567890123,
      "timestamp": 1533094739,
      "cached": 0,
      "result": {
          "user_id_list": [
              "uid1",
              "uid2"
          ]
      }
  }

2.3.4 删除用户

将用户从某个组中删除

请求路径

/face-api/v3/user/delete

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B。

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
group_id	是	string	用户组id(由数字、字母、下划线组成，长度限制48B) 如传入@ALL则从所有组中删除用户
user_id	是	string	用户id(由数字、字母、下划线组成，长度限制48B)

请求示例

  {
      "user_id": "user1",
      "group_id": "group1"
  }

返回结果通过返回的error_code判断是否成功如失败则查看error_msg获得具体错误信息

  {
      "error_code": 0,
      "error_msg": "SUCCESS",
      "log_id": 1234567890123,
      "timestamp": 1533094766,
      "cached": 0,
      "result": null
  }

2.4 用户组管理接口

2.4.1 创建用户组

创建一个空的用户组，如果用户组已存在，则返回错误。

请求路径

api/face-api/v3/group/add

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
group_id	是	string	group标识（由数字、字母、下划线组成），长度限制48B。
option	否	string	人脸的类型 LIVE：表示生活照：通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等。（默认） CERT：表示证件照片：如拍摄的身份证、工卡、护照、学生证等证件图片。

请求示例
```
{
    "group_id": "group1"
}
```
返回结果通过返回的error_code判断是否成功如失败则查看error_msg获得具体错误信息

{
    "error_code": 0,
    "error_msg": "SUCCESS",
    "log_id": 1234567890123,
    "timestamp": 1533094781,
    "cached": 0,
    "result": null
}

2.4.2 用户组列表

获取人脸库中用户组的列表

请求路径

api/face-api/v3/group/list

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B。

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
start	否	uint32	默认值0，起始序号。
length	否	uint32	返回数量，默认值100，最大值1000。

请求示例

  {
      "start": 0,
      "length": 100
  }

返回结果

字段	必选	类型	说明
group_id_list	是	array	group_id列表

返回示例

{
  "error_code": 0,
  "error_msg": "SUCCESS",
  "log_id": 1234567890123,
  "timestamp": 1533094800,
  "cached": 0,
  "result": {
      "group_id_list": [
          "gid1",
          "gid2"
      ]
  }
}

2.4.3 删除用户组

接口说明：删除用户组下所有的用户信息及人脸信息。如果组下的人脸数量大于100条，将会在后台排队进行处理；在删除期间，无法再往该组中添加人脸。

路径

api/face-api/v3/group/delete

URL请求参数

参数	必选	类型	说明
appid	是	string	app标识（由数字、字母、下划线组成），长度限制48B

Header：

参数	值
Content-Type	application/json

Body请求参数

请求参数	必选	类型	说明
group_id	是	string	group标识（由数字、字母、下划线组成），长度限制48B

返回结果通过返回的error_code判断是否成功如失败则查看error_msg获得具体错误信息

注：
用户组删除为异步操作，通过定时任务每5min执行一次
1、删除1W人脸库大约需要70s；
2、删除5W人脸库大约需要3min；
3、删除10W人脸库大约需要4min；

{
    "error_code": 0,
    "error_msg": "SUCCESS",
    "log_id": 1234567890123,
    "timestamp": 1533094791,
    "cached": 0,
    "result": null
}

3.错误码对照表

错误码	错误信息	说明	处理建议
222001	param[] is null	必要参数未传入	参考API说明文档，修改参数
222002	param[start] format error	参数格式错误	参考API说明文档，修改参数
222003	param[length] format error	参数格式错误	参考API说明文档，修改参数
222004	param[op_app_id_list] format error	参数格式错误	参考API说明文档，修改参数
222005	param[group_id_list] format error	参数格式错误	参考API说明文档，修改参数
222006	group_id format error	参数格式错误	参考API说明文档，修改参数
222007	uid format error	参数格式错误	参考API说明文档，修改参数
222008	face_id format error	参数格式错误	参考API说明文档，修改参数
222009	quality_conf format error	参数格式错误	参考API说明文档，修改参数
222010	user_info format error	参数格式错误	参考API说明文档，修改参数
222011	param[uid_list] format error	参数格式错误	参考API说明文档，修改参数
222012	param[op_app_id] format error	参数格式错误	参考API说明文档，修改参数
222013	param[image] format error	参数格式错误	参考API说明文档，修改参数
222014	param[app_id] format error	参数格式错误	参考API说明文档，修改参数
222015	param[image_type] format error	参数格式错误	参考API说明文档，修改参数
222016	param[max_face_num] format error	参数格式错误	参考API说明文档，修改参数
222017	param[face_field] format error	参数格式错误	参考API说明文档，修改参数
222018	param[user_id] format error	参数格式错误	参考API说明文档，修改参数
222019	param[quality_control] format error	参数格式错误	参考API说明文档，修改参数
222020	param[liveness_control] format error	参数格式错误	参考API说明文档，修改参数
222021	param[max_user_num] format error	参数格式错误	参考API说明文档，修改参数
222022	param[id_card_number] format error	参数格式错误	参考API说明文档，修改参数
222023	param[name] format error	参数格式错误	参考API说明文档，修改参数
222024	param[face_type] format error	参数格式错误	参考API说明文档，修改参数
222025	param[face_token] format error	参数格式错误	参考API说明文档，修改参数
222026	param[max_star_num] format error	参数格式错误	参考API说明文档，修改参数
222027	code length param error	验证码长度错误 (最小值大于最大值)	参考API说明文档，修改参数
222028	param[min_code_length] format error	参数格式错误	参考API说明文档，修改参数
222029	param[max_code_length] format error	参数格式错误	参考API说明文档，修改参数
222030	param[match_threshold] format error	参数格式错误	参考API说明文档，修改参数
222200	request body should be json format	该接口需使用 application/json的格式进行请求	请修改接口格式为： application/json
222201	network not available	服务端请求失败	重新尝试
222202	pic not has face	图片中没有人脸	检查图片质量
222203	image check fail	无法解析人脸	检查图片质量
222204	image_url_download_fail	从图片的url下载图片失败	请确认url可公网访问
222205	network not availablel	服务端请求失败	重新尝试
222206	rtse service return fail	服务端请求失败	重新尝试
222207	match user is not found	未找到匹配的用户	请确认人脸库中是否存在此用户
222208	the number of image is incorrect	图片的数量错误	多张图片请使用 json格式传输
222209	face token not exist	face token不存在	请确认您操作的人脸已创建成功；若face_token未注册到人脸库则有效期只有1小时注册人脸库的 face_token永久有效
222210	the number of user's faces is beyond the limit	人脸库中用户下的人脸数目超过限制	当前每个用户下限制人脸数目最大20张
222300	add face fail	人脸图片添加失败	重新尝试
222301	get face fail	获取人脸图片失败	请重新尝试，如果持续出现此类错误，请提交工单
222302	system error	服务端请求失败	重新尝试
222303	get face fail	获取人脸图片失败	请重新尝试，如果持续出现此类错误，请提交工单
223100	group is not exist	操作的用户组不存在	请确认您操作的用户组已创建成功
223101	group is already exist	该用户组已存在	请不要重复创建用户组
223102	user is already exist	该用户已存在	请不要重复创建用户
223103	user is not exist	找不到该用户	请确认您操作的用户已创建成功
223104	group_list is too large	group_list包含组数量过多	请按照文档提示设置group_list参数
223105	face is already exist	该人脸已存在	请不要重复添加人脸
223106	face is not exist	该人脸不存在	请确认您操作的人脸已创建成功；若face_token未注册到人脸库则有效期只有1小时，注册人脸库的 face_token永久有效
223110	uid_list is too large	uid_list包含数量过多	请按照文档提示设置user_list参数
223111	dst group not exist	目标用户组不存在	请确认您操作的用户组已创建成功
223112	quality_conf format error	quality_conf格式不正确	请按照文档提示设置 quality_conf参数
223113	face is covered	人脸有被遮挡	提示用户请勿遮挡面部
223114	face is fuzzy	人脸模糊	人脸图片模糊，前端页面可以提示用户拍摄时不要晃动手机
223115	face light is not good	人脸光照不好	提示用户到光线适宜的地方拍摄
223116	incomplete face	人脸不完整	提示用户请勿遮挡面部
223117	app_list is too large	app_list包含app数量过多	请按照文档提示设置 app_list参数
223118	quality control error	质量控制项错误	请按照文档提示设置质量控制参数
223119	liveness control item error	活体控制项错误	请按照文档提示设置活体控制参数
223120	liveness check fail	活体检测未通过	此次活体检测结果为非活体
223121	left eye is occlusion	质量检测未通过左眼遮挡程度过高	提示用户请勿遮挡左眼
223122	right eye is occlusion	质量检测未通过右眼遮挡程度过高	提示用户请勿遮挡右眼
223123	left cheek is occlusion	质量检测未通过左脸遮挡程度过高	提示用户请勿遮挡左脸颊
223124	right cheek is occlusion	质量检测未通过右脸遮挡程度过高	提示用户请勿遮挡右脸颊
223125	chin contour is occlusion	质量检测未通过下巴遮挡程度过高	提示用户请勿遮挡下巴
223126	nose is occlusion	质量检测未通过鼻子遮挡程度过高	提示用户请勿遮挡鼻子
223127	mouth is occlusion	质量检测未通过嘴巴遮挡程度过高	提示用户请勿遮挡嘴巴
222901	system busy	参数校验初始化失败	请重新尝试，若尝试多次无效，请提交工单咨询
222902	system busy	参数校验初始化失败	请重新尝试，若尝试多次无效，请提交工单咨询
222903	system busy	参数校验初始化失败	请重新尝试，若尝试多次无效，请提交工单咨询
222904	system busy	参数校验初始化失败	请重新尝试，若尝试多次无效，请提交工单咨询
222905	system busy	接口初始化失败	请重新尝试，若尝试多次无效，请提交工单咨询
222906	system busy	接口初始化失败	请重新尝试，若尝试多次无效，请提交工单咨询
222907	system busy	缓存处理失败	请重新尝试，若尝试多次无效，请提交工单咨询
222908	system busy	缓存处理失败	请重新尝试，若尝试多次无效，请提交工单咨询
222909	system busy	缓存处理失败	请重新尝试，若尝试多次无效，请提交工单咨询
222910	system busy	数据存储处理失败	请重新尝试，若尝试多次无效，请提交工单咨询
222911	system busy	数据存储处理失败	请重新尝试，若尝试多次无效，请提交工单咨询
222912	system busy	数据存储处理失败	请重新尝试，若尝试多次无效，请提交工单咨询
222913	system busy	接口初始化失败	请重新尝试，若尝试多次无效，请提交工单咨询
222914	system busy	接口初始化失败	请重新尝试，若尝试多次无效，请提交工单咨询
222915	system busy	后端服务连接失败	请重新尝试，若尝试多次无效，请提交工单咨询
222916	system busy	后端服务连接失败	请重新尝试，若尝试多次无效，请提交工单咨询
222304	image size is too large	图片尺寸太大	请确保图片尺寸在1920x1080以下下
223128	group was deleting	正在清理该用户组的数据	请等该用户组清理完毕后再对该组进行操作
222361	system busy	公安服务连接失败	请重新尝试，若尝试多次无效，请提交工单咨询
222046	param[template_type] format error	参数格式错误	请参考接口文档修改
222101	param[merge_degree] format error	参数格式错误	请参考API说明文档，修改参数
222102	param[face_location] format error	参数格式错误	参考API说明文档，修改参数
222307	image illegal, reason: porn	图片非法鉴黄未通过	请重新上传合法的图片
222308	image illegal, reason: sensitive person	图片非法含有政治敏感人物	请重新上传合法的图片
222211	template image quality reject	人脸融合失败模板图质量不合格	请检查模板图是否符合人脸融合文档中的质量要求
222212	merge face fail	人脸融合失败	请更换素材后重新尝试，如果持续出现此类错误，请提交工单
223129	face not forward	人脸未面向正前方（人脸的角度信息大于30度）	请使用面向正前方的人脸图片
222290	auth fail	feature服务鉴权失败	请检查授权服务运行正常，网络通畅
222291	qps exceed maximum	feature服务QPS超限	请降低服务访问频率
222292	auth expired	feature服务鉴权过期	请联系服务人员更新授权文件
222293	instance exceed maximum	feature服务实例数超限	请将运行实例数控制在授权数量内

更新记录

错误码