# API Docs
## 目录
- [开始之前：开启后端服务](#开始之前开启后端服务)
- [接口功能说明](#接口功能说明)
- [cURL 请求示例](#curl-请求示例)
- [Python 请求示例](#python-请求示例)
- [Python Requests 请求方法](#1️⃣-python-requests-请求方法)
- [Python 脚本请求方法](#2️⃣-python-脚本请求方法)
- [Java 请求示例](#java-请求示例)
- [Javascript 请求示例](#javascript-请求示例)
## 开始之前：开启后端服务
在请求 API 之前，请先运行后端服务
```bash
python delopy_api.py
```
## 接口功能说明
### 1.生成证件照(底透明)
接口名：`idphoto`
`生成证件照`接口的逻辑是发送一张 RGB 图像，输出一张标准证件照和一张高清证件照：
- **高清证件照**：根据`size`的宽高比例制作的证件照，文件名为`output_image_dir`增加`_hd`后缀
- **标准证件照**：尺寸等于`size`，由高清证件照缩放而来，文件名为`output_image_dir`
需要注意的是，生成的两张照片都是透明的（RGBA 四通道图像），要生成完整的证件照，还需要下面的`添加背景色`接口。
> 问：为什么这么设计？
> 答：因为在实际产品中，经常用户会频繁切换底色预览效果，直接给透明底图像，由前端 js 代码合成颜色是更好体验的做法。
### 2.添加背景色
接口名：`add_background`
`添加背景色`接口的逻辑是发送一张 RGBA 图像，根据`color`添加背景色，合成一张 JPG 图像。
### 3.生成六寸排版照
接口名：`generate_layout_photos`
`生成六寸排版照`接口的逻辑是发送一张 RGB 图像（一般为添加背景色之后的证件照），根据`size`进行照片排布，然后生成一张六寸排版照。
## cURL 请求示例
cURL 是一个命令行工具，用于使用各种网络协议传输数据。以下是使用 cURL 调用这些 API 的示例。
### 1. 生成证件照(底透明)
```bash
curl -X POST "http://127.0.0.1:8080/idphoto" \
-F "input_image=@demo/images/test.jpg" \
-F "height=413" \
-F "width=295"
```
### 2. 添加背景色
```bash
curl -X POST "http://127.0.0.1:8080/add_background" \
-F "input_image=@test.png" \
-F "color=638cce" \
-F "kb=200"
```
### 3. 生成六寸排版照
```bash
curl -X POST "http://127.0.0.1:8080/generate_layout_photos" \
-F "input_image=@test.jpg" \
-F "height=413" \
-F "width=295" \
-F "kb=200"
```
## Python 请求示例
### 1️⃣ Python Requests 请求方法
#### 1.生成证件照(底透明)
```python
import requests
url = "http://127.0.0.1:8080/idphoto"
input_image_path = "images/test.jpg"
files = {"input_image": open(input_image_path, "rb")}
data = {"height": 413, "width": 295}
response = requests.post(url, files=files, data=data).json()
# response为一个json格式字典，包含status、image_base64_standard和image_base64_hd三项
print(response)
```
#### 2.添加背景色
```python
import requests
url = "http://127.0.0.1:8080/add_background"
input_image_path = "test.png"
files = {"input_image": open(input_image_path, "rb")}
data = {"color": '638cce', 'kb': None}
response = requests.post(url, files=files, data=data).json()
# response为一个json格式字典，包含status和image_base64
print(response)
```
#### 3.生成六寸排版照
```python
import requests
url = "http://127.0.0.1:8080/generate_layout_photos"
input_image_path = "test.jpg"
files = {"input_image": open(input_image_path, "rb")}
data = {"height": 413, "width": 295, "kb": 200}
response = requests.post(url, files=files, data=data).json()
# response为一个json格式字典，包含status和image_base64
print(response)
```
### 2️⃣ Python 脚本请求方法
```bash
python requests_api.py -u -t -i -o [--height ] [--width ] [-c ] [-k ]
```
#### 参数说明
##### 基本参数
- `-u`, `--url`
- **描述**: API 服务的 URL。
- **默认值**: `http://127.0.0.1:8080`
- `-t`, `--type`
- **描述**: 请求 API 的种类，可选值有 `idphoto`、`add_background` 和 `generate_layout_photos`。分别代表证件照制作、透明图加背景和排版照生成。
- **默认值**: `idphoto`
- `-i`, `--input_image_dir`
- **描述**: 输入图像路径。
- **必需**: 是
- **示例**: `./input_images/photo.jpg`
- `-o`, `--output_image_dir`
- **描述**: 保存图像路径。
- **必需**: 是
- **示例**: `./output_images/processed_photo.jpg`
##### 可选参数
- `--height`,
- **描述**: 标准证件照的输出尺寸的高度。
- **默认值**: 413
- `--width`,
- **描述**: 标准证件照的输出尺寸的宽度。
- **默认值**: 295
- `-c`, `--color`
- **描述**: 给透明图增加背景色，格式为 Hex（如#638cce），仅在 type 为`add_background`时生效
- **默认值**: `638cce`
- `-k`, `--kb`
- **描述**: 输出照片的 KB 值，仅在 type 为`add_background`和`generate_layout_photos`时生效，值为 None 时不做设置。
- **默认值**: `None`
- **示例**: `50`
### 1.生成证件照(底透明)
```bash
python requests_api.py \
-u http://127.0.0.1:8080 \
-t idphoto \
-i ./photo.jpg \
-o ./idphoto.png \
--height 413 \
--width 295
```
### 2.添加背景色
```bash
python requests_api.py \
-u http://127.0.0.1:8080 \
-t add_background \
-i ./idphoto.png \
-o ./idphoto_with_background.jpg \
-c 638cce \
-k 50
```
### 3.生成六寸排版照
```bash
python requests_api.py \
-u http://127.0.0.1:8080 \
-t generate_layout_photos \
-i ./idphoto_with_background.jpg \
-o ./layout_photo.jpg \
--height 413 \
--width 295 \
-k 200
```
### 请求失败的情况
- 照片中检测到的人脸大于 1，则失败
## Java 请求示例
### 添加 maven 依赖
```java
cn.hutool
hutool-all
5.8.16
commons-io
commons-io
2.6
```
### 运行代码
#### 1.生成证件照(底透明)
```java
/**
* 生成证件照(底透明) /idphoto 接口
* @param inputImageDir 文件地址
* @return
* @throws IOException
*/
public static String requestIdPhoto(String inputImageDir) throws IOException {
String url = BASE_URL+"/idphoto";
// 创建文件对象
File inputFile = new File(inputImageDir);
Map paramMap=new HashMap<>();
paramMap.put("input_image",inputFile);
paramMap.put("height","413");
paramMap.put("width","295");
//包含status、image_base64_standard和image_base64_hd三项
return HttpUtil.post(url, paramMap);
}
```
#### 2.添加背景色
```java
/**
* 添加背景色 /add_background 接口
* @param inputImageDir 文件地址
* @return
* @throws IOException
*/
public static String requestAddBackground(String inputImageDir) throws IOException {
String url = BASE_URL+"/add_background";
// 创建文件对象
File inputFile = new File(inputImageDir);
Map paramMap=new HashMap<>();
paramMap.put("input_image",inputFile);
paramMap.put("color","638cce");
paramMap.put("kb","200");
// response为一个json格式字典，包含status和image_base64
return HttpUtil.post(url, paramMap);
}
```
#### 3.生成六寸排版照
```java
/**
* 生成六寸排版照 /generate_layout_photos 接口
* @param inputImageDir 文件地址
* @return
* @throws IOException
*/
public static String requestGenerateLayoutPhotos(String inputImageDir) throws IOException {
String url = BASE_URL+"/generate_layout_photos";
// 创建文件对象
File inputFile = new File(inputImageDir);
Map paramMap=new HashMap<>();
paramMap.put("input_image",inputFile);
paramMap.put("height","413");
paramMap.put("width","295");
paramMap.put("kb","200");
//response为一个json格式字典，包含status和image_base64
return HttpUtil.post(url, paramMap);
}
```
#### 4.汇总
```java
import cn.hutool.http.HttpUtil;
import cn.hutool.json.JSONObject;
import cn.hutool.json.JSONUtil;
import org.apache.commons.io.FileUtils;
import org.springframework.util.StringUtils;
import java.io.File;
import java.io.IOException;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;
/**
* @author: qingshuang
* @createDate: 2024/09/05
* @description: java生成证件照，测试用例
*/
public class Test {
/**
* 接口地址
*/
private final static String BASE_URL = "http://127.0.0.1:8080";
/**
* 生成证件照(底透明) /idphoto 接口
* @param inputImageDir 文件地址
* @return
* @throws IOException
*/
public static String requestIdPhoto(String inputImageDir) throws IOException {
String url = BASE_URL+"/idphoto";
// 创建文件对象
File inputFile = new File(inputImageDir);
Map paramMap=new HashMap<>();
paramMap.put("input_image",inputFile);
paramMap.put("height","413");
paramMap.put("width","295");
return HttpUtil.post(url, paramMap);
}
/**
* 添加背景色 /add_background 接口
* @param inputImageDir 文件地址
* @return
* @throws IOException
*/
public static String requestAddBackground(String inputImageDir) throws IOException {
String url = BASE_URL+"/add_background";
// 创建文件对象
File inputFile = new File(inputImageDir);
Map paramMap=new HashMap<>();
paramMap.put("input_image",inputFile);
paramMap.put("color","638cce");
paramMap.put("kb","200");
return HttpUtil.post(url, paramMap);
}
/**
* 生成六寸排版照 /generate_layout_photos 接口
* @param inputImageDir 文件地址
* @return
* @throws IOException
*/
public static String requestGenerateLayoutPhotos(String inputImageDir) throws IOException {
String url = BASE_URL+"/generate_layout_photos";
// 创建文件对象
File inputFile = new File(inputImageDir);
Map paramMap=new HashMap<>();
paramMap.put("input_image",inputFile);
paramMap.put("height","413");
paramMap.put("width","295");
paramMap.put("kb","200");
return HttpUtil.post(url, paramMap);
}
/**
* 生成证件照(底透明)
* @param inputImageDir 源文件地址
* @param outputImageDir 输出文件地址
* @throws IOException
*/
private static void requestIdPhotoToImage(String inputImageDir, String outputImageDir) throws IOException {
String res =requestIdPhoto(inputImageDir);
//转成json
JSONObject response= JSONUtil.parseObj(res);
if(response.getBool("status")){//请求接口成功
String image_base64_standard= response.getStr("image_base64_standard");
String image_base64_hd =response.getStr("image_base64_hd");
String[] outputImageDirArr= StringUtils.split(outputImageDir,".");
// Base64 保存为图片
FileUtils.writeByteArrayToFile(new File(outputImageDirArr[0]+"_standard."+outputImageDirArr[1]), Base64.getDecoder().decode(image_base64_standard));
FileUtils.writeByteArrayToFile(new File(outputImageDirArr[0]+"_hd."+outputImageDirArr[1]), Base64.getDecoder().decode(image_base64_hd));
}
}
/**
* 添加背景色
* @param inputImageDir 源文件地址
* @param outputImageDir 输出文件地址
* @throws IOException
*/
private static void requestAddBackgroundToImage(String inputImageDir, String outputImageDir) throws IOException {
String res =requestAddBackground(inputImageDir);
//转成json
JSONObject response= JSONUtil.parseObj(res);
if(response.getBool("status")){//请求接口成功
String image_base64= response.getStr("image_base64");
String[] outputImageDirArr= StringUtils.split(outputImageDir,".");
// Base64 保存为图片
FileUtils.writeByteArrayToFile(new File(outputImageDirArr[0]+"_background."+outputImageDirArr[1]), Base64.getDecoder().decode(image_base64));
}
}
/**
* 生成六寸排版照
* @param inputImageDir 源文件地址
* @param outputImageDir 输出文件地址
* @throws IOException
*/
private static void requestGenerateLayoutPhotosToImage(String inputImageDir, String outputImageDir) throws IOException {
String res =requestGenerateLayoutPhotos(inputImageDir);
//转成json
JSONObject response= JSONUtil.parseObj(res);
if(response.getBool("status")){//请求接口成功
String image_base64= response.getStr("image_base64");
String[] outputImageDirArr= StringUtils.split(outputImageDir,".");
// Base64 保存为图片
FileUtils.writeByteArrayToFile(new File(outputImageDirArr[0]+"_layout."+outputImageDirArr[1]), Base64.getDecoder().decode(image_base64));
}
}
public static void main(String[] args) {
try {
//生成证件照(底透明)
requestIdPhotoToImage("C:\\Users\\Administrator\\Desktop\\1111.jpg","C:\\Users\\Administrator\\Desktop\\2222.png");
//添加背景色
requestAddBackgroundToImage("C:\\Users\\Administrator\\Desktop\\2222_hd.png","C:\\Users\\Administrator\\Desktop\\idphoto_with_background.jpg");
//生成六寸排版照
requestGenerateLayoutPhotosToImage("C:\\Users\\Administrator\\Desktop\\1111.jpg","C:\\Users\\Administrator\\Desktop\\2222.png");
} catch (IOException e) {
e.printStackTrace();
}
}
}
```
## JavaScript 请求示例
在JavaScript中，我们可以使用`fetch` API来发送HTTP请求。以下是如何使用JavaScript调用这些API的示例。
### 1. 生成证件照(底透明)
```javascript
async function generateIdPhoto(inputImagePath, height, width) {
const url = "http://127.0.0.1:8080/idphoto";
const formData = new FormData();
formData.append("input_image", new File([await fetch(inputImagePath).then(res => res.blob())], "test.jpg"));
formData.append("height", height);
formData.append("width", width);
const response = await fetch(url, {
method: 'POST',
body: formData
});
const result = await response.json();
console.log(result);
return result;
}
// 示例调用
generateIdPhoto("images/test.jpg", 413, 295).then(response => {
console.log(response);
});
```
### 2. 添加背景色
```javascript
async function addBackground(inputImagePath, color, kb) {
const url = "http://127.0.0.1:8080/add_background";
const formData = new FormData();
formData.append("input_image", new File([await fetch(inputImagePath).then(res => res.blob())], "test.png"));
formData.append("color", color);
formData.append("kb", kb);
const response = await fetch(url, {
method: 'POST',
body: formData
});
const result = await response.json();
console.log(result);
return result;
}
// 示例调用
addBackground("test.png", "638cce", 200).then(response => {
console.log(response);
});
```
### 3. 生成六寸排版照
```javascript
async function generateLayoutPhotos(inputImagePath, height, width, kb) {
const url = "http://127.0.0.1:8080/generate_layout_photos";
const formData = new FormData();
formData.append("input_image", new File([await fetch(inputImagePath).then(res => res.blob())], "test.jpg"));
formData.append("height", height);
formData.append("width", width);
formData.append("kb", kb);
const response = await fetch(url, {
method: 'POST',
body: formData
});
const result = await response.json();
console.log(result);
return result;
}
// 示例调用
generateLayoutPhotos("test.jpg", 413, 295, 200).then(response => {
console.log(response);
});
```