人脸检测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：
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Authorization | 是 | String | 访问token:可通过控制台服务的appKey，secretkey和servicekey生成，具体方式请参考：“API token获取” 注意：有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token； |
Query：
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | 是 | String | application/json |
| action | 是 | String | 公共参数，本接口取值：aiservice-facedetect |
| version | 是 | String | API版本号，当前版本号：1 |
Body：
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| image | 是 | String | 图片的base64数据，base64编码后大小不可超过5M。需要注意的是，图片的base64编码不包含图片头， 如data:image/jpg;base64,图片格式：现支持PNG、JPG、JPEG、BMP，不支持GIF图片。 |
| maxFaceNum | 否 | Integer | 最多处理人脸数，默认：10 |
4、返回结果
| 名称 | 说明 |
|---|---|
| code | 返回结果信息码 |
| data | 识别结果数据 |
| msg | 描述信息 |
| status | API状态 |
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、信息码
| 信息码 | 描述信息 | 描述 | 处理建议 |
|---|---|---|---|
| 100 | nvalid appKey,secretkeyor servicekey | Key 非法 | 控制台检查申请token时设定的key |
| 101 | Invalid Token | 非法token | 重新申请token，或确认token是否正确 |
| 102 | Open api total request limit reached | 访问超过限额 | 控制台确认购买的授权服务剩余次数 |
| 103 | no permission to access data | 未授权操作 | 控制台确认服务是否购买授权 |
| 104 | Service Expiration | token过期 | 重新申请token |
| 105 | Resource Unavailable | 资源不可用 | 详细确认接口说明，确认action是否正确 |
| 106 | Token Acquisition failed | Token获取失败 | 检查设定的key，重新获取 |
| 107 | Token Null | Token为空 | 确认token是否添加 |
| 200 | Success | 成功 | |
| 201 | Failed Operation | 操作失败 | 确认请求参数或重新请求 |
| 300 | param is null | 必要参数未传入 | 检查必须的请求参数xx是否设定 |
| 301 | param format error | 参数格式错误 | 检查请求参数xx的数据格式，是否符合要求 |
