docs/api_EN.md

# API Documentation

[中文](api_CN.md) | English

## TOC

- [Before You Start: Launch the Backend Service](#before-you-start-launch-the-backend-service)
- [Interface Function Descriptions](#interface-function-descriptions)
- [cURL Request Example](#curl-request-examples)
- [Python Request Example](#python-request-example)
  - [Python Requests Method](#1️⃣-python-requests-method)
  - [Python Script Method](#2️⃣-python-script-request-method)
- [Java Request Example](#java-request-example)
- [Javascript Request Example](#javascript-request-examples)

## Before You Start: Launch the Backend Service

Before making API requests, please run the backend service:

```bash
python deploy_api.py
```

<br>

## Interface Function Descriptions

### 1. Generate ID Photo (Transparent Background)

Interface Name: `idphoto`

The `Generate ID Photo` interface logic involves sending an RGB image and receiving a standard ID photo and a high-definition ID photo:

- **High-Definition ID Photo**: An ID photo made according to the aspect ratio of `size`, with the filename being `output_image_dir` appended with `_hd` suffix.
- **Standard ID Photo**: A photo with dimensions equal to `size`, scaled from the high-definition ID photo, with the filename being `output_image_dir`.

It should be noted that both generated photos are transparent (RGBA four-channel images). To produce a complete ID photo, the following `Add Background Color` interface is also required.

> Q: Why is this design used?  
> A: In actual products, users often need to frequently switch background colors to preview effects. Providing a transparent background image and allowing the front-end JavaScript code to synthesize the color offers a better user experience.

### 2. Add Background Color

Interface Name: `add_background`

The `Add Background Color` interface logic involves sending an RGBA image, adding a background color based on `color`, and synthesizing a JPG image.

### 3. Generate 6-inch Layout Photo

Interface Name: `generate_layout_photos`

The `Generate 6-inch Layout Photo` interface logic involves sending an RGB image (usually an ID photo after adding a background color), arranging the photos according to `size`, and then generating a 6-inch layout photo.

<br>


## cURL Request Examples

cURL is a command-line tool used to transfer data using various network protocols. Below are examples of how to use cURL to call these APIs.

### 1. Generate ID Photo (Transparent Background)

```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. Add Background Color

```bash
curl -X POST "http://127.0.0.1:8080/add_background" \
-F "input_image=@test.png" \
-F "color=638cce" \
-F "kb=200"
```

### 3. Generate Six-Inch Layout Photo

```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 Request Example

### 1️⃣ Python Requests Method

#### 1. Generate ID Photo (Transparent Background)

```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 is a JSON dictionary containing status, image_base64_standard, and image_base64_hd
print(response)
```

#### 2. Add Background Color

```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 is a JSON dictionary containing status and image_base64
print(response)
```

#### 3. Generate 6-inch Layout Photo

```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 is a JSON dictionary containing status and image_base64
print(response)
```

<br>

### 2️⃣ Python Script Request Method

```bash
python requests_api.py -u <URL> -t <TYPE> -i <INPUT_IMAGE_DIR> -o <OUTPUT_IMAGE_DIR> [--height <HEIGHT>] [--width <WIDTH>] [-c <COLOR>] [-k <KB>]
```

#### Parameter Descriptions

##### Basic Parameters

- `-u`, `--url`

  - **Description**: The URL of the API service.
  - **Default Value**: `http://127.0.0.1:8080`

- `-t`, `--type`

  - **Description**: The type of API request, with optional values being `idphoto`, `add_background`, and `generate_layout_photos`. They represent ID photo creation, transparent image background addition, and layout photo generation, respectively.
  - **Default Value**: `idphoto`

- `-i`, `--input_image_dir`

  - **Description**: The path of the input image.
  - **Required**: Yes
  - **Example**: `./input_images/photo.jpg`

- `-o`, `--output_image_dir`
  - **Description**: The path to save the image.
  - **Required**: Yes
  - **Example**: `./output_images/processed_photo.jpg`

##### Optional Parameters

- `--height`

  - **Description**: The height of the output size for the standard ID photo.
  - **Default Value**: 413

- `--width`

  - **Description**: The width of the output size for the standard ID photo.
  - **Default Value**: 295

- `-c`, `--color`

  - **Description**: Adds a background color to the transparent image, in Hex format (e.g., #638cce), only effective when the type is `add_background`.
  - **Default Value**: `638cce`

- `-k`, `--kb`
  - **Description**: The KB value of the output photo, only effective when the type is `add_background` or `generate_layout_photos`, and no setting is made when the value is None.
  - **Default Value**: `None`
  - **Example**: `50`

#### 1. Generate ID Photo (Transparent Background)

```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. Add Background Color

```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. Generate 6-inch Layout Photo

```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
```

#### Request Failure Scenarios

- The request fails if more than one face is detected in the photo.

## Java Request Example

### Add Maven Dependency

```java
        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
            <version>5.8.16</version>
        </dependency>

        <dependency>
            <groupId>commons-io</groupId>
            <artifactId>commons-io</artifactId>
            <version>2.6</version>
        </dependency>
```

### Running the Code

#### 1. Generate ID Photo (Transparent Background)

```java
    /**
     * Generate ID Photo (Transparent Background) /idphoto interface
     * @param inputImageDir File address
     * @return
     * @throws IOException
     */
    public static String requestIdPhoto(String inputImageDir) throws IOException {
        String url = BASE_URL+"/idphoto";
        // Create file object
        File inputFile = new File(inputImageDir);
        Map<String, Object> paramMap=new HashMap<>();
        paramMap.put("input_image",inputFile);
        paramMap.put("height","413");
        paramMap.put("width","295");
        // Contains status, image_base64_standard, and image_base64_hd
        return HttpUtil.post(url, paramMap);
    }
```

#### 2. Add Background Color

```java
    /**
     * Add Background Color /add_background interface
     * @param inputImageDir File address
     * @return
     * @throws IOException
     */
    public static String requestAddBackground(String inputImageDir) throws IOException {
        String url = BASE_URL+"/add_background";
        // Create file object
        File inputFile = new File(inputImageDir);
        Map<String, Object> paramMap=new HashMap<>();
        paramMap.put("input_image",inputFile);
        paramMap.put("color","638cce");
        paramMap.put("kb","200");
        // Response is a JSON dictionary containing status and image_base64
        return HttpUtil.post(url, paramMap);
    }
```

#### 3. Generate 6-inch Layout Photo

```java
    /**
     * Generate 6-inch Layout Photo /generate_layout_photos interface
     * @param inputImageDir File address
     * @return
     * @throws IOException
     */
    public static String requestGenerateLayoutPhotos(String inputImageDir) throws IOException {
        String url = BASE_URL+"/generate_layout_photos";
        // Create file object
        File inputFile = new File(inputImageDir);
        Map<String, Object> paramMap=new HashMap<>();
        paramMap.put("input_image",inputFile);
        paramMap.put("height","413");
        paramMap.put("width","295");
        paramMap.put("kb","200");
        // Response is a JSON dictionary containing status and image_base64
        return HttpUtil.post(url, paramMap);
    }
```

#### 4. Summary

```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 generate ID photo, test case
 */
public class Test {
    /**
     * Interface address
     */
    private final static String BASE_URL = "http://127.0.0.1:8080";

    /**
     * Generate ID Photo (Transparent Background) /idphoto interface
     * @param inputImageDir File address
     * @return
     * @throws IOException
     */
    public static String requestIdPhoto(String inputImageDir) throws IOException {
        String url = BASE_URL+"/idphoto";
        // Create file object
        File inputFile = new File(inputImageDir);
        Map<String, Object> paramMap=new HashMap<>();
        paramMap.put("input_image",inputFile);
        paramMap.put("height","413");
        paramMap.put("width","295");
        return HttpUtil.post(url, paramMap);
    }
    /**
     * Add Background Color /add_background interface
     * @param inputImageDir File address
     * @return
     * @throws IOException
     */
    public static String requestAddBackground(String inputImageDir) throws IOException {
        String url = BASE_URL+"/add_background";
        // Create file object
        File inputFile = new File(inputImageDir);
        Map<String, Object> paramMap=new HashMap<>();
        paramMap.put("input_image",inputFile);
        paramMap.put("color","638cce");
        paramMap.put("kb","200");
        return HttpUtil.post(url, paramMap);
    }
    /**
     * Generate 6-inch Layout Photo /generate_layout_photos interface
     * @param inputImageDir File address
     * @return
     * @throws IOException
     */
    public static String requestGenerateLayoutPhotos(String inputImageDir) throws IOException {
        String url = BASE_URL+"/generate_layout_photos";
        // Create file object
        File inputFile = new File(inputImageDir);
        Map<String, Object> 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);
    }
    /**
     * Generate ID Photo (Transparent Background)
     * @param inputImageDir Source file address
     * @param outputImageDir Output file address
     * @throws IOException
     */
    private static void requestIdPhotoToImage(String inputImageDir, String outputImageDir) throws IOException {
        String res =requestIdPhoto(inputImageDir);
        // Convert to JSON
        JSONObject response= JSONUtil.parseObj(res);
        if(response.getBool("status")){// Request interface success
            String  image_base64_standard= response.getStr("image_base64_standard");
            String  image_base64_hd =response.getStr("image_base64_hd");
            String[] outputImageDirArr= StringUtils.split(outputImageDir,".");
            // Base64 save as image
            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));
        }
    }
    /**
     * Add Background Color
     * @param inputImageDir Source file address
     * @param outputImageDir Output file address
     * @throws IOException
     */
    private static void requestAddBackgroundToImage(String inputImageDir, String outputImageDir) throws IOException {
        String res =requestAddBackground(inputImageDir);
        // Convert to JSON
        JSONObject response= JSONUtil.parseObj(res);
        if(response.getBool("status")){// Request interface success
            String  image_base64= response.getStr("image_base64");
            String[] outputImageDirArr= StringUtils.split(outputImageDir,".");
            // Base64 save as image
            FileUtils.writeByteArrayToFile(new File(outputImageDirArr[0]+"_background."+outputImageDirArr[1]),  Base64.getDecoder().decode(image_base64));
        }
    }
    /**
     * Generate 6-inch Layout Photo
     * @param inputImageDir Source file address
     * @param outputImageDir Output file address
     * @throws IOException
     */
    private static void requestGenerateLayoutPhotosToImage(String inputImageDir, String outputImageDir) throws IOException {
        String res =requestGenerateLayoutPhotos(inputImageDir);
        // Convert to JSON
        JSONObject response= JSONUtil.parseObj(res);
        if(response.getBool("status")){// Request interface success
            String  image_base64= response.getStr("image_base64");
            String[] outputImageDirArr= StringUtils.split(outputImageDir,".");
            // Base64 save as image
            FileUtils.writeByteArrayToFile(new File(outputImageDirArr[0]+"_layout."+outputImageDirArr[1]),  Base64.getDecoder().decode(image_base64));
        }
    }

    public static void main(String[] args) {
        try {
            // Generate ID Photo (Transparent Background)
            requestIdPhotoToImage("C:\\Users\\Administrator\\Desktop\\1111.jpg","C:\\Users\\Administrator\\Desktop\\2222.png");
            // Add Background Color
            requestAddBackgroundToImage("C:\\Users\\Administrator\\Desktop\\2222_hd.png","C:\\Users\\Administrator\\Desktop\\idphoto_with_background.jpg");
            // Generate 6-inch Layout Photo
            requestGenerateLayoutPhotosToImage("C:\\Users\\Administrator\\Desktop\\1111.jpg","C:\\Users\\Administrator\\Desktop\\2222.png");

        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}
```

## JavaScript Request Examples

In JavaScript, we can use the `fetch` API to send HTTP requests. Below are examples of how to call these APIs using JavaScript.

### 1. Generate ID Photo (Transparent Background)

```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;
}

// Example call
generateIdPhoto("images/test.jpg", 413, 295).then(response => {
    console.log(response);
});
```

### 2. Add Background Color

```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;
}

// Example call
addBackground("test.png", "638cce", 200).then(response => {
    console.log(response);
});
```

### 3. Generate Six-Inch Layout Photo

```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;
}

// Example call
generateLayoutPhotos("test.jpg", 413, 295, 200).then(response => {
    console.log(response);
});
```