证件照仅检测

一、请求信息

      请求URL:https://www.shiliuai.com/api/id_photo/v1/qualify

      请求方式:POST

      请求参数-请求头(Header):

参数 类型 说明
Content-Type string application/json
APIKEY string 您的API KEY

      请求参数-请求内容(Body):

分类 参数 是否必填 类型 说明
图片
base64 必须填写其中之一 string base64编码的图片文件(小于15M),需要传入base64或者id
id string 图片id,对于已经请求过的图片,如果需要改变水印,尺寸,颜色等参数,使用id而无需再上传base64
规格
specID int 规格ID,规格对应证件照的尺寸,背景色,人脸尺寸,文件大小,高级合规检测标准,请参考规格列表
specVersion int 规格版本
人脸尺寸
faceWidth int 人脸宽度(像素)
minFaceWidth int 最小人脸宽度(像素)
maxFaceWidth int 最大人脸宽度(像素)
faceHeight int 人脸长度(像素)
minFaceHeight int 最小人脸长度(像素)
maxFaceHeight int 最大人脸长度(像素)
headTop int 头顶与上边距离(像素)
minHeadTop int 头顶与上边最小距离(像素)
maxHeadTop int 头顶与上边最大距离(像素)
chinTop int 头顶与上边距离(像素)
minChinTop int 头顶与上边最小距离(像素)
maxChinTop int 头顶与上边最大距离(像素)
eyesTop int 眼睛与上边距离(像素)
minEyesTop int 眼睛与上边最小距离(像素)
maxEyesTop int 眼睛与上边最大距离(像素)
合规检测
qualify int 0或1,是否返回普通合规信息,默认为1
advancedQualify int 0或1,是否返回高级合规信息,默认为1

二、返回信息

参数 说明
code 错误码
msg 错误信息(英文)
msg_cn 错误信息(中文)
id 图片id,用于同一张图片的多次请求,id的有效时间为6小时,(当code==0时会有该返回值)
info 普通合规信息,(当code==0且请求参数qualify==1时会有该返回值)
advanced_info 高级合规信息,(当code==0且请求参数advancedQualify==1时会有该返回值)

      错误码说明:

错误码 说明
0 成功
1 图片错误
3 服务器繁忙
4 参数错误,具体错误看msg或msg_cn
6 未知错误
7 图片id无效,可能已过期
101 API-KEY不正确
102 未知用户
103 积分已用完
104 扣除积分失败

      普通合规信息:

分类 参数 类型 说明
综合
qualified bool 是否合规(由face_width, face_height, head_top, eyes_top, eyes_angle决定)
msg string 合规消息(英文)
msg_cn string 合规消息(中文)
尺寸
width int 证件照宽度,单位为像素
height int 证件照高度,单位为像素
人脸
has_face bool 是否检测到人脸
face_count int 原图人脸数
rotation int 图片旋转角度(0度,90度,180度,或者270度)
判断
face_width_qualified bool 人脸宽度是否合规
face_height_qualified bool 人脸长度是否合规
head_top_qualified bool 头顶至上边距离是否合规
chin_top_qualified bool 头顶至上边距离是否合规
eyes_top_qualified bool 眼睛至上边距离是否合规
eyes_angle_qualified bool 双眼连线角度是否合规
距离与角度
face_width int 生成证件照中人脸宽度,单位为像素
face_height int 人脸长度,单位为像素
head_top int 头顶至上边距离,单位为像素
chin_top int 头顶至上边距离,单位为像素
eyes_top int 眼睛至上边距离,单位为像素
eyes_angle float [-pi/2, pi/2],双眼连线角度
pupil_distance int 瞳距,单位为像素
eyes_center_from_left int 双眼中心与左边距离,单位为像素
eyes_center_from_bottom int 双眼中心与下边距离,单位为像素

      高级合规信息:

