1. 云端人脸识别API接口服务
商米提供云端人脸识别API接口服务,用户可以用标准的HTTP请求来获取人脸检测框和人脸特征。其中,人脸特征可用于批量构建人脸底库,使用sqlite数据库进行人脸库的存储,其构建表结构如下:
CREATE TABLE SUNMI_FACE (
AUTOID INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
"ID VARCHAR(64), "
"NAME VARCHAR(64), "
"IMG_ID VARCHAR(64), "
"FEATURE BLOB,"
"CreatedTime TimeStamp NOT NULL DEFAULT CURRENT_TIMESTAMP);
数据表中各个字段的赋值,需注意以下几点:
- ID是用户的唯一标识,同一个用户ID相同,不用用户ID不同。
- NAME是用户姓名,允许重复。
- IMG_ID是对应人脸图片在数据库中的唯一标识,不可重复,需要采用UUID0算法生成唯一不重复的uuid。
- FEATURE是通过人脸API服务获取的人脸特征。
1.1. 人脸检测-请求参数
url地址:请联系商米获取云服务的url 地址
参数名称 | 是否必选 | 类型 | 默认值 | 说明 |
image | 是 | string | / | 图片信息 (总数据大小应小于2M),图片上传方式根据image_type来判断 |
image_type | 是 | string | / | 图片类型 BASE64:图片的base64值。base64编码后的图片数据,其图片大小不超过2M;URL:图片的 URL地址(可能由于网络等原因导致下载图片时间过长); |
max_face_count | 否 | int | 1 | 最多处理人脸的数目,默认值为1,仅检测图片中人脸置信度最高的那个人脸;最大值为10,检测图片中面积最大的几张人脸。 |
predict_mode | 否 | int | 7 | 参考下面的预测模式定义。7即为默认人脸检测+人脸特征+人脸属性。(年龄和性别都包含在人脸属性中) |
预测模式定义示例代码如下:
typedef enum {
PredictMode_None = 0,
PredictMode_Detect = 1 ‹‹ 0, // face detect
PredictMode_Feature = (1 ‹‹ 1) + PredictMode_Detect, // face detect and extract features
PredictMode_Age = (1 ‹‹ 2) + PredictMode_Detect, // face detect and age predict
PredictMode_Gender = PredictMode_Age, // face detect and gender predict
} SunmiFaceMode;
1.2. 人脸识别API–返回数据
字段 | 必选 | 类型 | 说明 |
face_num | 是 | int | 检测到的图片中的人脸数量 |
face_list | 是 | array | 人脸信息列表,具体参数参考下面的列表 |
+location | 是 | array | 人脸在图片中的位置 |
++left | 是 | double | 人脸框左上角x坐标 |
++top | 是 | double | 人脸框左上角y坐标 |
++width | 是 | double | 人脸框宽度 |
++height | 是 | double | 人脸框高度 |
+ face_probability | 是 | double | 人脸置信度 |
+ angle | 是 | array | 人脸旋转角度 |
++ yaw | 是 | double | 左右旋转角[-90(左), 90(右)] |
++ pitch | 是 | double | 俯仰旋转角[-90(上), 90(下)] |
++ roll | 是 | double | 平面内旋转角[-90(逆时针), 90(顺时针)] |
+ landmark | 是 | array | 5个关键点位置,左眼中心、右眼中心、鼻尖、左嘴角,右嘴角。 |
+ liveness_score | 是 | double | 2D活体检测得分,值越高说明是真人的概率高 |
+ feature | 是 | array | 人脸256维特征值 |
返回结果如为json格式,如以下示例:
{
"face_num": 1,
"face_list": [
{
"location": {
"left": 216.1408233642578,
"top": 157.1695556640625,
"width": 90.74900817871094,
"height": 115.81448364257812
},
"face_probability": 0.9972383975982666,
"angle": {
"yaw": 5.858273506164551,
"pitch": 19.634262084960938,
"roll": -1.6777983903884888
},
"landmark": [
{
"x": 239.48606872558594,
"y": 203.29200744628906
},
{
"x": 280.5645446777344,
"y": 203.55821228027344
},
{
"x": 258.20745849609375,
"y": 226.3636016845703
},
{
"x": 242.2882080078125,
"y": 243.4677734375
},
{
"x": 276.392333984375,
"y": 243.5858917236328
}
],
"liveness_score": 0.9542617797851562,
"gender_info": {
"gender": "female",
"score": 1.0
},
"age_info": {
"age": 25,
"score": 0.8857287168502808
},
"feature": [
0.0012834692606702447,
0.027195502072572708,
-0.1606169044971466,
-0.1035875454545021,
-0.055142492055892944,
…
0.043723493814468384,
0.07170124351978302,
-0.10330264270305634
]
}
]
}
1.3. 人脸识别API–返回状态码
因API不提供自定义配置参数设置,如SDK中的人脸姿态阈值、光照阈值等,在API中均采用默认值,而FACE_CODE_BAD_ILLUMINATION,FACE_CODE_POSE_ERROR等依赖配置参数,所以下表提供的返回值仅针对默认配置参数。
人脸姿态可直接根据返回的json中的“angle”字段进行判断,人脸大小可根据“location”字段判断。
商米人脸识别状态码如下表所示:
枚举成员 | 状态码 | 说明 |
FACE_CODE_OK | 0 | 正确 |
FACE_CODE_UNINIT | 1 | SDK没有初始化 |
FACE_CODE_EMPTY_IMAGE | 2 | 图片为空 |
FACE_CODE_NO_MODEL | 3 | 无加载模型文件 |
FACE_CODE_CONFIG_ERROR | 4 | 配置错误 |
FACE_CODE_BAD_ILLUMINATION | 5 | 光线条件不好 |
FACE_CODE_POSE_ERROR | 6 | 面部位置不符合要求 |
FACE_CODE_SMALL_FACE_SIZE | 7 | 人脸尺寸太小 |
FACE_CODE_LOW_IMAGE_QUALITY | 8 | 人脸图像模糊 |
FACE_CODE_NOT_LIVENESS | 9 | 非活体人脸图像 |
FACE_CODE_LICENSE_ERROR | 10 | 授权文件无效 |
FACE_CODE_LICENSE_EXPIRED | 11 | 授权文件过期 |
FACE_CODE_IMAGE_ID_ERROR | 101 | 删除时图像id不存在 |
FACE_CODE_OTHER_ERROR | 1000 | 其他错误 |
2. Python示例代码
2.1. 图片采用BASE64格式
对于BASE64格式的图片,使用如下示例进行API接口的调用:
import numpy as np
import cv2
import requests
import base64
import json
if __name__ == '__main__':
url = "http://face-recognition.sunmi.com/v1/face/recognition"
with open("test.jpg", "rb") as f:
base64_data = base64.b64encode(f.read())
data = {"image": base64_data, "image_type": "BASE64", "max_face_count": 1}
r = requests.post(url, data=data)
s = json.loads(r.content)
print(s['msg'])
2.2. 图片采用URL格式
对于URL格式的图片,使用如下示例进行API接口的调用:
import numpy as np
import cv2
import requests
import base64
import json
if __name__ == '__main__':
url = "****"
data = {"image": "https://wifi.cdn.sunmi.com/UAT/IMG/FACE/AM4RDZ2LP5HWTIJ8G70KN8NFNY0766WK1", "image_type": "URL", "max_face_count": 1}
r = requests.post(url, data=data)
s = json.loads(r.content)
print(s['msg'])