人脸检测与属性分析
能力介绍
接口能力
本文档为人脸识别V3接口使用文档,人脸识别V3接口能识别出人脸位置、人脸关键点、人脸属性值、人脸质量信息。
- 人脸检测:检测图片中的人脸并标记出位置信息。
- 人脸关键点:展示人脸的核心关键点信息,及150个关键点信息。
- 人脸属性值:展示人脸属性信息,如年龄、性别等。
- 人脸质量信息:返回人脸各部分的遮挡、光照、模糊、完整度、置信度等信息。
业务应用
典型应用场景:如人脸属性分析,基于人脸关键点的加工分析,人脸营销活动等。
说明:检测响应速度,与图片中人脸数量相关,人脸数量较多时响应时间会有些许延长。
质量检测
如果需要判断一张图片中的人脸,是否符合后续识别或者对比的条件,可以使用此接口,在请求时在face_field
参数中请求quality
。基于返回结果quality
中,以下字段及对应阈值,进行质量检测的判断,以保证人脸质量符合后续业务操作要求。
指标 | 字段与解释 | 推荐数值界限 |
---|---|---|
遮挡范围 | occlusion,取值范围[0~1],0为无遮挡,1是完全遮挡 含有多个具体子字段,表示脸部多个部位 通常用作判断头发、墨镜、口罩等遮挡 |
left_eye : 0.6, #左眼被遮挡的阈值 right_eye : 0.6, #右眼被遮挡的阈值 nose : 0.7, #鼻子被遮挡的阈值 mouth : 0.7, #嘴巴被遮挡的阈值 left_cheek : 0.8, #左脸颊被遮挡的阈值 right_cheek : 0.8, #右脸颊被遮挡的阈值 chin_contour : 0.6, #下巴被遮挡阈值 |
模糊度范围 | blur,取值范围[0~1],0是最清晰,1是最模糊 | 小于0.7 |
光照范围 | illumination,取值范围[0~255] 脸部光照的灰度值,0表示光照不好 以及对应客户端SDK中,YUV的Y分量 |
大于40 |
姿态角度 | Pitch:三维旋转之俯仰角度[-90(上), 90(下)] Roll:平面内旋转角[-180(逆时针), 180(顺时针)] Yaw:三维旋转之左右旋转角[-90(左), 90(右)] |
分别小于20度 |
人脸完整度 | completeness(0或1),0为人脸溢出图像边界, 1为人脸都在图像边界内 |
视业务逻辑判断 |
人脸大小 | 人脸部分的大小 建议长宽像素值范围:80*80~200*200 |
人脸部分不小于100*100像素 |
在线调试
您可以在 示例代码中心 中调试该接口,可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。
调用方式
请求URL数据格式
向API服务地址使用POST发送请求,必须在URL中带上参数access_token
,可通过后台的API Key和Secret Key生成,具体方式请参考“Access Token获取”。
示例代码
1#!/bin/bash
2curl -i -k 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=【应用的AK】&client_secret=【应用的SK】'
1<?php
2function request_post($url = '', $param = '') {
3 if (empty($url) || empty($param)) {
4 return false;
5 }
6
7 $postUrl = $url;
8 $curlPost = $param;
9 $curl = curl_init();//初始化curl
10 curl_setopt($curl, CURLOPT_URL,$postUrl);//抓取指定网页
11 curl_setopt($curl, CURLOPT_HEADER, 0);//设置header
12 curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);//要求结果为字符串且输出到屏幕上
13 curl_setopt($curl, CURLOPT_POST, 1);//post提交方式
14 curl_setopt($curl, CURLOPT_POSTFIELDS, $curlPost);
15 $data = curl_exec($curl);//运行curl
16 curl_close($curl);
17
18 return $data;
19 }
20
21 $url = 'https://aip.baidubce.com/oauth/2.0/token';
22 $post_data['grant_type'] = 'client_credentials';
23 $post_data['client_id'] = '你的 Api Key';
24 $post_data['client_secret'] = '你的 Secret Key';
25 $o = "";
26 foreach ( $post_data as $k => $v )
27 {
28 $o.= "$k=" . urlencode( $v ). "&" ;
29 }
30 $post_data = substr($o,0,-1);
31
32 $res = request_post($url, $post_data);
33
34 var_dump($res);
35
36?>
1package com.baidu.ai.aip.auth;
2
3import org.json.JSONObject;
4
5import java.io.BufferedReader;
6import java.io.InputStreamReader;
7import java.net.HttpURLConnection;
8import java.net.URL;
9import java.util.List;
10import java.util.Map;
11
12/**
13 * 获取token类
14 */
15public class AuthService {
16
17 /**
18 * 获取权限token
19 * @return 返回示例:
20 * {
21 * "access_token": "24.460da4889caad24cccdb1fea17221975.2592000.1491995545.282335-1234567",
22 * "expires_in": 2592000
23 * }
24 */
25 public static String getAuth() {
26 // 官网获取的 API Key 更新为你注册的
27 String clientId = "百度云应用的AK";
28 // 官网获取的 Secret Key 更新为你注册的
29 String clientSecret = "百度云应用的SK";
30 return getAuth(clientId, clientSecret);
31 }
32
33 /**
34 * 获取API访问token
35 * 该token有一定的有效期,需要自行管理,当失效时需重新获取.
36 * @param ak - 百度云官网获取的 API Key
37 * @param sk - 百度云官网获取的 Securet Key
38 * @return assess_token 示例:
39 * "24.460da4889caad24cccdb1fea17221975.2592000.1491995545.282335-1234567"
40 */
41 public static String getAuth(String ak, String sk) {
42 // 获取token地址
43 String authHost = "https://aip.baidubce.com/oauth/2.0/token?";
44 String getAccessTokenUrl = authHost
45 // 1. grant_type为固定参数
46 + "grant_type=client_credentials"
47 // 2. 官网获取的 API Key
48 + "&client_id=" + ak
49 // 3. 官网获取的 Secret Key
50 + "&client_secret=" + sk;
51 try {
52 URL realUrl = new URL(getAccessTokenUrl);
53 // 打开和URL之间的连接
54 HttpURLConnection connection = (HttpURLConnection) realUrl.openConnection();
55 connection.setRequestMethod("GET");
56 connection.connect();
57 // 获取所有响应头字段
58 Map<String, List<String>> map = connection.getHeaderFields();
59 // 遍历所有的响应头字段
60 for (String key : map.keySet()) {
61 System.err.println(key + "--->" + map.get(key));
62 }
63 // 定义 BufferedReader输入流来读取URL的响应
64 BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
65 String result = "";
66 String line;
67 while ((line = in.readLine()) != null) {
68 result += line;
69 }
70 /**
71 * 返回结果示例
72 */
73 System.err.println("result:" + result);
74 JSONObject jsonObject = new JSONObject(result);
75 String access_token = jsonObject.getString("access_token");
76 return access_token;
77 } catch (Exception e) {
78 System.err.printf("获取token失败!");
79 e.printStackTrace(System.err);
80 }
81 return null;
82 }
83
84}
1# encoding:utf-8
2import requests
3
4# client_id 为官网获取的AK, client_secret 为官网获取的SK
5host = 'https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=【官网获取的AK】&client_secret=【官网获取的SK】'
6response = requests.get(host)
7if response:
8 print(response.json())
1#include <iostream>
2#include <curl/curl.h>
3#include <json/json.h>
4#include "access_token.h"
5// libcurl库下载链接:https://curl.haxx.se/download.html
6// jsoncpp库下载链接:https://github.com/open-source-parsers/jsoncpp/
7// 获取access_token所需要的url
8const std::string access_token_url = "https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials";
9// 回调函数获取到的access_token存放变量
10// static std::string access_token_result;
11/**
12 * curl发送http请求调用的回调函数,回调函数中对返回的json格式的body进行了解析,解析结果储存在result中
13 * @param 参数定义见libcurl库文档
14 * @return 返回值定义见libcurl库文档
15 */
16static size_t callback(void *ptr, size_t size, size_t nmemb, void *stream) {
17 // 获取到的body存放在ptr中,先将其转换为string格式
18 std::string s((char *) ptr, size * nmemb);
19 // 开始获取json中的access token项目
20 Json::Reader reader;
21 Json::Value root;
22 // 使用boost库解析json
23 reader.parse(s,root);
24 std::string* access_token_result = static_cast<std::string*>(stream);
25 *access_token_result = root["access_token"].asString();
26 return size * nmemb;
27}
28
29/**
30 * 用以获取access_token的函数,使用时需要先在百度云控制台申请相应功能的应用,获得对应的API Key和Secret Key
31 * @param access_token 获取得到的access token,调用函数时需传入该参数
32 * @param AK 应用的API key
33 * @param SK 应用的Secret key
34 * @return 返回0代表获取access token成功,其他返回值代表获取失败
35 */
36int get_access_token(std::string &access_token, const std::string &AK, const std::string &SK) {
37 CURL *curl;
38 CURLcode result_code;
39 int error_code = 0;
40 curl = curl_easy_init();
41 if (curl) {
42 std::string url = access_token_url + "&client_id=" + AK + "&client_secret=" + SK;
43 curl_easy_setopt(curl, CURLOPT_URL, url.data());
44 curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0);
45 curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0);
46 std::string access_token_result;
47 curl_easy_setopt(curl, CURLOPT_WRITEDATA, &access_token_result);
48 curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, callback);
49 result_code = curl_easy_perform(curl);
50 if (result_code != CURLE_OK) {
51 fprintf(stderr, "curl_easy_perform() failed: %s\n",
52 curl_easy_strerror(result_code));
53 return 1;
54 }
55 access_token = access_token_result;
56 curl_easy_cleanup(curl);
57 error_code = 0;
58 } else {
59 fprintf(stderr, "curl_easy_init() failed.");
60 error_code = 1;
61 }
62 return error_code;
63}
1using System;
2using System.Collections.Generic;
3using System.Net.Http;
4
5namespace com.baidu.ai
6{
7 public static class AccessToken
8
9 {
10 // 调用getAccessToken()获取的 access_token建议根据expires_in 时间 设置缓存
11 // 返回token示例
12 public static String TOKEN = "24.adda70c11b9786206253ddb70affdc46.2592000.1493524354.282335-1234567";
13
14 // 百度云中开通对应服务应用的 API Key 建议开通应用的时候多选服务
15 private static String clientId = "百度云应用的AK";
16 // 百度云中开通对应服务应用的 Secret Key
17 private static String clientSecret = "百度云应用的SK";
18
19 public static String getAccessToken() {
20 String authHost = "https://aip.baidubce.com/oauth/2.0/token";
21 HttpClient client = new HttpClient();
22 List<KeyValuePair<String, String>> paraList = new List<KeyValuePair<string, string>>();
23 paraList.Add(new KeyValuePair<string, string>("grant_type", "client_credentials"));
24 paraList.Add(new KeyValuePair<string, string>("client_id", clientId));
25 paraList.Add(new KeyValuePair<string, string>("client_secret", clientSecret));
26
27 HttpResponseMessage response = client.PostAsync(authHost, new FormUrlEncodedContent(paraList)).Result;
28 String result = response.Content.ReadAsStringAsync().Result;
29 Console.WriteLine(result);
30 return result;
31 }
32 }
33}
1var https = require('https');
2var qs = require('querystring');
3
4const param = qs.stringify({
5 'grant_type': 'client_credentials',
6 'client_id': '您的 Api Key',
7 'client_secret': '您的 Secret Key'
8});
9
10https.get(
11 {
12 hostname: 'aip.baidubce.com',
13 path: '/oauth/2.0/token?' + param,
14 agent: false
15 },
16 function (res) {
17 // 在标准输出中查看运行结果
18 res.pipe(process.stdout);
19 }
20);
注意:
access_token
的有效期为30天,切记需要每30天进行定期更换,或者每次请求都拉取新token;
例如此接口,使用HTTPS POST发送:
1https://aip.baidubce.com/rest/2.0/face/v3/detect?access_token=24.f9ba9c5341b67688ab4added8bc91dec.2592000.1485570332.282335-8574074
POST中Body的参数,按照下方请求参数说明选择即可。
提示:如果您为百度智能云老用户,正在使用其他非AI的服务,可以参考百度智能云AKSK鉴权方式发送请求,虽然请求方式和鉴权方法和本文所介绍的不同,但请求参数和返回结果一致。
请求说明
注意事项:
- 请求体格式化:Content-Type为
application/json
,通过json
格式化请求体。 - Base64编码:请求的图片需经过
Base64编码
,图片的base64编码指将图片数据编码成一串字符串,使用该字符串代替图像地址。您可以首先得到图片的二进制,然后用Base64格式编码即可。需要注意的是,图片的base64编码是不包含图片头的,如data:image/jpg;base64,
- 图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片
- 如图片中存在多个人脸(大于1),您想要使用此接口获取的多个face_token进行对比、入库、检索等操作,需要在调用接口时将face_field参数传入feature值。
请求示例
HTTP方法:POST
请求URL: https://aip.baidubce.com/rest/2.0/face/v3/detect
URL参数:
参数 | 值 |
---|---|
access_token | 通过API Key和Secret Key获取的access_token,参考“Access Token获取” |
Header:
参数 | 值 |
---|---|
Content-Type | application/json |
Body中放置请求参数,参数详情如下:
请求参数
参数 | 必选 | 类型 | 说明 |
---|---|---|---|
image | 是 | string | 图片信息(总数据大小应小于10M,分辨率应小于1920*1080),图片上传方式根据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,landmark150, quality,eye_status,emotion,face_type,mask,spoofing信息 逗号分隔. 默认只返回face_token、人脸框、概率和旋转角度 |
max_face_num | 否 | uint32 | 最多处理人脸的数目,默认值为1,根据人脸检测排序类型检测图片中排序第一的人脸(默认为人脸面积最大的人脸),最大值20 |
face_type | 否 | string | 人脸的类型 LIVE表示生活照:通常为手机、相机拍摄的人像图片、或从网络获取的人像图片等 IDCARD表示身份证芯片照:二代身份证内置芯片中的人像照片 WATERMARK表示带水印证件照:一般为带水印的小图,如公安网小图 CERT表示证件照片:如拍摄的身份证、工卡、护照、学生证等证件图片 默认LIVE |
liveness_control | 否 | string | 活体控制 检测结果中不符合要求的人脸会被过滤 NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认NONE |
face_sort_type | 否 | int | 人脸检测排序类型 0:代表检测出的人脸按照人脸面积从大到小排列 1:代表检测出的人脸按照距离图片中心从近到远排列 默认为0 |
display_corp_image | 否 | int | 是否显示检测人脸的裁剪图base64值 0:不显示(默认) 1:显示 当取值为1时,max_face_num字段的取值上限按5计算,即最多可返回5张人脸的裁剪图 |
说明:face_field参数,默认只返回人脸框、概率和旋转角度,age等更多属性,请在此参数中添加。
示例代码
提示一:使用示例代码前,请记得替换其中的示例Token、图片地址或Base64信息。
提示二:部分语言依赖的类或库,请在代码注释中查看下载地址。
1人脸检测与属性分析
2curl -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'
1<?php
2/**
3 * 发起http post请求(REST API), 并获取REST请求的结果
4 * @param string $url
5 * @param string $param
6 * @return - http response body if succeeds, else false.
7 */
8function request_post($url = '', $param = '')
9{
10 if (empty($url) || empty($param)) {
11 return false;
12 }
13
14 $postUrl = $url;
15 $curlPost = $param;
16 // 初始化curl
17 $curl = curl_init();
18 curl_setopt($curl, CURLOPT_URL, $postUrl);
19 curl_setopt($curl, CURLOPT_HEADER, 0);
20 // 要求结果为字符串且输出到屏幕上
21 curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
22 curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
23 // post提交方式
24 curl_setopt($curl, CURLOPT_POST, 1);
25 curl_setopt($curl, CURLOPT_POSTFIELDS, $curlPost);
26 // 运行curl
27 $data = curl_exec($curl);
28 curl_close($curl);
29
30 return $data;
31}
32
33$token = '[调用鉴权接口获取的token]';
34$url = 'https://aip.baidubce.com/rest/2.0/face/v3/detect?access_token=' . $token;
35$bodys = "{\"image\":\"027d8308a2ec665acb1bdf63e513bcb9\",\"image_type\":\"FACE_TOKEN\",\"face_field\":\"faceshape,facetype\"}"
36$res = request_post($url, $bodys);
37
38var_dump($res);
1package com.baidu.ai.aip;
2
3import com.baidu.ai.aip.utils.HttpUtil;
4import com.baidu.ai.aip.utils.GsonUtils;
5
6import java.util.*;
7
8/**
9* 人脸检测与属性分析
10*/
11public class FaceDetect {
12
13 /**
14 * 重要提示代码中所需工具类
15 * FileUtil,Base64Util,HttpUtil,GsonUtils请从
16 * https://ai.baidu.com/file/658A35ABAB2D404FBF903F64D47C1F72
17 * https://ai.baidu.com/file/C8D81F3301E24D2892968F09AE1AD6E2
18 * https://ai.baidu.com/file/544D677F5D4E4F17B4122FBD60DB82B3
19 * https://ai.baidu.com/file/470B3ACCA3FE43788B5A963BF0B625F3
20 * 下载
21 */
22 public static String faceDetect() {
23 // 请求url
24 String url = "https://aip.baidubce.com/rest/2.0/face/v3/detect";
25 try {
26 Map<String, Object> map = new HashMap<>();
27 map.put("image", "027d8308a2ec665acb1bdf63e513bcb9");
28 map.put("face_field", "faceshape,facetype");
29 map.put("image_type", "FACE_TOKEN");
30
31 String param = GsonUtils.toJson(map);
32
33 // 注意这里仅为了简化编码每一次请求都去获取access_token,线上环境access_token有过期时间, 客户端可自行缓存,过期后重新获取。
34 String accessToken = "[调用鉴权接口获取的token]";
35
36 String result = HttpUtil.post(url, accessToken, "application/json", param);
37 System.out.println(result);
38 return result;
39 } catch (Exception e) {
40 e.printStackTrace();
41 }
42 return null;
43 }
44
45 public static void main(String[] args) {
46 FaceDetect.faceDetect();
47 }
48}
1# encoding:utf-8
2
3import requests
4
5'''
6人脸检测与属性分析
7'''
8
9request_url = "https://aip.baidubce.com/rest/2.0/face/v3/detect"
10
11params = "{\"image\":\"027d8308a2ec665acb1bdf63e513bcb9\",\"image_type\":\"FACE_TOKEN\",\"face_field\":\"faceshape,facetype\"}"
12access_token = '[调用鉴权接口获取的token]'
13request_url = request_url + "?access_token=" + access_token
14headers = {'content-type': 'application/json'}
15response = requests.post(request_url, data=params, headers=headers)
16if response:
17 print (response.json())
1#include <iostream>
2#include <curl/curl.h>
3
4// libcurl库下载链接:https://curl.haxx.se/download.html
5// jsoncpp库下载链接:https://github.com/open-source-parsers/jsoncpp/
6const static std::string request_url = "https://aip.baidubce.com/rest/2.0/face/v3/detect";
7static std::string faceDetect_result;
8/**
9 * curl发送http请求调用的回调函数,回调函数中对返回的json格式的body进行了解析,解析结果储存在全局的静态变量当中
10 * @param 参数定义见libcurl文档
11 * @return 返回值定义见libcurl文档
12 */
13static size_t callback(void *ptr, size_t size, size_t nmemb, void *stream) {
14 // 获取到的body存放在ptr中,先将其转换为string格式
15 faceDetect_result = std::string((char *) ptr, size * nmemb);
16 return size * nmemb;
17}
18/**
19 * 人脸检测与属性分析
20 * @return 调用成功返回0,发生错误返回其他错误码
21 */
22int faceDetect(std::string &json_result, const std::string &access_token) {
23 std::string url = request_url + "?access_token=" + access_token;
24 CURL *curl = NULL;
25 CURLcode result_code;
26 int is_success;
27 curl = curl_easy_init();
28 if (curl) {
29 curl_easy_setopt(curl, CURLOPT_URL, url.data());
30 curl_easy_setopt(curl, CURLOPT_POST, 1);
31 curl_slist *headers = NULL;
32 headers = curl_slist_append(headers, "Content-Type:application/json;charset=UTF-8");
33 curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
34 curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"image\":\"027d8308a2ec665acb1bdf63e513bcb9\",\"image_type\":\"FACE_TOKEN\",\"face_field\":\"faceshape,facetype\"}");
35 result_code = curl_easy_perform(curl);
36 if (result_code != CURLE_OK) {
37 fprintf(stderr, "curl_easy_perform() failed: %s\n",
38 curl_easy_strerror(result_code));
39 is_success = 1;
40 return is_success;
41 }
42 json_result = faceDetect_result;
43 curl_easy_cleanup(curl);
44 is_success = 0;
45 } else {
46 fprintf(stderr, "curl_easy_init() failed.");
47 is_success = 1;
48 }
49 return is_success;
50}
1using System;
2using System.IO;
3using System.Net;
4using System.Text;
5using System.Web;
6
7namespace com.baidu.ai
8{
9 public class FaceDetect
10 {
11 // 人脸检测与属性分析
12 public static string faceDetect()
13 {
14 string token = "[调用鉴权接口获取的token]";
15 string host = "https://aip.baidubce.com/rest/2.0/face/v3/detect?access_token=" + token;
16 Encoding encoding = Encoding.Default;
17 HttpWebRequest request = (HttpWebRequest)WebRequest.Create(host);
18 request.Method = "post";
19 request.KeepAlive = true;
20 String str = "{\"image\":\"027d8308a2ec665acb1bdf63e513bcb9\",\"image_type\":\"FACE_TOKEN\",\"face_field\":\"faceshape,facetype\"}";
21 byte[] buffer = encoding.GetBytes(str);
22 request.ContentLength = buffer.Length;
23 request.GetRequestStream().Write(buffer, 0, buffer.Length);
24 HttpWebResponse response = (HttpWebResponse)request.GetResponse();
25 StreamReader reader = new StreamReader(response.GetResponseStream(), Encoding.Default);
26 string result = reader.ReadToEnd();
27 Console.WriteLine("人脸检测与属性分析:");
28 Console.WriteLine(result);
29 return result;
30 }
31 }
32}
返回说明
返回参数
- 返回结果
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
face_num | 是 | int | 检测到的图片中的人脸数量 |
face_list | 是 | array | 人脸信息列表,具体包含的参数参考下面的列表。 |
+face_token | 是 | string | 人脸图片的唯一标识 (人脸检测face_token有效期为60min)。如果希望使用此token做人脸1:1比对,请求接口时,需传入face_field=feature |
+location | 是 | array | 人脸在图片中的位置 |
++left | 是 | double | 人脸区域离左边界的距离 |
++top | 是 | double | 人脸区域离上边界的距离 |
++width | 是 | double | 人脸区域的宽度 |
++height | 是 | double | 人脸区域的高度 |
++rotation | 是 | int64 | 人脸框相对于竖直方向的顺时针旋转角,[-180,180] |
+face_probability | 是 | double | 人脸置信度,范围【0~1】,代表这是一张人脸的概率,0最小、1最大。其中返回0或1时,数据类型为Integer |
+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 | 否 | string | 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 |
+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 0代表没戴口罩 1 代表戴口罩 |
++probability | 否 | double | 置信度,范围0~1 |
+landmark | 否 | array | 4个关键点位置,左眼中心、右眼中心、鼻尖、嘴中心。face_field包含landmark时返回 |
+landmark72 | 否 | array | 72个特征点位置 face_field包含landmark时返回 |
+landmark150 | 否 | object | 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 | 单张图片的活体信息。liveness_control包含LOW\NORMAL\HIGH时返回 |
++livemapscore | 否 | double | 单张图片的活体得分范围[0~1]。 |
+spoofing | 否 | double | 判断图片是合成图的概率 |
+not_spoofing | 否 | double | 判断图片不是合成图的概率 |
corp_image_base64 | 否 | string | 检测人脸框的人脸图片base64值 |
关于合成图检测spoofing的判断阈值选择,可参考以下数值信息:
阈值 | 误拒率(FRR) | 通过率(TAR) | 攻击拒绝率(TRR)) |
---|---|---|---|
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% |
关于以上数值的概念介绍:
- 拒绝率(TRR):如99%,代表100次作弊假体攻击,会有99次被拒绝。
- 误拒率(FRR):如0.5%,指1000次真人请求,会有5次因为活体分数低于阈值被错误拒绝。
- 通过率(TAR):如99%,指100次真人请求,会有99次因为活体分数高于阈值而通过。
- 阈值(Threshold):高于此数值,则可判断为是合成图攻击。
-
返回示例
JSON1{ 2 "face_num": 1, 3 "face_list": [ 4 { 5 "face_token": "35235asfas21421fakghktyfdgh68bio", 6 "location": { 7 "left": 117, 8 "top": 131, 9 "width": 172, 10 "height": 170, 11 "rotation": 4 12 }, 13 "face_probability": 1, 14 "angle" :{ 15 "yaw" : -0.34859421849251 16 "pitch": 1.9135693311691 17 "roll" :2.3033397197723 18 } 19 "landmark": [ 20 { 21 "x": 161.74819946289, 22 "y": 163.30244445801 23 }, 24 ... 25 ], 26 "landmark72": [ 27 { 28 "x": 115.86531066895, 29 "y": 170.0546875 30 }, 31 ... 32 ], 33 "age": 29.298097610474, 34 "expression": { 35 "type": "smile", 36 "probability" : 0.5543018579483 37 }, 38 "gender": { 39 "type": "male", 40 "probability": 0.99979132413864 41 }, 42 "glasses": { 43 "type": "sun", 44 "probability": 0.99999964237213 45 }, 46 47 "face_shape": { 48 "type": "triangle", 49 "probability": 0.5543018579483 50 } 51 "quality": { 52 "occlusion": { 53 "left_eye": 0, 54 "right_eye": 0, 55 "nose": 0, 56 "mouth": 0, 57 "left_cheek": 0.0064102564938366, 58 "right_cheek": 0.0057411273010075, 59 "chin": 0 60 }, 61 "blur": 1.1886881756684e-10, 62 "illumination": 141, 63 "completeness": 1 64 } 65 } 66 ] 67}
72个关键点分布图(对应landmark72个点的顺序,序号从0-71):
150个关键点分布图,红色关键点为在72关键点基础上增加的关键点(对应landmark150个点的顺序,序号从0-149,且每个关键点有对应的英文命名作为参数名,请参考图片下方表格):
关键点名称如下图,
错误码
请参考人脸识别错误码