接口文档

更新时间：2024-04-11

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 //未启用 无需处理
}

阈值说明

遮挡情况的阈值

控制度	left_eye	right_eye	nose	mouth	left_cheek	right_cheek	chin_contour
LOW	0.8	0.8	0.8	0.8	0.8	0.8	0.8
NORMAL	0.6	0.6	0.6	0.6	0.6	0.6	0.6
HIGH	0.2	0.2	0.2	0.2	0.2	0.2	0.2

模糊度、完整度的阈值

控制度	illumination	blurdegree	completeness
LOW	20	0.8	0
NORMAL	40	0.6	0
HIGH	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% 攻击拒绝率为63.91%
NORMAL	0.3	0.1%活体误拒率对应的通过率为99.9% 攻击拒绝率为90.32%
HIGH	0.9	1%活体误拒率对应的通过率为99% 攻击拒绝率为97.56%

误拒率（FRR）：如0.5%，指1000次真人请求，会有5次因为活体分数低于阈值被错误拒绝。通过率（TAR）：如99%，指100次真人请求，会有99次因为活体分数高于阈值而通过。攻击拒绝率（TRR）：如99%，代表100次作弊假体攻击，会有99次被拒绝。误拒率越高，其对攻击的防范能力也会越高

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 人脸检测

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

请求路径

/face-api/v3/face/detect

URL请求参数

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

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
image	是	string	图片信息(*总数据大小应小于10M，分辨率应小于19201080**)，图片上传方式根据image_type来判断
image_type	是	string	图片类型 BASE64:图片的base64值，base64编码后的图片数据，编码后的图片大小不超过2M； FACE_TOKEN: 人脸图片的唯一标识，调用人脸检测接口时，会为每个人脸图片赋予一个唯一的FACE_TOKEN，同一张图片多次检测得到的FACE_TOKEN是同一个。
face_field	否	string	包括age,expression,face_shape,gender,glasses,landmark,quality,face_type,parsing,eye_status,emotion,feature,spoofing信息逗号分隔. 默认只返回face_token、人脸框、概率和旋转角度
get_feature	否	string	是否保存特征值，只有保存了特征值之后才能使用FACE_TOKEN，默认为NO YES 保存特征值 NO 不保存特征值 2019.12.12以后部署的模型提供此接口请求参数，之前部署的模型若需要保存特征值，请在face_field字段中添加feature字段或者更新模型，更新方式请参考这里
max_face_num	否	uint32	最多处理人脸的数目，默认值为1，仅检测图片中面积最大的那个人脸；最大值10，检测图片中面积最大的几张人脸。若您想修改最大人脸检测数量数值，请参考接口调用问题文档
face_type	否	string	人脸的类型 LIVE表示生活照：通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等 IDCARD表示身份证芯片照：二代身份证内置芯片中的人像照片 WATERMARK表示带水印证件照：一般为带水印的小图，如公安网小图 CERT表示证件照片：如拍摄的身份证、工卡、护照、学生证等证件图片默认LIVE
liveness_control	否	string	活体控制检测结果中不符合要求的人脸会被过滤 NONE: 不进行控制 LOW:较低的活体要求(高通过率低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率低通过率) 默认NONE

若为视频监控模型，请求参数可以增加下列字段：

若您的前端摄像头是抓拍机抓拍并处理过的单人脸小图模式，推荐您在人脸检测/人脸注册/人脸更新/人脸搜索接口中使用SNAP参数，若为普通摄像头及混合场景模式，使用COMMON参数即可

参数	必选	类型	说明
image_spec	否	string	图片规格服务会对不同规格的图片采用不同的图片处理方式 COMMON: 通用图片规格默认的处理方式(如无适应的图片规格则使用此参数) SNAP: 从人脸抓拍机得到的抓拍图适用于小图片+单人脸的情况默认COMMON

请求示例

  {
      "image": "027d8308a2ec665acb1bdf63e513bcb9",
      "image_type": "FACE_TOKEN",
      "face_field": "faceshape,facetype"
  }

返回结果

