API功能
接口分类 | 接口名称 | 功能说明 |
---|---|---|
detect | /detection/detect | 检测一张照片中的人脸信息(脸部位置、年龄、种族、性别等等) |
/detection/landmark | 检测给定人脸相应的面部轮廓,五官等关键点的位置 | |
train | /train/verify | 调用/recognition/verify之前需要运行的训练 |
/train/search | 调用/recognition/search之前需要运行的训练 | |
/train/identify | 调用/recognition/identify之前需要运行的训练 | |
recognition | /recognition/compare | 对比两张人脸的相似程度 |
/recognition/verify | 给定人脸和人,判断这张人脸是否是给定的人 | |
/recognition/search | 给定人脸和人脸集合,在集合中找最相似的人脸 | |
/recognition/identify | 给定人脸和人群,找到人群中最像这张脸的人 | |
grouping | /grouping/grouping | 给定人脸集合,将集合中的人脸分成几类,每一类为同一个人 |
person | /person/create | 创建一个人 |
/person/delete | 删除一个人 | |
/person/add_face | 向一个人添加一张人脸 | |
/person/remove_face | 从一个人中删除一张人脸 | |
/person/set_info | 为一个人设定备注等信息 | |
/person/get_info | 获得一个人的备注等信息 | |
faceset | /faceset/create | 创建一个人脸集合 |
/faceset/delete | 删除一个人脸集合 | |
/faceset/add_face | 向一个人脸集合添加人脸 | |
/faceset/remove_face | 从一个人脸集合中删除人脸 | |
/faceset/set_info | 为一个人集合设定备注等信息 | |
/faceset/get_info | 获得一个人集合的备注等信息 | |
group | /group/create | 创建一个人群 |
/group/delete | 删除一个人群 | |
/group/add_person | 向人群中添加一个人 | |
/group/remove_person | 从人群中删除一个人 | |
/group/get_info | 获得人群的备注等信息 | |
info | /info/get_image | 获取一张图片的信息,包括其中的人脸信息 |
/info/get_face | 获取一组人脸的信息 | |
/info/get_person_list | 获取该应用中所有的人 | |
/info/get_faceset_list | 获取该应用中所有的人脸集合 | |
/info/get_group_list | 获取该应用中所有的人群 | |
/info/get_session | 获取session的状态与结果 | |
/info/get_app | 获取应用的相关信息 |
/detection/detect
描述
检测给定图片(Image)中的所有人脸(Face)的位置和相应的面部属性
-
目前面部属性包括性别(gender), 年龄(age), 种族(race), 微笑程度(smiling), 眼镜(glass)和姿势(pose)
若结果的face_id没有被加入任何faceset/person之中,则在72小时之后过期被自动清除。
参数
参数名 | 参数说明 | |
---|---|---|
必须 | api_key | App的Face++ API Key |
api_secret | APP的Face++ API Secret | |
url 或 img[POST] | 待检测图片的URL 或者 通过POST方法上传的二进制数据,原始图片大小需要小于1M | |
可选 | mode | 检测模式可以是normal(默认) 或者 oneface 。在oneface模式中,检测器仅找出图片中最大的一张脸。 |
attribute | 可以是none或者由逗号分割的属性列表。默认为gender, age, race, smiling。目前支持的属性包括:gender, age, race, smiling, glass, pose | |
tag | 可以为图片中检测出的每一张Face指定一个不包含^@,&=*'"等非法字符且不超过255字节的字符串作为tag,tag信息可以通过 /info/get_face 查询 | |
async | 如果置为true,该API将会以异步方式被调用;也就是立即返回一个session id,稍后可通过/info/get_session查询结果。默认值为false。 |
返回值说明
字段 | 类型 | 说明 |
---|---|---|
session_id | string | 相应请求的session标识符,可用于结果查询 |
url | string | 请求中图片的url |
img_id | string | Face++系统中的图片标识符,用于标识用户请求中的图片 |
face_id | string | 被检测出的每一张人脸都在Face++系统中的标识符 |
img_width | integer | 请求图片的宽度 |
img_height | integer | 请求图片的高度 |
face | array | 被检测出的人脸的列表 |
width | float | 0~100之间的实数,表示检出的脸的宽度在图片中百分比 |
height | float | 0~100之间的实数,表示检出的脸的高度在图片中百分比 |
center | object | 检出的人脸框的中心点坐标, x & y 坐标分别表示在图片中的宽度和高度的百分比 (0~100之间的实数) |
eye_left | object | 相应人脸的左眼坐标,x & y 坐标分别表示在图片中的宽度和高度的百分比 (0~100之间的实数) |
eye_right | object | 相应人脸的右眼坐标,x & y 坐标分别表示在图片中的宽度和高度的百分比 (0~100之间的实数) |
mouth_left | object | 相应人脸的左侧嘴角坐标,x & y 坐标分别表示在图片中的宽度和高度的百分比 (0~100之间的实数) |
mouth_right | object | 相应人脸的右侧嘴角坐标,x & y 坐标分别表示在图片中的宽度和高度的百分比 (0~100之间的实数) |
nose | object | 相应人脸的鼻尖坐标,x & y 坐标分别表示在图片中的宽度和高度的百分比 (0~100之间的实数) |
attribute | object | 包含一系列人脸的属性分析结果 |
gender | object | 包含性别分析结果,value的值为Male/Female, confidence表示置信度 |
age | object | 包含年龄分析结果,value的值为一个非负整数表示估计的年龄, range表示估计年龄的正负区间 |
race | object | 包含人种分析结果,value的值为Asian/White/Black, confidence表示置信度 |
smiling | object | 包含微笑程度分析结果,value的值为0-100的实数,越大表示微笑程度越高 |
glass | object | 包含眼镜佩戴分析结果,value的值为None/Dark/Normal, confidence表示置信度 |
pose | object | 包含脸部姿势分析结果,包括pitch_angle, roll_angle, yaw_angle,分别对应抬头,旋转(平面旋转),摇头。单位为角度。 |
调用示例
http://apicn.faceplusplus.com/v2/detection/detect?api_key=YOUR_API_KEY&api_secret=YOUR_API_SECRET&url=http%3A%2F%2Ffaceplusplus.com%2Fstatic%2Fimg%2Fdemo%2F1.jpg&attribute=glass,pose,gender,age,race,smiling
JSON 示例
{
"face": [
{
"attribute": {
"age": {
"range": 5,
"value": 23
},
"gender": {
"confidence": 99.9999,
"value": "Female"
},
"glass": {
"confidence": 99.945,
"value": "None"
},
"pose": {
"pitch_angle": {
"value": 17
},
"roll_angle": {
"value": 0.735735
},
"yaw_angle": {
"value": -2
}
},
"race": {
"confidence": 99.6121,
"value": "Asian"
},
"smiling": {
"value": 4.86501
}
},
"face_id": "17233b4b1b51ac91e391e5afe130eb78",
"position": {
"center": {
"x": 49.4,
"y": 37.6
},
"eye_left": {
"x": 43.3692,
"y": 30.8192
},
"eye_right": {
"x": 56.5606,
"y": 30.9886
},
"height": 26.8,
"mouth_left": {
"x": 46.1326,
"y": 44.9468
},
"mouth_right": {
"x": 54.2592,
"y": 44.6282
},
"nose": {
"x": 49.9404,
"y": 38.8484
},
"width": 26.8
},
"tag": ""
}
],
"img_height": 500,
"img_id": "22fd9efc64c87e00224c33dd8718eec7",
"img_width": 500,
"session_id": "38047ad0f0b34c7e8c6efb6ba39ed355",
"url": "http://www.faceplusplus.com.cn/wp-content/themes/faceplusplus/assets/img/demo/1.jpg?v=4"
}
错误列表
错误代码 | HTTP 状态代码 | 错误信息 |
---|---|---|
1001 | 500 | INTERNAL_ERROR |
1003 | 403 | AUTHORIZATION_ERROR |
1003 | 403 | INSUFFICIENT_PRIVILEGE_OR_QUOTA_LIMIT_EXCEEDED |
1004 | 400 | MISSING_ARGUMENTS |
1005 | 400 | INVALID_ARGUMENTS |
1006 | 403 | ILLEGAL_USE_OF_DEMO_KEY |
1202 | 502 | SERVER_TOO_BUSY |
1301 | 431 | IMAGE_ERROR_UNSUPPORTED_FORMAT |
1302 | 432 | IMAGE_ERROR_FAILED_TO_DOWNLOAD |
1303 | 433 | IMAGE_ERROR_FILE_TOO_LARGE |
1304 | 434 | IMAGE_ERROR |
1502 | 452 | BAD_TAG |
package org.jiahao.weixin.util;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import net.sf.json.JSONArray;
import net.sf.json.JSONObject;
import org.jiahao.weixin.face.Face;
/**
* 人脸识别FacePlusPlus工具类
* @author Alvin
*
*/
public class FacePlusPlusUtil {
public static String detectFace(String imageUrl) {
// 拼装请求地址
String requestUrl = "http://apicn.faceplusplus.com/v2/detection/detect?api_key=YOUR_API_KEY&api_secret=YOUR_API_SECRET&url=URL&attribute=glass,pose,gender,age,race,smiling";
requestUrl = requestUrl.replace("YOUR_API_KEY", "e93513e749c2a70a297189b232f22f1d");
requestUrl = requestUrl.replace("YOUR_API_SECRET", "sZs-D_kjQ3kfWGqcPNcv70rqgU-d-GBM");
requestUrl = requestUrl.replace("URL", CommonUtil.urlEncodeUTF8(imageUrl));
// 发起请求
String respJson = CommonUtil.httpRequest(requestUrl, "GET", null);
// 获取Face数组
JSONArray faceArray = (JSONArray)JSONObject.fromObject(respJson).get("face");
List<Face> faceList = new ArrayList<Face>();
// 遍历检测到的人脸
for(int i = 0; i < faceArray.size(); i++) {
JSONObject faceObject = (JSONObject)faceArray.get(i);
JSONObject attributeObject = faceObject.getJSONObject("attribute");
JSONObject positionObject = faceObject.getJSONObject("position");
Face face = new Face();
face.setFaceId(faceObject.getString("face_id"));
face.setAgeValue(attributeObject.getJSONObject("age").getInt("value"));
face.setAgeRange(attributeObject.getJSONObject("age").getInt("range"));
face.setGenderValue(genderConvert(attributeObject.getJSONObject("gender").getString("value")));
face.setGenderConfidence(attributeObject.getJSONObject("gender").getDouble("confidence"));
face.setRaceValue(raceConvert(attributeObject.getJSONObject("race").getString("value")));
face.setRaceConfidence(attributeObject.getJSONObject("race").getDouble("confidence"));
face.setSmilingValue(attributeObject.getJSONObject("smiling").getDouble("value"));
face.setCenterX(positionObject.getJSONObject("center").getDouble("x"));
face.setCenterY(positionObject.getJSONObject("center").getDouble("y"));
faceList.add(face);
}
Collections.sort(faceList);
StringBuffer buffer = new StringBuffer();
// 检测到1张人脸
if(1 == faceList.size()) {
buffer.append("共检测到").append(faceList.size()).append("张人脸\n\n");
for(Face face : faceList) {
// 人种
buffer.append(face.getRaceValue()).append("人种,");
// 性别
buffer.append(face.getGenderValue()).append(",");
// 年龄
buffer.append(face.getAgeValue()).append("岁左右");
}
}
// 检测到多张人脸
else if(faceList.size() > 1) {
buffer.append("共检测到").append(faceList.size()).append("张人脸,按脸部中心位置从左到右依次为:\n\n");
for(Face face : faceList) {
// 人种
buffer.append(face.getRaceValue()).append("人种,");
// 性别
buffer.append(face.getGenderValue()).append(",");
// 年龄
buffer.append(face.getAgeValue()).append("岁左右\n");
}
}
else {
buffer.append("你确定你发的是人?");
}
return buffer.toString();
}
/**
* 将 Male/Female 转换成 男性/女性
* @param gender
* @return
*/
private static String genderConvert(String gender) {
String result = "男性";
if(gender.equals("Female")) {
result = "女性";
}
return result;
}
/**
* 将 Asian/White/Black 转换成 黄色/白色/黑色
* @param race
* @return
*/
private static String raceConvert(String race) {
String result = "黄色";
if(race.equals("Asian")) {
result = "黄色";
}
else if(race.equals("White")) {
result = "白色";
}
else if(race.equals("Black")) {
result = "黑色";
}
return result;
}
public static void main(String[] args) {
String str = FacePlusPlusUtil.detectFace("http://mmbiz.qpic.cn/mmbiz/lLTibpXzX33grSReqBZGr0NcnVclxdzGH9TvDztcjIseDFmPUNz3IprJITdvib9TicZU0iaLKlibhpxYTWibClQcQF0w/0.jpg");
System.out.println(str);
}
}