人脸检测与属性分析
百度 官方文档
检测图中的人脸,并为人脸标记出边框。检测出人脸后,可对人脸进行分析,获得眼、口、鼻轮廓等150个关键点定位,准确识别多种人脸属性,如性别,年龄,表情等信息。该技术可适应大角度侧脸,遮挡,模糊,表情变化等各种实际环境
基本说明:
接口地址:https://aip.baidubce.com/rest/2.0/face/v3/detect
返回格式:json
请求方式:post
请求示例:https://aip.baidubce.com/rest/2.0/face/v3/detect?access_token=test
请求参数说明:
名称 类型 必填 说明
image string 必填 图片信息(总数据大小应小于10M),图片上传方式根据image_type来判断
image_type string 必填 图片类型
BASE64:图片的base64值,base64编码后的图片数据,编码后的图片大小不超过2M;
URL:图片的 URL地址( 可能由于网络等原因导致下载图片时间过长);
FACE_TOKEN: 人脸图片的唯一标识,调用人脸检测接口时,会为每个人脸图片赋予一个唯一的FACE_TOKEN,同一张图片多次检测得到的FACE_TOKEN是同一个。
face_field string 选填 包括age,beauty,expression,face_shape,gender,glasses,landmark,landmark72,landmark150,race,quality,eye_status,emotion,face_type信息
逗号分隔. 默认只返回face_token、人脸框、概率和旋转角度
max_face_num uint32 选填 最多处理人脸的数目,默认值为1,仅检测图片中面积最大的那个人脸;最大值10,检测图片中面积最大的几张人脸。
face_type string 选填 人脸的类型
LIVE表示生活照:通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等
IDCARD表示身份证芯片照:二代身份证内置芯片中的人像照片
WATERMARK表示带水印证件照:一般为带水印的小图,如公安网小图
CERT表示证件照片:如拍摄的身份证、工卡、护照、学生证等证件图片
默认LIVE
返回参数说明:
名称 类型 说明
face_num 检测到的图片中的人脸数量
face_list 人脸信息列表,具体包含的参数参考下面的列表。
+face_token 人脸图片的唯一标识
+location 人脸在图片中的位置
++left 人脸区域离左边界的距离
++top 人脸区域离上边界的距离
++width 人脸区域的宽度
++height 人脸区域的高度
++rotation 人脸框相对于竖直方向的顺时针旋转角,[-180,180]
+face_probability 人脸置信度,范围【0~1】,代表这是一张人脸的概率,0最小、1最大。
+angel 人脸旋转角度参数
++yaw 三维旋转之左右旋转角[-90(左), 90(右)]
++pitch 三维旋转之俯仰角度[-90(上), 90(下)]
++roll 平面内旋转角[-180(逆时针), 180(顺时针)]
+age 年龄 ,当<strong>face_field包含age时返回</strong>
+beauty 美丑打分,范围0-100,越大表示越美。当<strong>face_fields包含beauty时返回</strong>
+expression 表情,当 <strong>face_field包含expression时返回</strong>
++type <strong>none</strong>:不笑;<strong>smile</strong>:微笑;<strong>laugh</strong>:大笑
++probability 表情置信度,范围【0~1】,0最小、1最大。
+face_shape 脸型,当<strong>face_field包含face_shape时返回</strong>
++type <strong>square</strong>: 正方形 <strong>triangle</strong>:三角形 <strong>oval</strong>: 椭圆 <strong>heart</strong>: 心形 <strong>round</strong>: 圆形
++probability 置信度,范围【0~1】,代表这是人脸形状判断正确的概率,0最小、1最大。
+gender 性别,<strong>face_field包含gender时返回</strong>
++type male:<strong>男性</strong> female:<strong>女性</strong>
++probability 性别置信度,范围【0~1】,0代表概率最小、1代表最大。
+glasses 是否带眼镜,<strong>face_field包含glasses时返回</strong>
++type <strong>none</strong>:无眼镜,<strong>common</strong>:普通眼镜,<strong>sun</strong>:墨镜
++probability 眼镜置信度,范围【0~1】,0代表概率最小、1代表最大。
+eye_status 双眼状态(睁开/闭合) <strong>face_field包含eye_status时返回</strong>
++left_eye 左眼状态 [0,1]取值,越接近0闭合的可能性越大
++right_eye 右眼状态 [0,1]取值,越接近0闭合的可能性越大
+emotion 情绪 <strong>face_field包含emotion时返回</strong>
++type <strong>angry</strong>:愤怒 <strong>disgust</strong>:厌恶 <strong>fear</strong>:恐惧 <strong>happy</strong>:高兴<br><strong>sad</strong>:伤心 <strong>surprise</strong>:惊讶 <strong>neutral</strong>:无情绪
++probability 情绪置信度,范围0~1
+race 人种 <strong>face_field包含race时返回</strong>
++type <strong>yellow</strong>: 黄种人 <strong>white</strong>: 白种人 <strong>black</strong>:黑种人 <strong>arabs</strong>: <strong>阿拉伯人</strong>
++probability 人种置信度,范围【0~1】,0代表概率最小、1代表最大。
+face_type 真实人脸/卡通人脸 <strong>face_field包含face_type时返回</strong>
++type <strong>human</strong>: 真实人脸 <strong>cartoon</strong>: 卡通人脸
++probability 人脸类型判断正确的置信度,范围【0~1】,0代表概率最小、1代表最大。
+landmark 4个关键点位置,左眼中心、右眼中心、鼻尖、嘴中心。<strong>face_field包含landmark时返回</strong>
+landmark72 72个特征点位置 <strong>face_field包含landmark72时返回</strong>
+landmark150 150个特征点位置 <strong>face_field包含landmark150时返回</strong>
+quality 人脸质量信息。<strong>face_field包含quality时返回</strong>
++occlusion 人脸各部分遮挡的概率,范围[0~1],0表示完整,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 下巴遮挡比例,,[0-1] , 1表示完全遮挡
++blur 人脸模糊程度,范围[0~1],0表示清晰,1表示模糊
++illumination 取值范围在[0~255], 表示脸部区域的光照程度 越大表示光照越好
++completeness 人脸完整度,0或1, 0为人脸溢出图像边界,1为人脸都在图像边界内
JSON返回示例:
{
	"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": 115.86531066895,
				"y": 170.0546875
			},
			...
		],
		"age": 29.298097610474,
		"beauty": 55.128883361816,
		"expression": {
			"type": "smile",
			"probability": 0.5543018579483
		},
		"gender": {
			"type": "male",
			"probability": 0.99979132413864
		},
		"glasses": {
			"type": "sun",
			"probability": 0.99999964237213
		},
		"race": {
			"type": "yellow",
			"probability": 0.99999976158142
		},
		"face_shape": {
			"type": "triangle",
			"probability": 0.5543018579483
		}
		"quality": {
			"occlusion": {
				"left_eye": 0,
				"right_eye": 0,
				"nose": 0,
				"mouth": 0,
				"left_cheek": 0.0064102564938366,
				"right_cheek": 0.0057411273010075,
				"chin": 0
			},
			"blur": 1.1886881756684e-10,
			"illumination": 141,
			"completeness": 1
		}
	}]
}
服务级错误码参照
错误码 说明
4 集群超限额
6 没有接口权限
17 每天流量超限额
18 QPS超限额
19 请求总量超限额
100 无效的access_token参数
110 Access Token失效
111 Access token过期
222001 必要参数未传入
222002 参数格式错误
222003 参数格式错误
222004 参数格式错误
222005 参数格式错误
222006 参数格式错误
222007 参数格式错误
222008 参数格式错误
222009 参数格式错误
222010 参数格式错误
222011 参数格式错误
222012 参数格式错误
222013 参数格式错误
222014 参数格式错误
222015 参数格式错误
222016 参数格式错误
222017 参数格式错误
222018 参数格式错误
222019 参数格式错误
222020 参数格式错误
222021 参数格式错误
222022 参数格式错误
222023 参数格式错误
222024 参数格式错误
222025 参数格式错误
222026 参数格式错误
222027 验证码长度错误<br>(最小值大于最大值)
222028 参数格式错误
222029 参数格式错误
222030 参数格式错误
222200 该接口需使用<br>application/json的<br>格式进行请求
222201 服务端请求失败
222202 图片中没有人脸
222203 无法解析人脸
222204 从图片的url下载<br>图片失败
222205 服务端请求失败
222206 服务端请求失败
222207 未找到匹配的用户
222208 图片的数量错误
222209 face token不存在
222210 人脸库中用户下的人脸数目超过限制
222300 人脸图片添加失败
222301 获取人脸图片失败
222302 服务端请求失败
222303 获取人脸图片失败
223100 操作的用户组不存在
223101 该用户组已存在
223102 该用户已存在
223103 找不到该用户
223104 group_list包含组<br>数量过多
223105 该人脸已存在
223106 该人脸不存在
223110 uid_list包含数量过多
223111 目标用户组不存在
223112 quality_conf格式不正确
223113 人脸有被遮挡
223114 人脸模糊
223115 人脸光照不好
223116 人脸不完整
223117 app_list包含app数量<br>过多
223118 质量控制项错误
223119 活体控制项错误
223120 活体检测未通过
223121 质量检测未通过 左眼<br>遮挡程度过高
223122 质量检测未通过 右眼<br>遮挡程度过高
223123 质量检测未通过 左脸<br>遮挡程度过高
223124 质量检测未通过 右脸<br>遮挡程度过高
223125 质量检测未通过 下巴遮挡程度过高
223126 质量检测未通过 鼻子遮挡程度过高
223127 质量检测未通过 嘴巴<br>遮挡程度过高
222901 参数校验初始化失败
222902 参数校验初始化失败
222903 参数校验初始化失败
222904 参数校验初始化失败
222905 接口初始化失败
222906 接口初始化失败
222907 缓存处理失败
222908 缓存处理失败
222909 缓存处理失败
222910 数据存储处理失败
222911 数据存储处理失败
222912 数据存储处理失败
222913 接口初始化失败
222914 接口初始化失败
222915 后端服务连接失败
222916 后端服务连接失败
222304 图片尺寸太大
223128 正在清理该用户组的数据
222361 公安服务连接失败
完整教学代码示例
人脸检测与属性分析
curl -i -k 'https://aip.baidubce.com/rest/2.0/face/v3/detect?access_token=【调用鉴权接口获取的token】' --data '{"image":"027d8308a2ec665acb1bdf63e513bcb9","image_type":"FACE_TOKEN","face_field":"faceshape,facetype"}' -H 'Content-Type:application/json; charset=UTF-8'
<?php
/**
 * 发起http post请求(REST API), 并获取REST请求的结果
 * @param string $url
 * @param string $param
 * @return - http response body if succeeds, else false.
 */
