接口描述
用于检测输入图像中的人脸，输出人脸数量、人脸位置坐标、人脸98个关键点信息、人脸角度信息、人脸质量信息等。
请求方法
POST
接口要求
图片大小限制：图片单张大小小于7MB；
图片格式限制：图片格式支持jpg/jpeg/png/bmp格式。
URI
/v1/aiop/api/2f6hqix09mv4/face/PERSON/person/detectFaceFromBase64
请求参数
1.请求头header参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| Content-Type | 是 | String | json格式 | application/json | |
| appkey | 是 | String | 平台应用appkey | 562b89493b1a4XXXXXXXXX | |
| ctyun-eop-request-id | 是 | String | 用户请求 id，由用户构造，用户可以通过 uuid 等方法自行生成唯一字符串，用于日志请求追踪。 详见文档：Python3调用示例 | 33dfa732-b27b-464f-b15a-21ed6845afd5 | |
| eop-date | 是 | String | 请求时间，由用户构造，形如 yyyymmddTHHMMSSZ。 详见文档：Python3调用示例 | 20211221T163014Z | |
| host | 是 | String | 终端节点域名，固定字段 | ai-global.ctapi.ctyun.cn | |
| version | 是 | String | 固定值，v3 | ||
| Eop-Authorization | 是 | String | 由天翼云官网 accessKey 和 securityKey 经签名后生成，参与签名生成的字段包括天翼云官网 accessKey 、securityKey、平台应用的appkey（非必须），用户请求id（非必须），请求时间，终端节点域名（非必须）以及请求体内容。 签名逻辑详见文档：认证鉴权和Python3调用示例 |
2.请求体body参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| Action | 是 | String | 服务名称，固定值DetectFace | DetectFace | |
| ImageData | 是 | String | 图⽚的 base64 编码 | ||
| FaceThresh | 否 | Float | ⼈脸分数阈值。 取值范围 [0,1]，默认值为 0.5。 检测分数低于该阈值的⼈脸会被过滤 （不返回结果），建议使⽤默认值。 | 0.5 | |
| NeedFaceAngle | 否 | Bool | 是否返回⼈脸⻆度信息。 默认为 False，不返回⼈脸⻆度。 若该值设为 True，则返回⼈脸⻆度。 | ||
| NeedFaceQuality | 否 | Bool | 是否返回人脸质量信息。默认为 False，不返回⼈脸质量信息。 若该值设为 True，则返回⼈脸质量信息。 | ||
| NeedMoreLandmark | 否 | Bool | 是否返回98个关键点信息。默认为 False，不返回98个关键点信息。 若该值设为 True，则返回98个关键点信息。 |
请求代码示例
Curl -X POST "https://ai-global.ctapi.ctyun.cn/v1/aiop/api/2f6hqix09mv4/face/PERSON/person/detectFaceFromBase64"
-H "Content-Type: application/json"
-H "ctyun-eop-request-id:33dfa732-b27b-464f-b15a-21ed6845afd5"
-H "appkey:XXX"
-H "version:v3"
-H "Eop-Authorization:XXX"
-H "eop-date:20211109T104641Z"
-H "host:ai-global.ctapi.ctyun.cn"
--data '{"Action": "DetectFace", "ImageData": "AAAAAAA.......", "FaceThresh": 0.5,"NeedFaceAngle": true}'返回值说明
1.请求成功返回响应参数
| 参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|---|
| statusCode | 是 | String | 接口状态码，返回状态，返回 0 表示成功，返回错误代码参考下面的错误代码列表 | 0 | |
| message | 是 | String | 如果statusCode 为 0，返回 success；如果statusCode 非 0，返回 error | success | |
| returnObj | 是 | Object | 返回的人脸检测结果对象 | returnObj |
2.表returnObj
| 参数 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|
| DetectCount | Int | 检测到的⼈脸数量 | 2 | |
| DetectBoxes | Array | ⼈脸位置信息。 位置信息包括 box = [left, top, width, height]。 如有两个人脸，则返回 [box1, box2]，数组的维度 为 2 x 4，以此类推 | [[741, 117, 45, 72], [567, 148, 45, 60]] | |
| DetectScores | Array | ⼈脸检测分数。 每个检测框返回⼀个分数 score，取值范围 [0,1]。 如有两个人脸，则返回 [score1, score2]，数组的 维度为 1 x 2，以此类推 | [0.9974, 0.9964] | |
| DetectClses | Array | ⼈脸检测类别。 每个检测框返回⼀个类别 cls。 如有两个人脸，则返回 [cls1, cls2]，数组的维度 为 1 x 2，以此类推。 类别为 face 表示⼈脸 | ["face", "face"] | |
| LandmarkCount | Int | ⼈脸关键点数⽬。 单个⼈脸关键点固定为 5 点。 关键点包括眼睛 2 点，⿐⼦ 1 点，嘴巴 2 点 | 5 | |
| Landmarks | Array | 人脸关键点位置信息。 每个⼈脸返回⼀组关键点坐标 landmark，表示 ⽅式为 [x1, y1, x2, y2, x3, y3, x4, y4, x5, y5]， 数组的维度为 1 x 10。 如有两个⼈脸，则返回 [landmark1, landmark2]，数组的维度为 2 x 10，以此类推 | [ [750,142,750,144, 736,157,750,172, 751,172], [575,175,582,174, 571,187,579,196, 584,195] ] | |
| FaceAngles | Array | ⼈脸⻆度信息。 仅当请求时 NeedFaceAngle=True 才返回。 单位为⻆度。单个⼈脸⻆度信息包含 angle = [pitch, yaw, roll]，分别为上下偏移，左右偏 移，平⾯旋转。数组的维度为 1 x 3。 如有两个⼈脸，则返回 [angle1, angle2]，数组 的维度为 2 x 3，以此类推 | [ [-2.1, 72.3, 0.6], [-32.0, 62.6, -26.0] | |
| FaceQualities | Array | 人脸质量信息。仅当请求时NeedFaceQuality=True才返回。每个人脸返回一个质量数组，分数越高质量越好，取值范围[0,100]。如有两个人脸，则返回[quality1,quality2]，数组的维度为1 x 2，以此类推。质量数组每个元素内容分别是[模糊分数、人脸可信度、眼镜分数、光照分数、口罩分数、噪声分数、姿态分数、总分] | [ [69.629, 66.162, 88.867, 37.061, 33.301, 78.076, 35.693, 63.428], [25.952, 36.206, 62.598, 40.186, 61.523, 53.174, 23.157, 53.662]] | |
| Landmarks_98 | Array | 人脸98个关键点位置信息（2 维数组）。仅当请求时 NeedMoreLandmark=True 才返回，每个人脸返回一组关键点坐标 landmark，表示方式为 [x1, y1, x2, y2...x195, y195, x196, y196]，数组的维度为 1 x 196。如有两个人脸，则返回 [landmark1, landmark2]，数组的维度为 2 x 196，以此类推。 |
3.请求失败返回响应参数
| 参数 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|
| statusCode | String | 错误码，放置API对应的错误码 | 500001 | |
| message | String | 返回对应的错误信息 | 必传的参数未传 | |
| details | String | 返回对应的错误描述 | 异常详情信息 | |
| error | String | 返回对应的错误码 | AI_OP_500001 |
返回值示例
1.请求成功返回值示例
{ 'statusCode': 0,
'message': 'success',
'returnObj': {'DetectBoxes': [[1135, 181, 279, 274]],
'DetectClses': ['face'],
'DetectCount': 1,
'DetectScores': [0.6763],
'FaceAngles': [[-40.4, 1.2, 5.16]],
'LandmarkCount': 5,
'Landmarks': [[1214,
290,
1335,
289,
1273,
380,
1235,
407,
1319,
407]]}
}2.请求失败返回示例
{
'code': 400006,
'details': '必须的参数（Action、ImageData）未传',
'error': 'AI_OP_400006',
'message': '必传的参数未传',
'statusCode': 400006
}错误码说明
6 位错误码。4 开头为业务错误码，5 开头为服务错误码。
| 错误码 | 错误信息 | 错误描述 |
|---|---|---|
| CTAPI_10000 | API Not Found | |
| CTAPI_0009 | 无效json的body参数 | |
| AI_OP_400005 | 请求体类型错误 | 请求体需为字典，不能为其他类型 |
| AI_OP_400006 | 必传的参数未传 | 必须的参数（Action、ImageData）未传 |
| AI_OP_400008 | 请求体的参数字段类型错误 | Action、ImageData 字段应该是 string 类型 FaceThresh 字段应该是 float 类型 NeedFaceAngle 字段应该是 bool 类型 |
| AI_OP_400009 | 请求体的参数字段值为空 | Action、ImageData 字段值为空字符 |
| AI_OP_400010 | 请求体的参数字段值设置错误 | Action 值设置错误 FaceThresh 字段不符合规范，请参考接⼝⽂档说明 |
| AI_OP_400011 | base64 数据处理异常 | ImageData 字段的 base64 字符串转换字节码异常 |
| AI_OP_400012 | ⽂件格式不合法 | 仅⽀持 jpeg/png/jpg/bmp 格式 |
| AI_OP_400013 | ⽂件⼤⼩不符合要求 | 该⽂件⼤⼩不符合要求，图⽚要求⼩于 7M |
| AI_OP_410001 | 图⽚解码错误 | 字节码解码为图⽚错误 |
| AI_OP_410002 | 图⽚尺⼨不符合要求 | 分辨率⻓宽尺⼨应不⾼于 5000 不低于 32 |
| AI_OP_500001 | 服务接⼝异常，请联系管理员 | 需要联系管理员处理 |
base64 编码规则：使用常规的 safe base64 编码方式
python 中推荐使用
base64.urlsafe_b64encode()函数进行编码。java 中推荐使用
BASE64.getUrlEncoder().encodeToString()函数进行编码。
