人脸检测API使用文档

本文档主要针对HTTP API调用者,创迹AI开放平台需注册后申请服务授权调用API。 本文以“人脸检测”能力为例,指引您开启开发之旅。

1、能力介绍

检测给定图片中的人脸的位置,对应的性别,年龄,是否活体和人脸3D旋转角度。

2、调用方式

该接口主要用于HTTP API调用,服务授权请参考[接入指南-API接入指南],根据指南进行服务授权,授权后进行API使用。

3、请求说明

HTTP方法:POST

接口请求域名:service.trial-power.com

请求URL:https://service.trial-power.com/aiop_oauth/oauth/service

Headers:

参数名称必选类型描述
AuthorizationString 访问token:可通过控制台服务的appKey,secretkey和servicekey生成,具体方式请参考:“API token获取” 注意:有效期为30天,切记需要每30天进行定期更换,或者每次请求都拉取新token;

Query:

参数名称必选类型描述
Content-TypeStringapplication/json
actionString公共参数,本接口取值:aiservice-facedetect
versionStringAPI版本号,当前版本号:1

Body:

参数名称必选类型描述
imageString 图片的base64数据,base64编码后大小不可超过5M。需要注意的是,图片的base64编码不包含图片头,如data:image/jpg;base64,图片格式:现支持PNG、JPG、JPEG、BMP,不支持GIF图片。
maxFaceNumInteger最多处理人脸数,默认:10

4、返回结果

名称说明
code返回结果信息码
data识别结果数据
msg描述信息
statusAPI状态

data详细:

名称说明
faceInfo

人脸信息

orient:检测结果人脸角度

逆时针0度:1

逆时针90度:2

逆时针270度:3

逆时针180度:4

逆时针30度:5

逆时针60度:6

逆时针120度:7

逆时针150度:8

逆时针210度:9

逆时针240度:10

逆时针300度:11

逆时针330度:12

left:人脸位置:左上x

top:人脸位置:左上y

right:人脸位置:右下x

bottom:人脸位置:右下y

gender性别(未知性别=-1 、男性=0 、女性=1)
age年龄
angle

人脸旋转角度参数

pitch:俯仰角(三维绕X轴旋转 俯仰角度[-90(上), 90(下)])

yaw:偏航角(三维绕Y轴旋转 旋转角[-90(左), 90(右)])

roll:横滚角(三维 绕Z轴旋转 旋转角度[-180(逆时针), 180(顺时针)])

status:0: 正常 非0: 异常

liveness活体值(未知=-1 、非活体=0 、活体=1)

例如:

{
  "code": 200,
  "data": [
    {
      "gender": 0,
      "liveness": 1,
      "angle": {
        "roll": -3.754812,
        "pitch": -10.562885,
        "yaw": 14.1711235,
        "status": 0
      },
      "faceInfo": {
        "orient": 1,
        "top": 197,
        "left": 386,
        "bottom": 275,
        "right": 464
      },
      "age": 32
    }
  ],
  "msg": "RequestId:5394f3a983c240d3bd90d69eef86edc4 Success",
  "status": 200
}

5、信息码

信息码描述信息描述处理建议
100nvalid appKey,secretkeyor servicekeyKey 非法控制台检查申请token时设定的key
101Invalid Token非法token重新申请token,或确认token是否正确
102Open api total request limit reached访问超过限额控制台确认购买的授权服务剩余次数
103no permission to access data未授权操作控制台确认服务是否购买授权
104Token Expiretoken过期重新申请token
105Resource Unavailable资源不可用详细确认接口说明,确认action是否正确
106Token Acquisition failedToken获取失败检查设定的key,重新获取
200Success成功 
201Failed Operation操作失败确认请求参数或重新请求
300param[xx] is null必要参数未传入检查必须的请求参数xx是否设定
301param [xx] format error参数格式错误检查请求参数xx的数据格式,是否符合要求