1、接口描述
判断人脸图像是否正面、清晰、完整。
2、请求方法
POST
3、接口要求
- 输入单张包含人脸的图片
- 图片尺寸限制:最大输入图片宽度不大于960px,高度不大于1280px
- 图片格式限制:支持jpg/png/bmp图片格式
4、URI
/v1/aiop/api/2gkds6yod62o/face-fas-action/person/quality_detect_from_base64
5、请求参数
请求头header参数
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
Content-Type | 是 | String | json 格式 | application/json | |
appkey | 是 | String | 诸葛 AI 应用 appkey | 562b89493b1a40e1b97ea05e50dd8170 | |
ctyun-eop-request-id | 是 | String | 用户请求 id,由用户构造,用户可以通过 uuid 等方法自行生成唯一字符串,用于日志请求追踪。 详见文档:API参考-如何调用API-Python3 调用示例 |
33dfa732-b27b-464f-b15a-21ed6845afd5 | |
eop-date | 是 | String | 请求时间,由用户构造,形如 yyyymmddTHHMMSSZ。 详见文档:API参考-如何调用API-Python3 调用示例 |
20211221T163014Z | |
host | 是 | String | 终端节点域名,固定字段 | ai-global.ctapi.ctyun.cn | |
Eop-Authorization | 是 | String | 由天翼云官网 accessKey 和 securityKey 经签名后生成,参与签名生成的字段包括天翼云官网 accessKey 、securityKey、诸葛AI平台的 appkey(非必须),用户请求 id(非必须),请求时间,终端节点域名(非必须)以及请求体内容。 签名逻辑详见文档:API参考-如何调用API-认证鉴权和Python3 调用示例 |
请求体body参数
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
imageContent | 是 | String | 传入图片的base64编码,图片使用常规的base64编码方式,编码后,不包含前缀,剔除前缀例如 "data:image/jpeg;base64," | - |
6、请求代码示例
Curl -X POST "https://ai-global.ctapi.ctyun.cn/v1/aiop/api/2gkds6yod62o/face-fas-action/person/quality_detect_from_base64"
-H "Content-Type: application/json"
-H "ctyun-eop-request-id:33dfa732-b27b-464f-b15a-21ed6845afd5"
-H "appkey:XXX"
-H "Eop-Authorization:XXX"
-H "eop-date:20211109T104641Z"
-H "host:ai-global.ctapi.ctyun.cn"
--data '{"imageContent":"9j_4AAQSkZJRgABAQAAAQABAAD_4QAwRXhpZgAATU0AKgAAA..."}'
7、返回值说明
请求成功返回响应参数
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
statusCode | 是 | String | 返回状态,返回 0 表示成功,返回错误代码参考下面的错误代码列表。 | 0 | |
message | 是 | String | 如果 code 为 0,返回 success;如果 code 非 0,则返回对应的可读错误信息。 | success | |
returnObj | 是 | Object | 返回结果键值集合,键为人脸质量 "face_quality" | returnObj |
表result
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
face_quality | 是 | string | 值为人脸图片的质量检测结果,分为“good”、"medium"、“bad" | good |
请求失败返回响应参数
参数 | 是否必填 | 参数类型 | 说明 | 示例 | 下级对象 |
---|---|---|---|---|---|
statusCode | 是 | string | 错误码,放置API对应的错误码 | 4201 | |
message | 是 | string | 请求失败时返回值固定为"error" | error | |
details | 是 | string | 返回对应的错误信息 | 请求内容错误 | |
error | 是 | string | 返回对应的错误码 | AI_OP_4201 |
8、返回值示例
请求成功返回值示例
{
"statusCode": 0,
"message": "success",
"returnObj": {
"face_quality": "good"
}
}
请求失败返回值示例
{
"statusCode": "4204",
"message": "error",
"details": "人脸探测异常, 请确保为真实人脸!",
"error":"AI_OP_4204"
}
9、状态码
http状态码 | 描述 |
---|---|
200 | 表示请求成功 |
10、错误码说明
4 位错误码。4 开头为业务错误码,5 开头为服务错误码。
错误码 | 错误信息 | 错误描述 |
---|---|---|
AI_OP_4201 | 请求内容错误 | 传入内容为空,或者传入的参数名错误 |
AI_OP_4202 | 请求参数格式错误 | 参数格式不满足要求 |
AI_OP_4203 | 图片解码失败 | 图片为空,base64编码有误,或图片格式不支持 |
AI_OP_4204 | 人脸探测异常, 请确保为真实人脸! | 用户摄像头拍到照片或屏幕上的非活体人脸。 或用户处于逆光等光照条件差的环境下。 |
AI_OP_4205 | 所上传图片尺寸过大 | 编码前的原始图片宽高大于设定阈值 |
AI_OP_4210 | 有图片解码失败 | 在检测到动作之前检测到存在编码错误的图片 |
AI_OP_4212 | 请正对摄像头, 请避免逆光环境!(或 未检测到人脸) | 上传图片序列中,有图片不包含人脸。 或用户处于逆光等光照条件差的环境下。 |
AI_OP_4213 | 有图片包含多张人脸 | 用户摄像头拍摄到多人人脸 |
AI_OP_5000 | 服务内部错误,请联系管理员 | 接口服务出现未知错误,请联系管理员解决 |
11、base64 编码规则:使用常规的 safe base64 编码方式
- python 中推荐使用
base64.urlsafe_b64encode()
函数进行编码。 - java 中推荐使用
BASE64.getUrlEncoder().encodeToString()
函数进行编码。