分类 参数 类型 说明
综合
qualified bool 是否合规,如果无人脸,戴帽子,墨镜,耳机,手机,口罩,模糊,过曝或欠曝,眉毛遮挡,嘴巴张开,则不合规。 注意:其他项目不计入判断。
msg string 合规消息(英文)
msg_cn string 合规消息(中文)
人脸
has_face bool 是否检测到人脸
face_count int 原图人脸个数
姿势
yaw float [-90, 90],人脸偏航角,决定pose_abnormal
pitch float [-90, 90],人脸俯仰角,决定pose_abnormal
roll float [-90, 90],人脸翻滚角,决定pose_abnormal
pose_abnormal bool 人脸角度异常,如果abs(yaw)>10,或者abs(pitch)>15,或者abs(roll)>10,那么为True
质量
face_overexposed_score float [0, 1],脸部过曝程度,决定face_overexposed,默认阈值为0.5
face_overexposed bool 是否脸部过曝
face_underexposed_score float [0, 1],脸部欠曝程度,决定face_underexposed,默认阈值为0.5
face_underexposed bool 是否脸部欠曝
face_exposure_uneven_score float [0, 1],阴阳脸程度,决定face_exposure_uneven,默认阈值为0.2
face_exposure_uneven bool 是否阴阳脸
face_blur_score float [0, 1],脸部模糊程度,决定face_blur,默认阈值为0.6
face_blur bool 是否脸部模糊
face_dark_score float [0, 1],脸部过暗程度,决定face_blur,默认阈值为0.5
face_dark bool 是否脸部过暗
face_color_abnormal_score float [0, 1],脸部肤色不正常程度,决定face_blur,默认阈值为0.5
face_color_abnormal bool 是否脸部肤色不正常
image_gray_score float [0, 1], 黑白照片程度,默认阈值为0.5
image_gray bool 是否黑白照片
face_glare_score float [0,1], 脸部反光程度,默认阈值为0.5
face_glare bool 是否脸部反光
遮挡
left_eye_occlusion_score float [0, 1],左眼遮挡程度,决定left_eye_occlusion,默认阈值为0.2
left_eye_occlusion bool 是否左眼遮挡
right_eye_occlusion_score float [0, 1],右眼遮挡程度,决定right_eye_occlusion,默认阈值为0.2
right_eye_occlusion bool 是否右眼遮挡
mouth_occlusion_score float [0, 1],嘴巴遮挡程度,决定mouth_occlusion,默认阈值为0.2
mouth_occlusion bool 是否嘴巴遮挡
nose_occlusion_score float [0, 1],鼻子遮挡程度,决定nose_occlusion,默认阈值为0.2
nose_occlusion bool 是否鼻子遮挡
left_cheek_occlusion_score float [0, 1],左脸遮挡程度,决定left_cheek_occlusion,默认阈值为0.3
left_cheek_occlusion bool 是否左脸遮挡
right_cheek_occlusion_score float [0, 1],右脸遮挡程度,决定right_cheek_occlusion,默认阈值为0.3
right_cheek_occlusion bool 是否右脸遮挡
eyebrow_occlusion_score float [0, 1],眉毛遮挡程度,决定eyebrow_occlusion,默认阈值为0.3
eyebrow_occlusion bool 是否眉毛遮挡
ear_occlusion_score float [0, 1],耳朵遮挡程度,决定ear_occlusion,默认阈值为0.8
ear_occlusion bool 是否耳朵遮挡
头发
hair_incomplete_score float [0, 1],头发不完整程度,决定hair_incomplete,默认阈值为0.1
hair_incomplete bool 是否头发不完整
hair_color_r float [0, 255],头发颜色红色分量
hair_color_g float [0, 255],头发颜色绿色分量
hair_color_b float [0, 255],头发颜色蓝色分量
眼睛
eye_close_score float [0, 1],闭眼程度,决定eye_close,默认阈值为0.5
eye_close bool 是否闭眼
gaze_horizontal_score float [0, 1],视线水平偏移程度,决定gaze_horizontal,默认阈值为0.15
gaze_horizontal bool 是否视线水平偏移
gaze_vertical_score float [0, 1],视线竖直偏移程度,决定gaze_vertical,默认阈值为0.1
gaze_vertical bool 是否视线竖直偏移
gaze_abnormal bool 是否目光没有平视前方,当视线有水平和竖直偏移时,为True
red_eye_score float [0, 1],红眼程度,决定red_eye,默认阈值为0.5
red_eye bool 是否红眼
colored_contacts_score float [0, 1],有色隐形眼镜分数,决定colored_contacts,默认阈值为0.5
colored_contacts bool 是否戴有色隐形眼镜
耳朵
ears_asymmetric_score float [0, 1],双耳不对称程度,决定ears_asymmetric,默认阈值为0.5
ears_asymmetric bool 是否双耳不对称
嘴巴
mouth_open_score float [0, 1],嘴巴张开程度,决定mouth_open,默认阈值为0.1
mouth_open bool 是否嘴巴张开
饰品
hat int 0或1,是否戴帽子
glasses int 0或1,是否戴眼镜
sunglasses int 0或1,是否戴墨镜
headphone int 0或1,是否戴耳机
earphone int 0或1,是否戴耳塞
cellphone int 0或1,是否用手机
earring int 0或1,是否戴耳饰
mask int 0或1,是否戴口罩
necklace int 0或1,是否戴项链
glasses_glare_score float [0, 1],眼镜反光程度,决定glasses_glare,默认阈值为0.5
glasses_glare bool 是否眼镜反光
heavy_makeup_score float [0, 1],浓妆程度,决定heavy_makeup,默认阈值为0.5
heavy_makeup bool 是否浓妆
肩膀
shoulder_incomplete_score float [0, 1],肩膀不完整程度,决定shoulder_incomplete,默认阈值为0.5
shoulder_incomplete bool 是否肩膀不完整
shoulder_imbalance_score float [0, 1],肩膀不平衡程度,决定shoulder_imbalance,默认阈值为0.5
shoulder_imbalance bool 是否肩膀不平衡
衣服
clothes_color_r float [0, 255],衣服颜色红色分量
clothes_color_g float [0, 255],衣服颜色绿色分量
clothes_color_b float [0, 255],衣服颜色蓝色分量
clothes_color_light_score float [0, 1],衣服浅色程度,决定clothes_color_light,默认阈值为0.75
clothes_color_light bool 是否浅色衣服
clothes_bg_similar_score float [0, 1],衣服背景颜色相近程度,决定clothes_bg_similar,默认阈值为0.8
clothes_bg_similar bool 是否衣服背景颜色相近
shirtless_score float [0, 1],光膀程度,决定shirtless,默认阈值为0.5
shirtless bool 是否光膀
sleeveless_score float [0, 1],背心或吊带分数,决定sleeveless,默认阈值为0.5
sleeveless bool 是否穿背心或吊带
big_clothes_score float [0, 1],臃肿外套分数,决定big_clothes,默认阈值为0.5
big_clothes bool 是否穿臃肿外套
背景
bg_color_r float [0, 255],背景颜色红色分量
bg_color_g float [0, 255],背景颜色绿色分量
bg_color_b float [0, 255],背景颜色蓝色分量

