智能多媒体服务> API 文档> 人脸核验>功能接口>人脸检测

人脸检测

最近更新时间: 2023年04月19日 11:14:03

接口说明

检测单张图片中的人脸信息

请求

请求地址

名称	值
HTTP URL	`https://face-detect.qiniuapi.com/v2/facedetect`
HTTP Method	POST

请求头

名称	必填	说明
Host	是	固定值face-detect.qiniuapi.com
Authorization	是	该参数应严格按照管理凭证格式进行填充,否则会返回 401 错误码。一个合法的 Authorization 值应类似于:Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7...
Content-Type	是	固定值application/json

请求参数

字段	必填	类型	说明
image	否	string	图片信息(总数据大小应小于10M,图片尺寸在1920x1080以下),图片上传方式根据image_type来判断。两张图片通过json格式上传,格式参考表格下方示例
image_type	否	string	图片类型 BASE64:图片的base64值,base64编码后的图片数据,编码后的图片大小不超过2M; URL:图片的 URL地址( 可能由于网络等原因导致下载图片时间过长); FACE_TOKEN: 人脸图片的唯一标识,调用人脸检测接口时,会为每个人脸图片赋予一个唯一的FACE_TOKEN,同一张图片多次检测得到的FACE_TOKEN是同一个。
face_field	否	string	包括`age,expression,face_shape,gender,glasses,landmark,landmark150,quality,eye_status,emotion,face_type,mask,spoofing`信息逗号分隔. 默认只返回`face_token、人脸框、概率和旋转角度`
max_face_num	否	number	最多处理人脸的数目,默认值为1,根据人脸检测排序类型检测图片中排序第一的人脸(默认为人脸面积最大的人脸),最大值120
face_type	否	string	人脸的类型 LIVE:表示生活照:通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等, IDCARD:表示身份证芯片照:二代身份证内置芯片中的人像照片, WATERMARK:表示带水印证件照:一般为带水印的小图,如公安网小图 CERT:表示证件照片:如拍摄的身份证、工卡、护照、学生证等证件图片默认`LIVE`
liveness_control	否	string	活体检测控制 NONE: 不进行控制 LOW:较低的活体要求(高通过率低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率低通过率) 默认 `NONE` 若活体检测结果不满足要求,则返回结果中会提示活体检测失败
face_sort_type	否	number	人脸检测排序类型 0:代表检测出的人脸按照人脸面积从大到小排列 1:代表检测出的人脸按照距离图片中心从近到远排列默认为0
display_corp_image	否	number	是否显示检测人脸的裁剪图base64值 0:不显示(默认) 1:显示当取值为1时,max_face_num字段的取值上限按5计算,即最多可返回5张人脸的裁剪图

请求示例

POST /v2/facedetect
Host: face-detect.qiniuapi.com
Authorization: Qiniu token
Content-Type: application/json
{
 "image": "sfasq35sadvsvqwr5q...",
 "image_type": "BASE64",
 "face_type": "LIVE",
 "liveness_control": "HIGH"
}

响应

响应头

名称	必填	说明
Content-Type	是	固定值application/json

响应参数

字段	必填	类型	说明
error_code	否	number	错误码
error_msg	否	string	错误信息
log_id	否	number	请求ID
result	否	Object detect_result	请求结果

其中,detect_result 参数

字段	必填	类型	说明
face_num	否	number	检测到的图片中的人脸数量
face_list	否	[]Object faces	人脸信息列表,具体包含的参数参考下面的列表。

其中,faces 参数

字段	必填	类型	说明
face_token	否	string	人脸图片的唯一标识
location	否	Object face_location	人脸在图片中的位置
corp_image_base64	否	string	检测人脸框的人脸图片base64值
face_probability	否	number	人脸置信度,范围【0~1】,代表这是一张人脸的概率,0最小、1最大。其中返回0或1时,数据类型为Integer
angle	否	Object face_angle	人脸旋转角度参数
age	否	number	年龄 ,当face_field包含age时返回
expression	否	Object face_expression	表情,当 face_field包含expression时返回
face_shape	否	Object face_shape	脸型,当face_field包含face_shape时返回
gender	否	Object face_gender	性别,face_field包含gender时返回
glasses	否	Object face_glasses	是否带眼镜,face_field包含glasses时返回
eye_status	否	Object face_eye_status	双眼状态(睁开/闭合) face_field包含eye_status时返回
emotion	否	Object face_emotion	情绪 face_field包含emotion时返回
face_type	否	Object face_type	真实人脸/卡通人脸 face_field包含face_type时返回
mask	否	Object face_mask	口罩识别 face_field包含mask时返回
landmark	否	[]Object landmark_points	4个关键点位置,左眼中心、右眼中心、鼻尖、嘴中心。face_field包含landmark时返回
landmark72	否	[]Object landmark_points	72个特征点位置 face_field包含landmark时返回
landmark150	否	[]Object landmark_points	150个特征点位置 face_field包含landmark150时返回
quality	否	Object face_quality	人脸质量信息。face_field包含quality时返回
spoofing	否	number	判断图片是否为合成图

