1. 接口说明
结婚证件照制作接口 API:基于自研深度学习算法与图像处理技术,实现从普通生活照一键生成结婚证件照。接口内部集成人脸检测、人像裁剪、背景抠除与颜色替换、美颜处理以及排版打印能力,开发者只需上传原始照片及少量参数,即可获得符合规格要求的结婚证件照成品。
1.1 主要功能
- 全规格支持:
- 可自定义证件照宽高(像素或毫米)、DPI 分辨率、目标文件大小(KB),满足不同结婚证件照规格需求。
- 智能抠图与换底:
- 自动识别人像并完成精细抠图,可将背景替换为指定纯色或渐变色,常用背景包括红色、蓝色、白色等。
- 美颜与质量增强:
- 支持自动与自定义参数的磨皮、瘦脸、调光、锐化等操作,提升结婚证件照观感与清晰度。
- 预览与加水印:
- 可通过参数开启预览模式,加水印展示生成效果,不扣积分,方便前端交互体验与效果确认。
- 排版打印:
- 支持返回 5 寸或 6 寸相纸排版图,便于线下冲印结婚证件照。
1.2 接入场景
适用于结婚登记预约平台、小程序/APP 中的结婚证件照拍摄与制作、婚庆服务机构的证件照增值服务,以及线下自助终端的结婚证件照快速生成等场景。
2. 请求信息
2.1 请求地址(URL)
POST https://api.shiliuai.com/api/id_photo/v1/couple
2.2 请求方式
POST
2.3 请求头(header)
| 参数 | 类型 | 说明 |
|---|---|---|
| Content-Type | string | application/json |
| APIKEY | string | 您的 API KEY |
2.4 请求体(body)
| 参数 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
| 图片 | |||
| base64 | 必须填写其中之一 | string | base64 编码的图片文件(小于 20M),需要传入 base64 或者 id |
| id | string | 图片 id,对于已经请求过的图片,如果需要改变水印、尺寸、颜色等参数,可直接使用 id 而无需再次上传 base64 | |
| 尺寸 | |||
| dpi | 否 | int | 生成证件照的 DPI,默认为 300,最大值 1000 |
| pxWidth | 否 | int | 生成证件照宽度(像素),可与 pxHeight 搭配,或与毫米尺寸互斥,默认 (295, 413),小于 1800 像素 |
| pxHeight | 否 | int | 生成证件照高度(像素),小于 1800 像素 |
| mmWidth | 否 | int | 生成证件照宽度(毫米),小于 180 毫米 |
| mmHeight | 否 | int | 生成证件照高度(毫米),小于 180 毫米 |
| 背景色 | |||
| changeBg | 否 | int | 0 或 1,是否抠图换背景,默认为 1 |
| bgColor | 否 | string | 背景色 16 进制表示,常用颜色:白色 "FFFFFF",红色 "FF0000",蓝色 "438EDB",默认为白色 |
| 美颜 | |||
| 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 |
| 预览 | |||
| preview | 否 | int | 0 或 1,是否仅预览。预览图有水印且不扣积分,默认为 0 |
| watermarkID | 否 | string | 定制化水印 id,默认使用系统水印 |
| 文件大小 | |||
| quality | 否 | int | 生成证件照质量,[1, 100],数值越大文件越大,默认为 92 |
| minFileSize | 否 | int | 最小文件大小(KB),例如 10240 表示 10KB,仅在 quality 为空时生效 |
| maxFileSize | 否 | int | 最大文件大小(KB),仅在 quality 为空时生效 |
| 排版 | |||
| layout | 否 | int | 0 或 1,是否返回排版图,默认为 0 |
| layoutVertical | 否 | int | 0 或 1,返回横版或竖版排版,默认为横版 |
| layoutSize | 否 | string | "5inch" 或 "6inch",排版尺寸为五寸或六寸,默认为 "5inch" |
3. 返回信息
3.1 返回类型
JSON
3.2 返回字段
| 参数 | 说明 |
|---|---|
| code | 错误码 |
| msg | 错误信息(英文) |
| msg_cn | 错误信息(中文) |
| id | 图片 id,当 code==0 时返回 |
| result_base64 | 结婚证件照成品的 base64 编码,当 code==0 时返回 |
| layout_base64 | 排版图的 base64 编码,当 code==0 且请求参数 layout==1 时返回 |
3.3 返回示例
{
"code": 0,
"msg": "OK",
"msg_cn": "成功",
"id": "xxxxxx",
"result_base64": "结婚证件照 base64 数据",
"layout_base64": "结婚证件照排版 base64 数据(当请求参数 layout==1 时返回)"
}
3.4 错误码说明
| 错误码 | 说明 |
|---|---|
| 0 | 成功 |
| 1 | 图片错误 |
| 2 | 抠图错误 |
| 3 | 服务器繁忙 |
| 4 | 参数错误,具体错误请参考 msg 或 msg_cn |
| 6 | 未知错误 |
| 7 | 图片 id 无效,可能已过期 |
| 8 | 图片人脸数不是 2(结婚证件照通常为两人合照) |
| 101 | API-KEY 不正确 |
| 102 | 未知用户 |
| 103 | 积分已用完 |
| 104 | 扣除积分失败 |
4. 示例代码
4.1 Python
# -*- coding: utf-8 -*-
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://api.shiliuai.com/api/id_photo/v1/couple'
headers = {'APIKEY': api_key, "Content-Type": "application/json"}
data = {
"base64": photo_base64,
}
response = requests.post(url=url, headers=headers, json=data)
response = json.loads(response.content)
"""
成功:{'code': 0, 'msg': 'OK', 'msg_cn': '成功', 'id': image_id, 'result_base64': result_base64}
or
失败:{'code': error_code, 'msg': error_msg, 'msg_cn': 错误信息}
"""
result_base64 = response['result_base64']
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_UNCHANGED)
cv2.imshow('result', image)
cv2.waitKey(0)
4.2 PHP
<?php
$url = "https://api.shiliuai.com/api/id_photo/v1/couple";
$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,
);
$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);
4.3 Java
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.file.Files;
import java.util.Base64;
import org.json.JSONObject;
public class CoupleIDPhotoAPIExample {
public static void main(String[] args) {
String apiKey = "******"; // 你的API KEY
String filePath = "path/to/your/image.jpg"; // 图片路径
try {
// 读取图片并编码为 Base64
byte[] fileBytes = Files.readAllBytes(new File(filePath).toPath());
String photoBase64 = Base64.getEncoder().encodeToString(fileBytes);
// API 请求的 URL
String apiUrl = "https://api.shiliuai.com/api/id_photo/v1/couple";
// 请求参数
JSONObject requestData = new JSONObject();
requestData.put("base64", photoBase64);
// 发送 POST 请求
JSONObject response = sendPostRequest(apiUrl, apiKey, requestData);
// 检查响应是否成功
if (response.getInt("code") == 0) {
String resultBase64 = response.getString("result_base64");
// 解码并保存图片
byte[] resultBytes = Base64.getDecoder().decode(resultBase64);
try (FileOutputStream fos = new FileOutputStream("result_couple.jpg")) {
fos.write(resultBytes);
}
System.out.println("结婚证件照生成成功,文件已保存为 result_couple.jpg");
} else {
System.out.println("请求失败: " + response.getString("msg_cn"));
}
} catch (Exception e) {
e.printStackTrace();
}
}
// 发送 POST 请求
private static JSONObject sendPostRequest(String urlStr, String apiKey, JSONObject jsonData) throws IOException {
URL url = new URL(urlStr);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("APIKEY", apiKey);
conn.setRequestProperty("Content-Type", "application/json");
conn.setDoOutput(true);
// 写入请求数据
try (OutputStream os = conn.getOutputStream()) {
byte[] input = jsonData.toString().getBytes("utf-8");
os.write(input, 0, input.length);
}
// 读取响应
StringBuilder response = new StringBuilder();
try (BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"))) {
String responseLine;
while ((responseLine = br.readLine()) != null) {
response.append(responseLine.trim());
}
}
return new JSONObject(response.toString());
}
}
4.4 JavaScript
const fs = require('fs');
const fetch = require('node-fetch'); // 需安装:npm install node-fetch
const apiKey = '******'; // 你的API KEY
const filePath = 'path/to/your/image.jpg'; // 图片路径
(async () => {
try {
// 读取图片并编码为 Base64
const fileBuffer = fs.readFileSync(filePath);
const photoBase64 = fileBuffer.toString('base64');
// API 请求的 URL
const apiUrl = 'https://api.shiliuai.com/api/id_photo/v1/couple';
// 请求参数
const requestData = {
base64: photoBase64
};
// 发送 POST 请求
let response = await fetch(apiUrl, {
method: 'POST',
headers: {
'APIKEY': apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify(requestData)
});
const responseData = await response.json();
// 检查响应是否成功
if (responseData.code === 0) {
const resultBase64 = responseData.result_base64;
const resultBuffer = Buffer.from(resultBase64, 'base64');
fs.writeFileSync('result_couple.jpg', resultBuffer);
console.log('结婚证件照生成成功,文件已保存为 result_couple.jpg');
} else {
console.error('请求失败:', responseData.msg_cn);
}
} catch (error) {
console.error('发生错误:', error);
}
})();