字段	必选	类型	说明
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时返回
+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:无情绪
++probability	否	double	情绪置信度，范围0~1
+face_type	否	array	真实人脸/卡通人脸 face_field包含face_type时返回
++type	否	string	human: 真实人脸 cartoon: 卡通人脸
++probability	否	double	人脸类型判断正确的置信度，范围【0~1】，0代表概率最小、1代表最大。
+landmark	否	array	4个关键点位置，左眼中心、右眼中心、鼻尖、嘴中心。face_field包含landmark时返回
+landmark72	否	array	72个特征点位置 face_field包含landmark72时返回
+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	否	double	下巴遮挡比例，[0-1] ， 1表示完全遮挡
++blur	否	double	人脸模糊程度，范围[0~1]，0表示清晰，1表示模糊
++illumination	否	double	取值范围在[0~255], 表示脸部区域的光照程度越大表示光照越好
++completeness	否	int64	人脸完整度，0或1, 0为人脸溢出图像边界，1为人脸都在图像边界内
+spoofing	否	double	判断图片是否合成图功能
++char	否	string	人脸当前正在读出的文字（当前只支持对数字进行识别，返回内容为单个数字，范围0~9）
++probability	否	double	置信度，范围0~1
+parsing_info	否	string	人脸分层结果结果数据是使用gzip压缩后再base64编码使用前需base64解码后再解压缩原数据格式为string 形如0,0,0,0,0,1,1,1,1,1,1,2,2,2,2,2,2,2,2,2,…

返回示例

{
 "error_code": 0,
 "error_msg": "SUCCESS",
 "log_id": 1234567890123,
 "timestamp": 1533094400,
 "cached": 0,
 "result": {
     "face_num": 1,
     "face_list": [
         {
             "face_token": "35235asfas21421fakghktyfdgh68bio",
             "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,
             "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
             },
             "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
             }
         }
     ]
 }
}

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

2.1.2 人脸对比

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

请求路径

/face-api/v3/face/match

URL请求参数

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

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
image	是	string	图片信息(总数据大小应小于10M)，图片上传方式根据image_type来判断。两张图片通过json格式上传，格式参考表格下方示例
image_type	是	string	图片类型 BASE64:图片的base64值，base64编码后的图片数据，编码后的图片大小不超过2M； FACE_TOKEN: 人脸图片的唯一标识，调用人脸检测接口时，会为每个人脸图片赋予一个唯一的FACE_TOKEN，同一张图片多次检测得到的FACE_TOKEN是同一个。
face_type	否	string	人脸的类型 LIVE：表示生活照：通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等， IDCARD：表示身份证芯片照：二代身份证内置芯片中的人像照片， WATERMARK：表示带水印证件照：一般为带水印的小图，如公安网小图 CERT：表示证件照片：如拍摄的身份证、工卡、护照、学生证等证件图片默认LIVE
quality_control	否	string	图片质量控制 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求默认 NONE 若图片质量不满足要求，则返回结果中会提示质量检测失败
liveness_control	否	string	活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率低通过率) 默认 NONE 若活体检测结果不满足要求，则返回结果中会提示活体检测失败

请求示例

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

注意：请求体要求为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	人脸相似度得分，推荐阈值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 人脸搜索

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

请求路径

/face-api/v3/face/identify

URL请求参数

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

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
image	是	string	图片信息(总数据大小应小于10M)，图片上传方式根据image_type来判断
image_type	是	string	图片类型 BASE64:图片的base64值，base64编码后的图片数据，编码后的图片大小不超过2M； FACE_TOKEN: 人脸图片的唯一标识，调用人脸检测接口时，会为每个人脸图片赋予一个唯一的FACE_TOKEN，同一张图片多次检测得到的FACE_TOKEN是同一个。
group_id_list	是	string	从指定的group中进行查找用逗号分隔，上限10个
quality_control	否	string	图片质量控制 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求默认 NONE 若图片质量不满足要求，则返回结果中会提示质量检测失败
liveness_control	否	string	活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率低通过率) 默认NONE 若活体检测结果不满足要求，则返回结果中会提示活体检测失败
user_id	否	string	当需要对特定用户进行比对时，指定user_id进行比对。即人脸认证功能。
match_threshold	否	int	匹配阈值（设置阈值后，score低于此阈值的用户信息将不会返回）最大100 最小0 默认0 此阈值设置得越高，检索速度将会越快，推荐使用80的阈值
max_user_num	否	unit32	查找后返回的用户数量。返回相似度最高的几个用户，默认为1，最多返回50个,若您想要修改最大返回人脸数量，请参考4.如何控制1：N返回的最大人脸数问题文档