其中,face_location 参数

字段	必填	类型	说明
left	否	number	人脸区域离左边界的距离
top	否	number	人脸区域离上边界的距离
width	否	number	人脸区域的宽度
height	否	number	人脸区域的高度
rotation	否	number	人脸框相对于竖直方向的顺时针旋转角,[-180,180]

其中,face_angle 参数

字段	必填	类型	说明
yaw	否	number	三维旋转之左右旋转角[-90(左), 90(右)]
pitch	否	number	三维旋转之俯仰角度[-90(上), 90(下)]
roll	否	number	平面内旋转角[-180(逆时针), 180(顺时针)]

其中,face_expression 参数

字段	必填	类型	说明
type	否	string	none:不笑;smile:微笑;laugh:大笑
probability	否	number	表情置信度,范围【0~1】,0最小、1最大。

其中,face_shape 参数

字段	必填	类型	说明
type	否	string	square: 正方形 triangle:三角形 oval: 椭圆 heart: 心形 round: 圆形
probability	否	number	置信度,范围【0~1】,0最小、1最大。

其中,face_gender 参数

字段	必填	类型	说明
type	否	string	male:男性 female:女性
probability	否	number	置信度,范围【0~1】,0最小、1最大。

其中,face_glasses 参数

字段	必填	类型	说明
type	否	string	none:无眼镜,common:普通眼镜,sun:墨镜
probability	否	number	置信度,范围【0~1】,0最小、1最大。

其中,face_eye_status 参数

字段	必填	类型	说明
left_eye	否	number	左眼状态 [0,1]取值,越接近0闭合的可能性越大
right_eye	否	number	右眼状态 [0,1]取值,越接近0闭合的可能性越大

其中,face_emotion 参数

字段	必填	类型	说明
type	否	string	angry:愤怒 disgust:厌恶 fear:恐惧 happy:高兴 sad:伤心 surprise:惊讶 neutral:无表情 pouty: 撅嘴 grimace:鬼脸
probability	否	number	置信度,范围【0~1】,0最小、1最大。

其中,face_type 参数

字段	必填	类型	说明
type	否	string	human: 真实人脸 cartoon: 卡通人脸
probability	否	number	置信度,范围【0~1】,0最小、1最大。

其中,face_mask 参数

字段	必填	类型	说明
type	否	number	没戴口罩/戴口罩取值0或1 0代表没戴口罩 1 代表戴口罩
probability	否	number	置信度,范围【0~1】,0最小、1最大。

其中,landmark_points 参数

字段	必填	类型	说明
x	否	number
y	否	number

其中,face_quality 参数

字段	必填	类型	说明
occlusion	否	Object face_quality_occlusion	人脸各部分遮挡的概率,范围[0~1],0表示完整,1表示不完整
blur	否	number	人脸模糊程度,范围[0~1],0表示清晰,1表示模糊
illumination	否	number	取值范围在[0~255], 表示脸部区域的光照程度越大表示光照越好
completeness	否	number	人脸完整度,0或1, 0为人脸溢出图像边界,1为人脸都在图像边界内

其中,face_quality_occlusion 参数

字段	必填	类型	说明
left_eye	否	number	左眼遮挡比例,[0-1] ,1表示完全遮挡
right_eye	否	number	右眼遮挡比例,[0-1] ,1表示完全遮挡
nose	否	number	鼻子遮挡比例,[0-1] ,1表示完全遮挡
mouth	否	number	嘴遮挡比例,[0-1] ,1表示完全遮挡
left_cheek	否	number	左脸颊遮挡比例,[0-1] ,1表示完全遮挡
right_cheek	否	number	右脸颊遮挡比例,[0-1] ,1表示完全遮挡
chin	否	number	下巴遮挡比例,[0-1] ,1表示完全遮挡

响应示例

200 
Content-Type: application/json
{
 "error_code": 0,
 "error_msg": "SUCCESS",
 "log_id": 587756642,
 "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": 161.74819946289,
 "y": 163.30244445801
 }
 ],
 "landmark72": [
 {
 "x": 161.74819946289,
 "y": 163.30244445801
 }
 ],
 "age": 29.298097610474,
 "expression": {
 "type": "smile",
 "probability": 0.5543018579483
 },
 "gender": {
 "type": "male",
 "probability": 0.99979132413864
 },
 "glasses": {
 "type": "sun",
 "probability": 0.99999964237213
 },
 "face_shape": {
 "type": "triangle",
 "probability": 0.5543018579483
 },
 "quality": {
 "occlusion": {
 "left_eye": 0,
 "right_eye": 0,
 "nose": 0,
 "mouth": 0,
 "left_cheek": 0,
 "right_cheek": 0,
 "chin_contour": 0
 },
 "blur": 0,
 "illumination": 114,
 "completeness": 1
 }
 }
 ]
 }
}

以上内容是否对您有帮助?

文档反馈 (如有产品使用问题,请提交工单)