function request_post($url = '', $param = '')
{
    if (empty($url) || empty($param)) {
        return false;
    }

    $postUrl = $url;
    $curlPost = $param;
    // 初始化curl
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, $postUrl);
    curl_setopt($curl, CURLOPT_HEADER, 0);
    // 要求结果为字符串且输出到屏幕上
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
    // post提交方式
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $curlPost);
    // 运行curl
    $data = curl_exec($curl);
    curl_close($curl);

    return $data;
}

$token = '[调用鉴权接口获取的token]';
$url = 'https://aip.baidubce.com/rest/2.0/face/v3/detect?access_token=' . $token;
$bodys = "{\"image\":\"027d8308a2ec665acb1bdf63e513bcb9\",\"image_type\":\"FACE_TOKEN\",\"face_field\":\"faceshape,facetype\"}"
$res = request_post($url, $bodys);
var_dump($res);
package com.baidu.ai.aip;

import com.baidu.ai.aip.utils.HttpUtil;
import com.baidu.ai.aip.utils.GsonUtils;

import java.util.*;

/**
* 人脸检测与属性分析
*/
public class FaceDetect {

    /**
    * 重要提示代码中所需工具类
    * FileUtil,Base64Util,HttpUtil,GsonUtils请从
    * https://ai.baidu.com/file/658A35ABAB2D404FBF903F64D47C1F72
    * https://ai.baidu.com/file/C8D81F3301E24D2892968F09AE1AD6E2
    * https://ai.baidu.com/file/544D677F5D4E4F17B4122FBD60DB82B3
    * https://ai.baidu.com/file/470B3ACCA3FE43788B5A963BF0B625F3
    * 下载
    */
    public static String detect() {
        // 请求url
        String url = "https://aip.baidubce.com/rest/2.0/face/v3/detect";
        try {
            Map<String, Object> map = new HashMap<>();
            map.put("image", "027d8308a2ec665acb1bdf63e513bcb9");
            map.put("face_field", "faceshape,facetype");
            map.put("image_type", "FACE_TOKEN");

            String param = GsonUtils.toJson(map);

            // 注意这里仅为了简化编码每一次请求都去获取access_token,线上环境access_token有过期时间, 客户端可自行缓存,过期后重新获取。
            String accessToken = "[调用鉴权接口获取的token]";

            String result = HttpUtil.post(url, accessToken, "application/json", param);
            System.out.println(result);
            return result;
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }

    public static void main(String[] args) {
        FaceDetect.detect();
    }
}
# encoding:utf-8
import urllib
import urllib2

'''
人脸检测与属性分析
'''

request_url = "https://aip.baidubce.com/rest/2.0/face/v3/detect"


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

access_token = '[调用鉴权接口获取的token]'
request_url = request_url + "?access_token=" + access_token
request = urllib2.Request(url=request_url, data=params)
request.add_header('Content-Type', 'application/json')
response = urllib2.urlopen(request)
content = response.read()
if content:
    print content
#include <iostream>
#include <curl/curl.h>

// libcurl库下载链接:https://curl.haxx.se/download.html
// jsoncpp库下载链接:https://github.com/open-source-parsers/jsoncpp/
const static std::string request_url = "https://aip.baidubce.com/rest/2.0/face/v3/detect";
static std::string detect_result;
/**
 * curl发送http请求调用的回调函数,回调函数中对返回的json格式的body进行了解析,解析结果储存在全局的静态变量当中
 * @param 参数定义见libcurl文档
 * @return 返回值定义见libcurl文档
 */
static size_t callback(void *ptr, size_t size, size_t nmemb, void *stream) {
    // 获取到的body存放在ptr中,先将其转换为string格式
    detect_result = std::string((char *) ptr, size * nmemb);
    return size * nmemb;
}
/**
 * 人脸检测与属性分析
 * @return 调用成功返回0,发生错误返回其他错误码
 */
int detect(std::string &json_result, const std::string &access_token) {
    std::string url = request_url + "?access_token=" + access_token;
    CURL *curl = NULL;
    CURLcode result_code;
    int is_success;
    curl = curl_easy_init();
    if (curl) {
        curl_easy_setopt(curl, CURLOPT_URL, url.data());
        curl_easy_setopt(curl, CURLOPT_POST, 1);
        curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "Content-Type:application/json;charset=UTF-8");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"image\":\"027d8308a2ec665acb1bdf63e513bcb9\",\"image_type\":\"FACE_TOKEN\",\"face_field\":\"faceshape,facetype\"}");
        result_code = curl_easy_perform(curl);
        if (result_code != CURLE_OK) {
            fprintf(stderr, "curl_easy_perform() failed: %s
",
                    curl_easy_strerror(result_code));
            is_success = 1;
            return is_success;
        }
        json_result = detect_result;
        curl_easy_cleanup(curl);
        is_success = 0;
    } else {
        fprintf(stderr, "curl_easy_init() failed.");
        is_success = 1;
    }
    return is_success;
}
using System;
using System.IO;
using System.Net;
using System.Text;
using System.Web;

namespace com.baidu.ai
{
    public class FaceDetect
    {
        // 人脸检测与属性分析
        public static string detect()
        {
            string token = "[调用鉴权接口获取的token]";
            string host = "https://aip.baidubce.com/rest/2.0/face/v3/detect?access_token=" + token;
            Encoding encoding = Encoding.Default;
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(host);
            request.Method = "post";
            request.KeepAlive = true;
            String str = "{\"image\":\"027d8308a2ec665acb1bdf63e513bcb9\",\"image_type\":\"FACE_TOKEN\",\"face_field\":\"faceshape,facetype\"}";
            byte[] buffer = encoding.GetBytes(str);
            request.ContentLength = buffer.Length;
            request.GetRequestStream().Write(buffer, 0, buffer.Length);
            HttpWebResponse response = (HttpWebResponse)request.GetResponse();
            StreamReader reader = new StreamReader(response.GetResponseStream(), Encoding.Default);
            string result = reader.ReadToEnd();
            Console.WriteLine("人脸检测与属性分析:");
            Console.WriteLine(result);
            return result;
        }
    }
}