若为视频监控模型，请求参数可以增加下列字段：

若您的前端摄像头是抓拍机抓拍并处理过的单人脸小图模式，推荐您在人脸检测/人脸注册/人脸更新/人脸搜索接口中使用SNAP参数，若为普通摄像头及混合场景模式，使用COMMON参数即可

参数	必选	类型	说明
image_spec	否	string	图片规格服务会对不同规格的图片采用不同的图片处理方式 COMMON: 通用图片规格默认的处理方式(如无适应的图片规格则使用此参数) SNAP: 从人脸抓拍机得到的抓拍图适用于小图片+单人脸的情况默认COMMON

说明：如果使用base 64格式的图片，两张请求的图片请分别进行base64编码。

请求示例

  {
      "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 多人脸搜索

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

请求路径 /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值; FACE_TOKEN: face_token 人脸标识
group_id_list	是	string	从指定的group中进行查找用逗号分隔，上限10个
max_face_num	否	int	最多处理人脸的数目默认值为1(仅检测图片中面积最大的那个人脸) 最大值10
match_threshold	否	int	匹配阈值（设置阈值后，score低于此阈值的用户信息将不会返回）最大100 最小0 默认80 此阈值设置得越高，检索速度将会越快，推荐使用默认阈值`80`
quality_control	否	string	质量控制(质量不符合要求的人脸不会出现在返回结果中) NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求默认NONE
liveness_control	否	string	活体控制(活体分数不符合要求的人脸不会出现在返回结果中) NONE: 不进行控制 LOW:较低的活体要求(高通过率低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率低通过率) 默认NONE
max_user_num	否	unit32	识别返回的最大用户数，默认为1，最大值20

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

请求示例

{
"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张图片进行活体检测(如果传入一个人的多张图片，活体判断会更准确)

请求路径

/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_TOKEN: 人脸图片的唯一标识，调用人脸检测接口时，会为每个人脸图片赋予一个唯一的FACE_TOKEN，同一张图片多次检测得到的FACE_TOKEN是同一个。
face_field	否	string	包括age,expression,face_shape,gender,glasses,landmark,quality,face_type,parsing,eye_status,emotion,feature信息，逗号分隔，默认只返回face_token、活体数、人脸框、概率和旋转角度
option	否	string	场景信息，程序会视不同的场景选用相对应的模型。当前支持的场景有COMMON(通用场景)，GATE(闸机场景)，默认使用COMMON

请求示例

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

返回结果

参数	类型	是否必须	说明
face_liveness	是	float	活体分数值
thresholds	是	array	由服务端返回最新的阈值数据（随着模型的优化，阈值可能会变化），将此参数与返回的face_liveness进行比较，可以作为活体判断的依据。 frr_1e-4：万分之一误识率的阈值；frr_1e-3：千分之一误识率的阈值；frr_1e-2：百分之一误识率的阈值。误识率越低，准确率越高，相应的拒绝率也越高
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时返回
+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代表最大。
+face_type	否	array	真实人脸/卡通人脸 face_field包含face_type时返回
++type	否	string	human: 真实人脸 cartoon: 卡通人脸
++probability	否	double	人脸类型判断正确的置信度，范围【0~1】，0代表概率最小、1代表最大。
+landmark	否	array	4个关键点位置，左眼中心、右眼中心、鼻尖、嘴中心。face_field包含landmark时返回
+landmark72	否	array	72个特征点位置 face_field包含landmark时返回
+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	否	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]
+parsing_info	否	string	人脸分层结果结果数据是使用gzip压缩后再base64编码使用前需base64解码后再解压缩原数据格式为string 形如0,0,0,0,0,1,1,1,1,1,1,2,2,2,2,2,2,2,2,2,…
++char	否	string	人脸当前正在读出的文字（当前只支持对数字进行识别，返回内容为单个数字，范围0~9）
++probability	否	double	置信度，范围0~1

返回示例

{
"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": "df46f7c7db4aa09a093c26fb8d1a8d44",
            "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
        },
        {
            "face_token": "901d2c64274fccd687d311a6e6110a01",
            "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,
        },
        {
            "face_token": "7d57e36981c48b4946eb97c8d838b02a",
            "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
        }
    ]
}
}

