API调用-证件照生成

一、请求信息

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

      请求方式:POST

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

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

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

参数 类型 说明
base64 string, optional base64编码的图片文件,图片需预先缩小到2000*2000以下,需要传入base64或者id
id string, optional 图片id,对于已经请求过的图片,如果需要改变水印,尺寸,颜色等参数,使用id而无需再上传base64
dpi int, optional 生成证件照的dpi,默认为300
quality int, optional 生成证件照的质量,[1, 100],越大生成的证件照文件越大,默认为92
minFileSize int, optional 生成证件照的最小文件大小,[0, inf],比如10240表示最小文件大小为10KB,只有当quality为空时起作用,默认为空
maxFileSize int, optional 生成证件照的最大文件大小,[0, inf],只有当quality为空时起作用,默认为空
bgColor string, required 背景色的16进制表示,常用颜色有:白色:"FFFFFF",红色:"FF0000",蓝色:"438EDB"
bgColor2 string, optional 渐变色的16进制表示,当提供bgColor2时,背景色会从顶部的bgColor渐变到底部的bgColor2,默认为空
pxHeight int, optional 生成证件照的高度(像素),需要传入 (pxHeight, pxWidth) 或者 (mmHeight, mmWidth) 中的一对值
pxWidth int, optional 生成证件照的宽度(像素)
mmHeight int, optional 生成证件照的高度(毫米)
mmWidth int, optional 生成证件照的宽度(毫米)
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_5", "woman_1", ..., "woman_5", 默认为空
changeBg int, optional 0或1,是否抠图换背景,默认为1
preview int, optional 0或1,是否预览,预览有水印,不扣积分,默认为0
watermarkID string, optional 定制化水印id,默认用系统水印
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"
layoutQRCodeData string, optional 排版附加二维码数据,默认为空
layoutQRCodeSize int, optional 排版附加二维码尺寸像素,默认为290

二、返回信息

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

      错误码说明:

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

      合规信息:

参数 说明
qualified 是否合规
has_face 是否检测到人脸
rotation 图片是否旋转90度,180度,或者270度
face_width 生成证件照中人脸宽度
face_height 人脸长度
head_top 头顶至上边距离
eyes_top 眼睛至上边距离
pupil_distance 瞳距
eyes_angle 双眼连线角度
eyes_center_from_left 双眼中心与左边距离
eyes_center_from_bottom 双眼中心与下边距离

三、示例代码

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, 'id': id, 'result_base64': result_base64, 'msg': 'OK', 'info': info}
or
失败:{'code': error_code, 'msg': error_msg}
"""
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);