三、示例代码

Python 代码示例:

import requests
import base64
import cv2
import json
import numpy as np


api_key = '******'  # 你的API KEY
file_path = '...'  # 图片路径

with open(file_path, 'rb') as fp:
    photo_base64 = base64.b64encode(fp.read()).decode('utf8')

url = 'https://www.shiliuai.com/api/id_photo/v1/qualify'
headers = {'APIKEY': api_key, "Content-type": "application/json"}
data = {
    "base64": photo_base64,
    "qualify": 1,
    "advancedQualify": 1
    }

response = requests.post(url=url, headers=headers, json=data)
response = json.loads(response.content)
"""
成功:{'code': 0, 'msg': 'OK', 'msg_cn': '成功', 'id': id, 'info': info, 'advanced_info': advanced_info}
or
失败:{'code': error_code, 'msg': error_msg, 'msg_cn': 错误信息}
"""
                            

PHP 代码示例:

$url = "https://www.shiliuai.com/api/id_photo/v1/qualify";
$method = "POST";
$apikey = "******";
$header = array();
array_push($header, "APIKEY:" . $apikey);
array_push($header, "Content-Type:application/json");

$file_path = "...";
$handle = fopen($file_path, "r");
$photo = fread($handle, filesize($file_path));
fclose($handle);
$photo_base64 = base64_encode($photo);

$data = array(
  "base64"=> $photo_base64,
  "qualify"=> 1,
  "advancedQualify"=> 1
);
$post_data = json_encode($data);

$curl = curl_init();
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
curl_setopt($curl, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);

$response = curl_exec($curl);
var_dump($response);