活体阈值说明

阈值	误拒率	通过率	攻击拒绝率
0.05	0.01%	99.99%	63.91%
0.3	0.1%	99.9%	90.33%
0.9	1%	99%	97.56%

阈值（Threshold）：高于此数值，则可判断为活体。（视用户的业务场景需求，选用合适的阈值）
误拒率（FRR）：如0.5%，指1000次真人请求，会有5次因为活体分数低于阈值被错误拒绝。
通过率（TAR）：如99%，指100次真人请求，会有99次因为活体分数高于阈值而通过。
攻击拒绝率（TRR）：如99%，代表100次作弊假体攻击，会有99次被拒绝。

2.2 人脸管理接口

2.2.1 人脸注册

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

请求路径:

/face-api/v3/face/add

URL请求参数

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

Header：

参数	值
Content-Type	application/json

Body请求参数

参数	必选	类型	说明
image	是	string	图片信息(总数据大小应小于10M)，图片上传方式根据image_type来判断。注：组内每个uid下的人脸图片数目上限为20张
image_type	是	string	图片类型 BASE64:图片的base64值，base64编码后的图片数据，编码后的图片大小不超过2M； FACE_TOKEN：人脸图片的唯一标识，调用人脸检测接口时，会为每个人脸图片赋予一个唯一的FACE_TOKEN，同一张图片多次检测得到的FACE_TOKEN是同一个。
group_id	是	string	用户组id，标识一组用户（由数字、字母、下划线组成），长度限制48B。产品建议：根据您的业务需求，可以将需要注册的用户，按照业务划分，分配到不同的group下，例如按照会员手机尾号作为groupid，用于刷脸支付、会员计费消费等，这样可以尽可能控制每个group下的用户数与人脸数，提升检索的准确率单个group建议80W人脸上限
user_id	是	string	用户id（由数字、字母、下划线组成），长度限制48B
user_info	否	string	用户资料，长度限制256B 默认空
quality_control	否	string	图片质量控制 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求默认 NONE 若图片质量不满足要求，则返回结果中会提示质量检测失败
liveness_control	否	string	活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率低通过率) 默认NONE 若活体检测结果不满足要求，则返回结果中会提示活体检测失败
action_type	否	string	操作方式 APPEND: 当user_id在库中已经存在时，对此user_id重复注册时，新注册的图片默认会追加到该user_id下 REPLACE : 当对此user_id重复注册时,则会用新图替换库中该user_id下所有图片默认使用APPEND

若为视频监控模型，请求参数可以增加下列字段：

若您的前端摄像头是抓拍机抓拍并处理过的单人脸小图模式，推荐您在人脸检测/人脸注册/人脸更新/人脸搜索接口中使用SNAP参数，若为普通摄像头及混合场景模式，使用COMMON参数即可

参数	必选	类型	说明
image_spec	否	string	图片规格服务会对不同规格的图片采用不同的图片处理方式 COMMON: 通用图片规格默认的处理方式(如无适应的图片规格则使用此参数) SNAP: 从人脸抓拍机得到的抓拍图适用于小图片+单人脸的情况默认COMMON

说明：人脸注册完毕后，生效时间一般为5s以内，之后便可以进行人脸搜索或认证操作。

请求示例

  {
      "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请求参数

参数	必选	类型	说明
image	是	string	图片信息(总数据大小应小于10M)，图片上传方式根据image_type来判断
image_type	是	string	图片类型 BASE64:图片的base64值，base64编码后的图片数据，编码后的图片大小不超过2M； FACE_TOKEN: 人脸图片的唯一标识
group_id	是	string	用户组id，标识一组用户（由数字、字母、下划线组成），长度限制128B
user_id	是	string	用户id（由数字、字母、下划线组成），长度限制48B
user_info	否	string	用户资料，长度限制48B 默认空
quality_control	否	string	图片质量控制 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高的质量要求默认 NONE 若图片质量不满足要求，则返回结果中会提示质量检测失败
liveness_control	否	string	活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率低通过率) 默认NONE 若活体检测结果不满足要求，则返回结果中会提示活体检测失败
action_type	否	string	操作方式 UPDATE: 会使用新图替换库中该user_id下所有图片, 若user_id不存在则会报错 REPLACE : 当user_id不存在时, 则会注册这个user_id的用户默认使用UPDATE

