接口描述
用于检测输入图像中的人脸，输出人脸位置坐标。
请求方法
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 | |
| NeedFaceQuality | 否 | Bool | 是否返回⼈脸质量信息。 默认为 False，不返回⼈脸质量。 若该值设为 True，则返回⼈脸质量。 | ||
| NeedFaceAngle | 否 | Bool | 是否返回⼈脸⻆度信息。 默认为 False，不返回⼈脸⻆度。 若该值设为 True，则返回⼈脸⻆度。 |
请求代码示例
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, "NeedFaceQuality": true,"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 | ⼈脸位置信息（2 维数组）。 位置信息包括 box = [left, top, width, height]。 如有两个框，则返回 [box1, box2]，数组的维度 为 2 x 4，以此类推 | [[741, 117, 45, 72], [567, 148, 45, 60]] | |
| DetectScores | Array | ⼈脸检测分数（1 维数组）。 每个检测框返回⼀个分数 score，取值范围 [0,1]。 如有两个框，则返回 [score1, score2]，数组的 维度为 1 x 2，以此类推 | [0.9974, 0.9964] | |
| DetectClses | Array | ⼈脸检测类别（1 维数组）。 每个检测框返回⼀个类别 cls。 如有两个框，则返回 [cls1, cls2]，数组的维度 为 1 x 2，以此类推。 类别为 face 表示⼈脸 | ["face", "face"] | |
| LandmarkCount | Int | ⼈脸关键点数⽬。 单个⼈脸关键点固定为 5 点。 关键点包括眼睛 2 点，⿐⼦ 1 点，嘴巴 2 点 | 5 | |
| Landmarks | Array | 人脸关键点位置信息（2 维数组）。 每个⼈脸返回⼀组关键点坐标 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] ] | |
| FaceQualities | Array | ⼈脸质量信息（1 维数组）。 仅当请求时 NeedFaceQuality=True 才返回。 每个⼈脸返回⼀个质量 quality，分数越⾼质量 越好，取值范围 [0, 100]。 如有两个⼈脸，则返回 [quality1, quality2]，数 组的维度为 1 x 2，以此类推 | [30.938, 0.538] | |
| FaceAngles | Array | ⼈脸⻆度信息（2 维数组）。 仅当请求时 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] |
3.请求失败返回响应参数
| 参数 | 参数类型 | 说明 | 示例 | 下级对象 |
|---|---|---|---|---|
| statusCode | String | 错误码，放置API对应的错误码 | 500001 | |
| message | String | 请求失败时返回值固定为"error" | error | |
| 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]],
'FaceQualities': [45.562],
'LandmarkCount': 5,
'Landmarks': [[1214,
290,
1335,
289,
1273,
380,
1235,
407,
1319,
407]]}
}2.请求失败返回示例
{
"statusCode": "4101",
"message": "error",
"details": "请求内容错误",
"error":"AI_OP_4101"
}错误码说明
6 位错误码。4 开头为业务错误码，5 开头为服务错误码。
| 错误码 | 错误信息 | 错误描述 |
|---|---|---|
| 400001 | 请求路径错误 | 请求路径错误 |
| 400002 | 请求⽅法错误 | 请求⽅法错误，请使⽤ POST 请求 |
| 400003 | 请求体内容为空 | 请求体请求数据为空，没有包含内容 |
| 400004 | 请求体⾮ json 格式 | 请求体内容需要符合 json 要求 |
| 400005 | 请求体类型错误 | 请求体需为字典，不能为其他类型 |
| 400006 | 必传的参数未传 | 必须的参数（Action、ImageData）未传 |
| 400008 | 请求体的参数字段类型错误 | Action、ImageData 字段应该是 string 类型 FaceThresh 字段应该是 float 类型 NeedFaceQuality 字段应该是 bool 类型 NeedFaceAngle 字段应该是 bool 类型 |
| 400009 | 请求体的参数字段值为空 | Action、ImageData 字段值为空字符 |
| 400010 | 请求体的参数字段值设置错误 | Action 值设置错误 FaceThresh 字段不符合规范，请参考接⼝⽂档说明 |
| 400011 | base64 数据处理异常 | ImageData 字段的 base64 字符串转换字节码异常 |
| 400012 | ⽂件格式不合法 | 仅⽀持 jpeg/png/jpg/bmp 格式 |
| 400013 | ⽂件⼤⼩不符合要求 | 该⽂件⼤⼩不符合要求，图⽚要求⼩于 7M |
| 410001 | 图⽚解码错误 | 字节码解码为图⽚错误 |
| 410002 | 图⽚尺⼨不符合要求 | 分辨率⻓宽尺⼨应不⾼于 5000 不低于 32 |
| 500001 | 服务接⼝异常，请联系管理员 | 需要联系管理员处理 |
base64 编码规则：使用常规的 safe base64 编码方式
python 中推荐使用
base64.urlsafe_b64encode()函数进行编码。java 中推荐使用
BASE64.getUrlEncoder().encodeToString()函数进行编码。
