请求URL:https://www.shiliuai.com/api/id_photo/v1
请求方式:POST
请求参数-请求头(Header):
| 参数 | 类型 | 说明 |
|---|---|---|
| Content-Type | string | application/json |
| APIKEY | string | 您的API KEY |
请求参数-请求内容(Body):
| 分类 | 参数 | 是否必填 | 类型 | 说明 |
|---|---|---|---|---|
| 图片 | ||||
| base64 | 必须填写其中之一 | string | base64编码的图片文件(小于20M),需要传入base64或者id | |
| id | string | 图片id,对于已经请求过的图片,如果需要改变水印,尺寸,颜色等参数,使用id而无需再上传base64 | ||
| 规格 | ||||
| specID | 否 | int | 规格ID,规格对应证件照的尺寸,背景色,人脸尺寸,文件大小,高级合规检测标准,请参考规格列表 | |
| specVersion | 否 | int | 规格版本 | |
| 尺寸 | ||||
| dpi | 否 | int | 生成证件照的dpi,默认为300,最小值10,最大值1000 | |
| pxWidth | 否 | int | 生成证件照的宽度(像素),可传入 (pxWidth, pxHeight) 或者 (mmWidth, mmHeight) 中的一对值,默认为 (295, 413),小于1800像素 | |
| pxHeight | 否 | int | 生成证件照的高度(像素),小于1800像素 | |
| mmWidth | 否 | int | 生成证件照的宽度(毫米),小于180毫米 | |
| mmHeight | 否 | int | 生成证件照的高度(毫米),小于180毫米 | |
| 背景 | ||||
| changeBg | 否 | int | 0或1,是否抠图换背景,默认为1 | |
| transparentBg | 否 | int | 0或1,是否返回透明底证件照,默认为0 | |
| 背景色 | ||||
| bgColor | 否 | string | 背景色的16进制表示,常用颜色有:白色:"FFFFFF",红色:"FF0000",蓝色:"438EDB",默认为白色 | |
| bgColor2 | 否 | string | 渐变色的16进制表示,当提供bgColor2时,背景色会从顶部的bgColor渐变到底部的bgColor2,默认为空 | |
| 人脸尺寸 | ||||
| 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 | 眼睛与上边最大距离(像素) | |
| 美颜 | ||||
| autoBright | 否 | int | 0或1,是否自动调光,默认为0 | |
| brightFactor | 否 | float | [0, 1],调光系数,默认为0.5 | |
| autoSmooth | 否 | int | 0或1,是否自动磨皮,默认为0 | |
| smoothFactor | 否 | float | [0, 1],磨皮系数,默认为0.5 | |
| autoThinFace | 否 | int | 0或1,是否自动瘦脸,默认为0 | |
| thinFaceFactor | 否 | float | [0, 1],瘦脸系数,默认为0.5 | |
| autoSharp | 否 | int | 0或1,是否自动锐化,默认为0 | |
| sharpFactor | 否 | float | [0, 1],锐化系数,默认为0.5 | |
| 换装 | ||||
| clothesID | 否 | string | 换正装,"man_1", ... , "man_20", "woman_1", ..., "woman_20", "child_1", ..., "child_10", 默认为空 | |
| 预览 | ||||
| preview | 否 | int | 0或1,是否预览,预览有水印,不扣积分,默认为0 | |
| watermarkID | 否 | string | 定制化水印id,默认用系统水印 | |
| 文件大小 | ||||
| quality | 否 | int | 生成证件照的质量,[1, 100],越大生成的证件照文件越大,默认为92 | |
| minFileSize | 否 | int | 生成证件照的最小文件大小,[0, inf],比如10240表示最小文件大小为10KB,只有当quality为空时起作用,默认为空 | |
| maxFileSize | 否 | int | 生成证件照的最大文件大小,[0, inf],只有当quality为空时起作用,默认为空 | |
| 标签 | ||||
| addLabel | 否 | int | 0或1,是否在证件照底部加标签,默认为0 | |
| labelText | 否 | string | 证件照底部标签内容,默认为空 | |
| labelHeight | 否 | int | 证件照底部标签高度(像素),默认为30 | |
| 排版 | ||||
| layout | 否 | int | 0或1,是否返回排版,默认为0 | |
| layoutVertical | 否 | int | 0或1,返回横版或竖版排版,默认为横版 | |
| layoutSize | 否 | string | "5inch"或"6inch",排版尺寸五寸或六寸,默认为"5inch" | |
| layoutBgColor | 否 | string | 排版背景色的16进制表示,比如:白色:"FFFFFF",默认为灰色 | |
| layoutQRCodeData | 否 | string | 排版附加二维码数据,默认为空 | |
| layoutQRCodeSize | 否 | int | 排版附加二维码尺寸像素,默认为290 | |
| layoutLabelText | 否 | string | 排版附加文字,换行用\n表示,默认为空 | |
| 合规检测 | ||||
| qualify | 否 | int | 0或1,是否返回普通合规信息,默认为0 | |
| advancedQualify | 否 | int | 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时会有该返回值) |
| request_id | 请求ID,请求的唯一码 |
错误码说明:
| 错误码 | 说明 |
|---|---|
| 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决定);(specID存在由thresholds里的阈值决定) | |
| thresholds | dict | specID存在时返回:用来判断qualified的项目的阈值,有min/max_face_width, min/max_face_height等组成 | |
| 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 | 人脸长度是否合规 | |
| face_left_qualified | bool | 左侧脸颊到左侧边框距离是否合规 | |
| face_right_qualified | bool | 右侧脸颊到右侧边框距离是否合规 | |
| head_top_qualified | bool | 头顶至上边距离是否合规 | |
| chin_top_qualified | bool | 头顶至上边距离是否合规 | |
| eyes_top_qualified | bool | 眼睛至上边距离是否合规 | |
| eyes_angle_qualified | bool | 双眼连线角度是否合规 | |
| 距离与角度 | |||
| face_width | int | 生成证件照中人脸宽度,单位为像素 | |
| face_left | int | 生成证件照中左侧脸颊到左侧边框距离, 单位为像素 | |
| face_right | 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 | 是否合规。(默认)如果无人脸,戴帽子,墨镜,耳机,手机,口罩,模糊,过曝或欠曝,眉毛遮挡,嘴巴张开,则不合规。 注意:其他项目不计入判断。(specID存在)由thresholds里的阈值决定 | |
| thresholds | dict | specID存在时返回:用来判断qualified的项目的阈值,由specID决定 | |
| 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 | 是否右眼遮挡 | |
| 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 | 是否右脸遮挡 | |
| cheek_occlusion | bool | 是否脸颊遮挡,当左脸或右脸遮挡时,该项为True | |
| 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],头发颜色蓝色分量 | |
| hair_dyed_score | float | [0,1],染发程度,决定hair_dyed,默认阈值0.5 | |
| hair_dyed | 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_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],背景颜色蓝色分量 | |
| bg_color_wrong_score | float | [0,1],背景颜色错误,决定bg_color_wrong,默认阈值为0.5 | |
| bg_color_wrong | bool | 是否背景颜色错误 | 图片 |
| image_gray_score | float | [0,1],黑白照片程度,决定image_gray,默认阈值为0.5 | |
| image_gray | 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);