若为视频监控模型，请求参数可以增加下列字段：

若您的前端摄像头是抓拍机抓拍并处理过的单人脸小图模式，推荐您在人脸检测/人脸注册/人脸更新/人脸搜索接口中使用SNAP参数，若为普通摄像头及混合场景模式，使用COMMON参数即可

参数	必选	类型	说明
image_spec	否	string	图片规格服务会对不同规格的图片采用不同的图片处理方式 COMMON: 通用图片规格默认的处理方式(如无适应的图片规格则使用此参数) SNAP: 从人脸抓拍机得到的抓拍图适用于小图片+单人脸的情况默认COMMON

请求示例

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

返回结果

字段	必选	类型	说明
log_id	是	uint64	请求标识码，随机数，唯一
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 人脸列表

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

请求路径

/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

请求示例

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

返回结果

字段	必选	类型	说明
face_list	是	array	人脸信息列表
+face_token	是	string	人脸标志
+ctime	是	string	人脸创建时间

返回示例

  {
      "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"
              },
              {
                  "face_token": "fid2",
                  "ctime": "2018-01-01 10:00:00"
              }
          ]
      }
  }

2.2.4 删除人脸

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

请求路径

/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判断是否成功如失败则查看error_msg获得具体错误信息

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

2.3 用户管理接口

2.3.1 复制用户

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

请求路径

/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信息和用户所属的组)

请求路径

/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 用户列表

获取用户组中的用户列表

请求路径

/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 创建用户组

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

请求路径

/face-api/v3/group/add

URL请求参数

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

Header：

参数	值
Content-Type	application/json

Body请求参数

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

请求示例
```
{
    "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 用户组列表

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

请求路径

/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

返回示例

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

2.4.3 删除用户组

删除用户组下所有的用户信息及人脸信息 如果组不存在则返回错误 注：使用删除组接口前需要先绑定定时脚本

#组删除脚本(部署目录如果不是`/home/work`, 记得修改到部署目录下)
*/10 * * * * cd /home/work/odp && ./hhvm/bin/hhvm app/face-api/script/DeleteGroup.php

路径

/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
}

2.4.4 查询人脸组数量

请求路径: /face-api/facehub/statapp

Header：

参数	值
Content-Type	application/json

Body请求参数

请求参数	类型	说明
op_app_id_list	string	appid

返回结果

{	
    "appid1": {	
        "group_num": 1	
}

批量获取组统计信息

请求路径：/face-api/facehub/statgroup

Header：

参数	值
Content-Type	application/json

Body请求参数

请求参数	类型	说明
op_app_id	string	appid标识
group_id_list	string	groupid列表多个按`,`分隔限制20个

返回结果

{	
    "gid1": {	
        "user_num": 3,	
        "face_num": 5,	
        "ctime": "2017-11-30 00:00:00",	
        "utime": "2017-11-30 12:00:00" 	
    },	
    "gid2": {	
        "user_num": 3,	
        "face_num": 5,	
        "ctime": "2017-11-30 00:00:00",	
        "utime": "2017-11-30 12:00:00"	
    }	
}

2.5 人脸库管理接口

2.5.1 创建人脸库（APPID）

人脸识别私有化服务中没有单独创建人脸库（Appid）的接口，如果需要创建人脸库，可以直接调用创建人脸组接口实现。
创建方式为：在“创建用户组”接口中可以自定义一个Appid，当组创建成功后，此Appid即可生效。请参考「创建用户组」接口文档。

系统会默认生成一个default的人脸库Appid。

2.5.2 查询appid列表

列出所有的appid

请求路径 /face-api/v3/app/list
请求参数：无
返回结果

字段	必选	类型	说明
app_id_list	是	array	appid

返回示例

{
    "error_code": 0,
    "error_msg": "SUCCESS",
    "log_id": 774558169,
    "timestamp": 1559027574,
    "cached": 0,
    "result": {
        "app_id_list": [
            "516978270",
            "516978277",
            "516978100"
        ]
    }
}

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服务实例数超限	请将运行实例数控制在授权数量内

更新记录

错误码