请求信息 / 返回信息 / 示例代码

证件照仅检测

一、请求信息

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

请求方式：POST

请求参数-请求头（Header）：

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

请求参数-请求内容（Body）：

分类	参数	类型	说明
图片
	base64	string, required	base64编码的图片文件（小于15M），需要传入base64或者id
	id	string, required	图片id，对于已经请求过的图片，如果需要改变水印，尺寸，颜色等参数，使用id而无需再上传base64
人脸尺寸
	faceWidth	int, optional	人脸宽度（像素）
	minFaceWidth	int, optional	最小人脸宽度（像素）
	maxFaceWidth	int, optional	最大人脸宽度（像素）
	faceHeight	int, optional	人脸长度（像素）
	minFaceHeight	int, optional	最小人脸长度（像素）
	maxFaceHeight	int, optional	最大人脸长度（像素）
	headTop	int, optional	头顶与上边距离（像素）
	minHeadTop	int, optional	头顶与上边最小距离（像素）
	maxHeadTop	int, optional	头顶与上边最大距离（像素）
	eyesTop	int, optional	眼睛与上边距离（像素）
	minEyesTop	int, optional	眼睛与上边最小距离（像素）
	maxEyesTop	int, optional	眼睛与上边最大距离（像素）
合规检测
	qualify	int, optional	0或1，是否返回普通合规信息，默认为1
	advancedQualify	int, optional	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	合规消息（中文）
has_face	bool	是否检测到人脸
rotation	int	图片旋转角度（0度，90度，180度，或者270度）
face_width_qualified	bool	人脸宽度是否合规
face_height_qualified	bool	人脸长度是否合规
head_top_qualified	bool	头顶至上边距离是否合规
eyes_top_qualified	bool	眼睛至上边距离是否合规
eyes_angle_qualified	bool	双眼连线角度是否合规
face_width	int	生成证件照中人脸宽度
face_height	int	人脸长度
head_top	int	头顶至上边距离
eyes_top	int	眼睛至上边距离
eyes_angle	float	双眼连线角度
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	原图人脸个数
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，是否戴项链
face_blur_score	float	[0, 1]，脸部模糊程度，决定face_blur，默认阈值为0.6
face_blur	bool	是否脸部模糊
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	是否脸部欠曝
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	是否耳朵遮挡
mouth_open_score	float	[0, 1]，嘴巴张开程度，决定mouth_open，默认阈值为0.1
mouth_open	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	是否右脸遮挡
yaw	float	[-90, 90]，原图人脸偏航角
pitch	float	[-90, 90]，原图人脸俯仰角
roll	float	[-90, 90]，原图人脸翻滚角
hair_incomplete_score	float	[0, 1]，头发不完整程度，决定hair_incomplete，默认阈值为0.1
hair_incomplete	bool	是否头发不完整
shoulder_incomplete_score	float	[0, 1]，肩膀不完整程度，决定shoulder_incomplete，默认阈值为0.5
shoulder_incomplete	bool	是否肩膀不完整
clothes_color_light_score	float	[0, 1]，衣服浅色程度，决定clothes_color_light，默认阈值为0.75
clothes_color_light	bool	是否浅色衣服
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_straight	bool	是否目光平视前方，当视线没有水平和竖直偏移时，为True

三、示例代码

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);