API调用-证件照制作+检测

一、请求信息

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

请求方式：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
尺寸
	dpi	int, optional	生成证件照的dpi，默认为300，最大值1000
	pxWidth	int, optional	生成证件照的宽度（像素），可传入 (pxWidth, pxHeight) 或者 (mmWidth, mmHeight) 中的一对值，默认为 (295, 413)，小于1800像素
	pxHeight	int, optional	生成证件照的高度（像素），小于1800像素
	mmWidth	int, optional	生成证件照的宽度（毫米），小于180毫米
	mmHeight	int, optional	生成证件照的高度（毫米），小于180毫米
背景色
	changeBg	int, optional	0或1，是否抠图换背景，默认为1
	transparentBg	int, optional	0或1，是否返回透明底证件照，默认为0
	bgColor	string, optional	背景色的16进制表示，常用颜色有：白色："FFFFFF"，红色："FF0000"，蓝色："438EDB"，默认为白色
	bgColor2	string, optional	渐变色的16进制表示，当提供bgColor2时，背景色会从顶部的bgColor渐变到底部的bgColor2，默认为空
人脸尺寸
	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	眼睛与上边最大距离（像素）
美颜
	autoBright	int, optional	0或1，是否自动调光，默认为0
	brightFactor	float, optional	[0, 1]，调光系数，默认为0.5
	autoSmooth	int, optional	0或1，是否自动磨皮，默认为0
	smoothFactor	float, optional	[0, 1]，磨皮系数，默认为0.5
	autoThinFace	int, optional	0或1，是否自动瘦脸，默认为0
	thinFaceFactor	float, optional	[0, 1]，瘦脸系数，默认为0.5
	autoSharp	int, optional	0或1，是否自动锐化，默认为0
	sharpFactor	float, optional	[0, 1]，锐化系数，默认为0.5
换装
换装	clothesID	string, optional	换正装，"man_1", ... , "man_20", "woman_1", ..., "woman_20", "child_1", ..., "child_10"，默认为空
预览
	preview	int, optional	0或1，是否预览，预览有水印，不扣积分，默认为0
	watermarkID	string, optional	定制化水印id，默认用系统水印
文件大小
	quality	int, optional	生成证件照的质量，[1, 100]，越大生成的证件照文件越大，默认为92
	minFileSize	int, optional	生成证件照的最小文件大小，[0, inf]，比如10240表示最小文件大小为10KB，只有当quality为空时起作用，默认为空
	maxFileSize	int, optional	生成证件照的最大文件大小，[0, inf]，只有当quality为空时起作用，默认为空
标签
	addLabel	int, optional	0或1，是否在证件照底部加标签，默认为0
	labelText	string, optional	证件照底部标签内容，默认为空
	labelHeight	int, optional	证件照底部标签高度（像素），默认为30
排版
	layout	int, optional	0或1，是否返回排版，默认为0
	layoutVertical	int, optional	0或1，返回横版或竖版排版，默认为横版
	layoutSize	string, optional	"5inch"或"6inch"，排版尺寸五寸或六寸，默认为"5inch"
	layoutBgColor	string, optional	排版背景色的16进制表示，比如：白色："FFFFFF"，默认为灰色
	layoutQRCodeData	string, optional	排版附加二维码数据，默认为空
	layoutQRCodeSize	int, optional	排版附加二维码尺寸像素，默认为290
	layoutLabelText	string, optional	排版附加文字，换行用\n表示，默认为空
合规检测
	qualify	int, optional	0或1，是否返回普通合规信息，默认为0
	advancedQualify	int, optional	0或1，是否返回高级合规信息，默认为0

二、返回信息

参数	说明
code	错误码
msg	错误信息（英文）
msg_cn	错误信息（中文）
id	图片id，用于同一张图片的多次请求，id的有效时间为6小时，（当code==0时会有该返回值）
result_base64	证件照的base64编码，（当code==0时会有该返回值）
layout_base64	排版的base64编码，（当code==0且请求参数layout==1时会有该返回值）
info	普通合规信息，（当code==0且请求参数qualify==1时会有该返回值）
advanced_info	高级合规信息，（当code==0且请求参数advancedQualify==1时会有该返回值）

错误码说明：

错误码	说明
0	成功
1	图片错误
2	抠图错误
3	服务器繁忙
4	参数错误，具体错误看msg或msg_cn
5	换装时没检测到人脸
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	是否检测到人脸
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	是否嘴巴张开

三、示例代码

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'
headers = {'APIKEY': api_key, "Content-type": "application/json"}
data = {
    "base64": photo_base64,
    "bgColor": "FFFFFF",
    "dpi": 300,
    "mmHeight": 35,
    "mmWidth": 25
    }

response = requests.post(url=url, headers=headers, json=data)
response = json.loads(response.content)
"""
成功：{'code': 0, 'msg': 'OK', 'msg_cn': '成功', 'id': id, 'result_base64': result_base64}
or
失败：{'code': error_code, 'msg': error_msg, 'msg_cn': 错误信息}
"""
result_base64 = response['result_base64']
id = response['id']
file_bytes = base64.b64decode(result_base64)
f = open('result.jpg', 'wb')
f.write(file_bytes)
f.close()

image = np.asarray(bytearray(file_bytes), dtype=np.uint8)
image = cv2.imdecode(image, cv2.IMREAD_COLOR)
cv2.imshow('result', image)
cv2.waitKey(0)

# 同一张图片，参数改变，再次请求
data = {
    "id": id,
    "bgColor": "FF0000",
    "dpi": 300,
    "pxHeight": 640,
    "pxWidth": 480,
    }
response = requests.post(url=url, headers=headers, json=data)
response = json.loads(response.content)

PHP 代码示例：

$url = "https://www.shiliuai.com/api/id_photo/v1";
$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,
  "bgColor"=>"FFFFFF",
  "dpi"=>300,
  "mmHeight"=>35,
  "mmWidth"=>25
);
$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);