HivisionIDPhoto

https://github.com/zeyi-lin/hivisionidphotos
Admin
HivisionIDPhoto is an AI-powered intelligent ID photo generation tool that provides lightweight...
Tokens:19,316
Snippets:112
Trust Score:9.4
License:Apache-2.0
Update:6 months ago
Show doc for...
Tokens:
Raw
### Deploy API Service: Start Backend

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Start the backend API service for the HiVision ID Photos application.

```bash
python deploy_api.py
```

--------------------------------

### Install ONNX Runtime GPU and PyTorch

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Install the necessary packages for GPU acceleration. Ensure CUDA and cuDNN are installed and compatible with the chosen versions. PyTorch installation is optional but recommended if cuDNN configuration is problematic.

```bash
pip install onnxruntime-gpu==1.18.0
pip install torch --index-url https://download.pytorch.org/whl/cu121
```

--------------------------------

### Docker Deployment: Run Both Services with Docker Compose

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Start both the Gradio Demo and API backend services simultaneously using Docker Compose in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Docker Usage with Environment Variables

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Example of running a Docker container with multiple environment variables set for configuration, including API keys, run mode, and default language.

```bash
docker run  -d -p 7860:7860 \
    -e FACE_PLUS_API_KEY=7-fZStDJ···· \
    -e FACE_PLUS_API_SECRET=VTee824E···· \
    -e RUN_MODE=beast \
    -e DEFAULT_LANG=en \
    linzeyi/hivision_idphotos  
```

--------------------------------

### Run Application with CUDA 12.x and cuDNN 8

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Install specific versions of onnxruntime-gpu and torch for CUDA 12.x and cuDNN 8. This setup is for GPU-accelerated inference.

```bash
# 假如你的电脑安装的是CUDA 12.x, cuDNN 8
# 安装torch是可选的，如果你始终配置不好cuDNN，那么试试安装torch
pip install onnxruntime-gpu==1.18.0
pip install torch --index-url https://download.pytorch.org/whl/cu121
```

--------------------------------

### Add Background Color - Python

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Python example using the requests library to add a background color to an image. Allows specifying color, KB size, and DPI.

```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,
    "render": 0,
    "dpi": 300,
}

response = requests.post(url, files=files, data=data).json()

# response为一个json格式字典，包含status和image_base64
print(response)
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Install the required Python packages. It is recommended to use a conda virtual environment with Python 3.10.

```bash
pip install -r requirements.txt
pip install -r requirements-app.txt
```

--------------------------------

### Generate ID Photo (Transparent Background) - Python

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Python example using the requests library to generate an ID photo with a transparent background. Requires specifying image path and various parameters.

```python
import requests

url = "http://127.0.0.1:8080/idphoto"
input_image_path = "demo/images/test0.jpg"

files = {"input_image": open(input_image_path, "rb")}
data = {
    "height": 413,
    "width": 295,
    "human_matting_model": "modnet_photographic_portrait_matting",
    "face_detect_model": "mtcnn",
    "hd": True,
    "dpi": 300,
    "face_alignment": True,
    "head_measure_ratio": 0.2,
    "head_height_ratio": 0.45,
    "top_distance_max": 0.12,
    "top_distance_min": 0.1,
    "brightness_strength": 0,
    "contrast_strength": 0,
    "sharpen_strength": 0,
    "saturation_strength": 0,
}

response = requests.post(url, params=params, files=files, data=data).json()

# response为一个json格式字典，包含status、image_base64_standard和image_base64_hd三项
print(response)
```

--------------------------------

### Clone the Project Repository

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Use these commands to download the project source code and navigate into the directory.

```bash
git clone https://github.com/Zeyi-Lin/HivisionIDPhotos.git
cd  HivisionIDPhotos
```

--------------------------------

### Download Portrait Matting Models

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Use the provided script to download the necessary portrait matting model weights.

```bash
python scripts/download_model.py --models all
# 如需指定下载某个模型
# python scripts/download_model.py --models modnet_photographic_portrait_matting
```

--------------------------------

### 设置 Windows 环境变量

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/face++_CN.md

在 Windows 操作系统中设置 Face++ API Key 和 API Secret 环境变量。请将 "您的API_KEY" 和 "您的API_SECRET" 替换为您的实际密钥。

```cmd
set FACE_PLUS_API_KEY="您的API_KEY"
set FACE_PLUS_API_SECRET="您的API_SECRET"
```

--------------------------------

### Docker Deployment: Build Image from Dockerfile

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Build a Docker image directly from the project's Dockerfile. Ensure model weights are placed in the specified directory before building.

```bash
docker build -t linzeyi/hivision_idphotos .
```

--------------------------------

### Docker 部署与配置

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

使用 Docker 快速启动服务，支持 Gradio 界面、API 后端及环境变量配置。

```bash
# 拉取官方镜像
docker pull linzeyi/hivision_idphotos

# 启动 Gradio Web 界面 (端口 7860)
docker run -d -p 7860:7860 linzeyi/hivision_idphotos

# 启动 API 后端服务 (端口 8080)
docker run -d -p 8080:8080 linzeyi/hivision_idphotos python3 deploy_api.py

# 使用环境变量配置
docker run -d -p 7860:7860 \
  -e FACE_PLUS_API_KEY=your_api_key \
  -e FACE_PLUS_API_SECRET=your_api_secret \
  -e RUN_MODE=beast \
  -e DEFAULT_LANG=en \
  linzeyi/hivision_idphotos

# 使用 docker-compose 同时启动两个服务
docker compose up -d

# 自行构建镜像 (需先下载模型权重到 hivision/creator/weights)
docker build -t hivision_idphotos .
```

--------------------------------

### 证件照裁切命令行操作

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

对已抠图的图像进行指定尺寸的裁切处理。

```bash
python inference.py \
  -t idphoto_crop \
  -i ./matting.png \
  -o ./cropped.png \
  --height 413 \
  --width 295
```

--------------------------------

### 设置 Linux/macOS 环境变量

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/face++_CN.md

在 Linux 或 macOS 操作系统中设置 Face++ API Key 和 API Secret 环境变量。请将 "你的API_KEY" 和 "你的API_SECRET" 替换为您的实际密钥。

```bash
export FACE_PLUS_API_KEY="你的API_KEY"
export FACE_PLUS_API_SECRET="你的API_SECRET"
```

--------------------------------

### Docker Deployment: Build with Docker Compose

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Build the Docker image using Docker Compose. This method also requires model weights to be in the correct directory.

```bash
docker compose build
```

--------------------------------

### Generate Layout Photos with Python

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Sends an image to the /generate_layout_photos endpoint to create a six-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,
    "dpi": 300,
}

response = requests.post(url, files=files, data=data).json()

# response为一个json格式字典，包含status和image_base64
print(response)
```

--------------------------------

### Docker Deployment: Run Gradio Demo Service

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Run the Gradio Demo service in detached mode, mapping port 7860 for access via a web browser.

```bash
docker run -d -p 7860:7860 linzeyi/hivision_idphotos
```

--------------------------------

### Python Inference: Generate Layout Photos

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Create a six-inch layout photo from a 3-channel image. Specify input and output paths, and desired dimensions. Kernel size for blurring can also be set.

```python
python inference.py -t generate_layout_photos -i ./idphoto_ab.jpg -o ./idphoto_layout.jpg  --height 413 --width 295 -k 200
```

--------------------------------

### Docker Compose 配置示例

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

通过 docker-compose.yml 文件定义服务及其环境变量。

```yaml
# docker-compose.yml 配置示例
version: '3'
services:
  hivision:
    image: linzeyi/hivision_idphotos
    ports:
      - "7860:7860"
      - "8080:8080"
    environment:
      - RUN_MODE=beast
      - DEFAULT_LANG=zh
```

--------------------------------

### Command-line Inference

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Process images using command-line scripts for ID photo creation, matting, background addition, and layout generation.

```APIDOC
## Command-line Inference - inference.py

### Description
Process images using command-line scripts, supporting ID photo creation, human matting, background addition, and layout photo generation.

### Usage Examples:

1.  **ID Photo Creation (Outputting transparent standard and HD photos):**
    ```bash
    python inference.py \
      -i demo/images/test0.jpg \
      -o ./idphoto.png \
      --height 413 \
      --width 295 \
      --matting_model modnet_photographic_portrait_matting \
      --face_detect_model mtcnn \
      --dpi 300
    ```

2.  **Human Matting (Background removal only):**
    ```bash
    python inference.py \
      -t human_matting \
      -i demo/images/test0.jpg \
      -o ./matting.png \
      --matting_model hivision_modnet
    ```

3.  **Adding Background Color to Transparent Image:**
    `render`: 0=solid color, 1=top-bottom gradient, 2=center gradient
    ```bash
    python inference.py \
      -t add_background \
      -i ./idphoto.png \
      -o ./idphoto_blue.jpg \
      -c 638cce \
      -k 200 \
      -r 0
    ```

4.  **Generate 6-inch Layout Photo:**
    ```bash
    python inference.py \
      -t generate_layout_photos \
      -i ./idphoto_blue.jpg \
      -o ./layout.jpg \
      --height 413 \
      --width 295 \
      -k 200
    ```
```

--------------------------------

### POST /add_background - Add Background Color

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

This endpoint takes a transparent RGBA image and adds a background color. It supports solid colors, vertical gradients, and radial gradients, outputting a JPG image.

```APIDOC
## POST /add_background

### Description
This endpoint receives an RGBA transparent image and adds a background based on the specified color. It supports three rendering modes: solid color, vertical gradient, and center gradient, outputting a JPG format image.

### Method
POST

### Endpoint
`/add_background`

### Parameters
#### Form Data
- **input_image** (file) - Required - The input transparent PNG image file.
- **color** (string) - Required - The background color in HEX format (without '#'). Example: `638cce` for blue.
- **kb** (integer) - Optional - The output file size limit in KB. `None` means no limit. Defaults to None.
- **render** (integer) - Optional - The rendering mode: `0` for solid color, `1` for vertical gradient, `2` for center gradient. Defaults to `0`.
- **dpi** (integer) - Optional - The DPI of the output image. Defaults to 300.

### Request Example
```bash
curl -X POST "http://127.0.0.1:8080/add_background" \
  -F "input_image=@transparent.png" \
  -F "color=638cce" \
  -F "kb=200" \
  -F "render=0" \
  -F "dpi=300"
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the operation was successful.
- **image_base64** (string) - Base64 encoded string of the image with the background added.

#### Response Example
```json
{
  "status": true,
  "image_base64": "iVBORw0KGgo..."
}
```

**Common Background Colors:**
- Blue: `438edb` or `638cce`
- White: `ffffff`
- Red: `ff0000`
```

```Python
import requests
import base64

url = "http://127.0.0.1:8080/add_background"
files = {"input_image": open("transparent.png", "rb")}
data = {
    "color": "638cce",   # Blue background (HEX format, without #)
    "kb": 200,           # Output file size limit (KB), None means no limit
    "render": 0,         # Rendering mode: 0=solid color, 1=vertical gradient, 2=center gradient
    "dpi": 300,
}

response = requests.post(url, files=files, data=data).json()

if response["status"]:
    image_data = base64.b64decode(response["image_base64"])
    with open("with_background.jpg", "wb") as f:
        f.write(image_data)

# Common background colors:
# Blue: 438edb or 638cce
# White: ffffff
# Red: ff0000
```

--------------------------------

### Human Matting (Portrait Segmentation)

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Performs human matting to segment the portrait from the background using a specified model. Requires an input image and DPI.

```bash
curl -X POST "http://127.0.0.1:8080/human_matting" \
-F "input_image=@demo/images/test0.jpg" \
-F "human_matting_model=modnet_photographic_portrait_matting" \
-F "dpi=300"
```

--------------------------------

### Docker Deployment: Pull Latest Image

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Pull the latest pre-built Docker image for the HiVision ID Photos application.

```bash
docker pull linzeyi/hivision_idphotos
```

--------------------------------

### 启动 Gradio 服务

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/face++_CN.md

使用 Python 脚本启动 Gradio 服务。确保您已正确配置 Face++ API 密钥和 Secret。

```bash
python app.py
```

--------------------------------

### Generate 6-Inch Layout Photos

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Generates a 6-inch layout of photos with specified dimensions, KB size, and DPI. This is useful for creating photo prints.

```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" \
-F "dpi=300"
```

--------------------------------

### Generate ID Photo (Transparent Background)

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Generates an ID photo with a transparent background. Requires specifying dimensions, matting model, face detection model, and other alignment parameters.

```bash
curl -X POST "http://127.0.0.1:8080/idphoto" \
-F "input_image=@demo/images/test0.jpg" \
-F "height=413" \
-F "width=295" \
-F "human_matting_model=modnet_photographic_portrait_matting" \
-F "face_detect_model=mtcnn" \
-F "hd=true" \
-F "dpi=300" \
-F "face_alignment=true" \
-F 'head_height_ratio=0.45' \
-F 'head_measure_ratio=0.2' \
-F 'top_distance_min=0.1' \
-F 'top_distance_max=0.12' \
-F 'sharpen_strength=0' \
-F 'saturation_strength=0' \
-F 'brightness_strength=10' \
-F 'contrast_strength=0'
```

--------------------------------

### Set Image File Size using Python

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Python script to resize an image to a target file size in KB. The API adjusts compression or header info to meet the specified KB.

```python
import requests
import base64

url = "http://127.0.0.1:8080/set_kb"
files = {"input_image": open("photo.jpg", "rb")}
data = {"kb": 50, "dpi": 300}

response = requests.post(url, files=files, data=data).json()

if response["status"]:
    resized = base64.b64decode(response["image_base64"])
    with open("resized_50kb.jpg", "wb") as f:
        f.write(resized)
    print(f"文件大小: {len(resized) / 1024:.1f} KB")
```

--------------------------------

### Command-line Inference: Generate Layout Photos

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Generate a 6-inch layout of ID photos using the command-line script. This command takes a processed ID photo and arranges it into a printable layout.

```bash
python inference.py \
  -t generate_layout_photos \
  -i ./idphoto_blue.jpg \
  -o ./layout.jpg \
  --height 413 \
  --width 295 \
  -k 200
```

--------------------------------

### Python Inference: Human Matting

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Perform human matting to obtain a 4-channel transparent PNG of a person. Requires specifying the input image, output path, and the matting model.

```python
python inference.py -t human_matting -i demo/images/test0.jpg -o ./idphoto_matting.png --matting_model hivision_modnet
```

--------------------------------

### Perform Human Matting with Python

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Uses the /human_matting endpoint to remove the background from a portrait image.

```python
import requests

url = "http://127.0.0.1:8080/human_matting"
input_image_path = "test.jpg"

files = {"input_image": open(input_image_path, "rb")}
data = {
    "human_matting_model": "modnet_photographic_portrait_matting",
    "dpi": 300,
}

response = requests.post(url, files=files, data=data).json()

# response为一个json格式字典，包含status和image_base64
print(response)
```

--------------------------------

### Command-line Inference: ID Photo Creation

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Use the command-line script for ID photo creation. This command generates a standard and high-definition ID photo with a transparent background.

```bash
python inference.py \
  -i demo/images/test0.jpg \
  -o ./idphoto.png \
  --height 413 \
  --width 295 \
  --matting_model modnet_photographic_portrait_matting \
  --face_detect_model mtcnn \
  --dpi 300
```

--------------------------------

### 证件照制作完整工作流 API 调用

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

通过 Python 请求 API 完成从抠图、背景替换到排版生成的全流程。

```python
import requests
import base64

API_BASE = "http://127.0.0.1:8080"

def make_id_photo(input_path, output_prefix, height=413, width=295, bg_color="438edb"):
    """
    完整证件照制作流程
    1. 生成透明背景证件照
    2. 添加背景色
    3. 生成六寸排版照
    """

    # 步骤1: 生成透明背景证件照
    with open(input_path, "rb") as f:
        response = requests.post(
            f"{API_BASE}/idphoto",
            files={"input_image": f},
            data={
                "height": height,
                "width": width,
                "human_matting_model": "modnet_photographic_portrait_matting",
                "face_detect_model": "mtcnn",
                "hd": True,
                "face_alignment": True,
            }
        ).json()

    if not response["status"]:
        raise Exception("证件照生成失败：未检测到有效人脸")

    # 保存透明背景高清照
    hd_transparent = base64.b64decode(response["image_base64_hd"])
    with open(f"{output_prefix}_transparent.png", "wb") as f:
        f.write(hd_transparent)

    # 步骤2: 添加背景色
    response = requests.post(
        f"{API_BASE}/add_background",
        files={"input_image": (f"{output_prefix}.png", hd_transparent, "image/png")},
        data={
            "color": bg_color,
            "render": 0,
            "dpi": 300,
        }
    ).json()

    with_bg = base64.b64decode(response["image_base64"])
    with open(f"{output_prefix}_blue.jpg", "wb") as f:
        f.write(with_bg)

    # 步骤3: 生成六寸排版照
    response = requests.post(
        f"{API_BASE}/generate_layout_photos",
        files={"input_image": (f"{output_prefix}.jpg", with_bg, "image/jpeg")},
        data={
            "height": height,
            "width": width,
            "kb": 500,
            "dpi": 300,
        }
    ).json()

    layout = base64.b64decode(response["image_base64"])
    with open(f"{output_prefix}_layout.jpg", "wb") as f:
        f.write(layout)

    print(f"证件照制作完成！")
    print(f"  透明背景: {output_prefix}_transparent.png")
    print(f"  蓝色背景: {output_prefix}_blue.jpg")
    print(f"  六寸排版: {output_prefix}_layout.jpg")

# 使用示例
make_id_photo("my_photo.jpg", "output/idphoto", height=413, width=295, bg_color="438edb")
```

--------------------------------

### Command-line Inference: Human Matting

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Perform human matting using the command-line script. This command focuses solely on background removal using a specified matting model.

```bash
python inference.py \
  -t human_matting \
  -i demo/images/test0.jpg \
  -o ./matting.png \
  --matting_model hivision_modnet
```

--------------------------------

### Human Matting using cURL

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Perform human matting using cURL to remove the background from an image. Specify the input image and the desired matting model.

```bash
curl -X POST "http://127.0.0.1:8080/human_matting" \
  -F "input_image=@photo.jpg" \
  -F "human_matting_model=modnet_photographic_portrait_matting" \
  -F "dpi=300"
```

--------------------------------

### Python Inference: Create ID Photos

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Generate standard and high-definition ID photos from an input image. Specify input and output paths, and desired dimensions.

```python
python inference.py -i demo/images/test0.jpg -o ./idphoto.png --height 413 --width 295
```

--------------------------------

### Set Image KB Size with Python

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Adjusts the file size of an image to a specific KB limit using the /set_kb endpoint.

```python
import requests

# 设置请求的 URL
url = "http://127.0.0.1:8080/set_kb"

# 设置文件和其他表单数据
input_image_path = "demo/images/test0.jpg"
files = {"input_image": open(input_image_path, "rb")}
data = {"kb": 50, "dpi": 300}

# 发送 POST 请求
response = requests.post(url, files=files, data=data)

# 检查响应
if response.ok:
    # 输出响应内容
    print(response.json())
else:
    # 输出错误信息
    print(f"Request failed with status code {response.status_code}: {response.text}")
```

--------------------------------

### POST /generate_layout_photos - Generate Six-Inch Layout Photos

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

This endpoint takes an RGB ID photo (with background color already added) and arranges it into a six-inch layout (1795x1205 pixels) based on specified ID photo dimensions.

```APIDOC
## POST /generate_layout_photos

### Description
This endpoint receives an RGB ID photo (with background color already added) and arranges it into a six-inch layout (1795x1205 pixels) based on the specified ID photo dimensions.

### Method
POST

### Endpoint
`/generate_layout_photos`

### Parameters
#### Form Data
- **input_image** (file) - Required - The input RGB ID photo with background color.
- **id_photo_width** (integer) - Required - The width of a single ID photo.
- **id_photo_height** (integer) - Required - The height of a single ID photo.
- **num_horizontal** (integer) - Optional - The number of ID photos to arrange horizontally. Defaults to 3.
- **num_vertical** (integer) - Optional - The number of ID photos to arrange vertically. Defaults to 5.
- **dpi** (integer) - Optional - The DPI of the output image. Defaults to 300.

### Request Example
```bash
curl -X POST "http://127.0.0.1:8080/generate_layout_photos" \
  -F "input_image=@photo_with_background.jpg" \
  -F "id_photo_width=413" \
  -F "id_photo_height=295" \
  -F "num_horizontal=3" \
  -F "num_vertical=5" \
  -F "dpi=300"
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the operation was successful.
- **image_base64** (string) - Base64 encoded string of the six-inch layout photo.

#### Response Example
```json
{
  "status": true,
  "image_base64": "iVBORw0KGgo..."
}
```
```

--------------------------------

### Add Background via REST API

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Apply a background color to an RGBA image using the /add_background endpoint. Supports solid colors and gradient rendering modes.

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

```python
import requests
import base64

url = "http://127.0.0.1:8080/add_background"
files = {"input_image": open("transparent.png", "rb")}
data = {
    "color": "638cce",   # 蓝色背景 (HEX格式，不带#)
    "kb": 200,           # 输出文件大小限制 (KB)，None表示不限制
    "render": 0,         # 渲染模式: 0=纯色, 1=上下渐变, 2=中心渐变
    "dpi": 300,
}

response = requests.post(url, files=files, data=data).json()

if response["status"]:
    image_data = base64.b64decode(response["image_base64"])
    with open("with_background.jpg", "wb") as f:
        f.write(image_data)
```

--------------------------------

### POST /set_kb

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Adjusts the file size of an image to a specific KB value by either compressing it or adding header information.

```APIDOC
## POST /set_kb

### Description
Adjusts the file size of an image to a target KB value. If the target is smaller than the original, it compresses the image; if larger, it adds header information.

### Method
POST

### Endpoint
/set_kb

### Parameters
#### Request Body
- **input_image** (file) - Required (or input_image_base64) - The RGB image file.
- **input_image_base64** (str) - Required (or input_image) - Base64 encoded RGB image.
- **kb** (int) - Optional - Target KB size.
- **dpi** (int) - Optional - Image resolution, default 300.

### Response
#### Success Response (200)
- **status** (int) - Status code (true for success).
- **image_base64** (str) - Base64 encoded image after KB adjustment.
```

--------------------------------

### Human Matting using Python

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Python script for human matting. It sends an image and matting model details to the API and saves the resulting transparent image.

```python
import requests
import base64

url = "http://127.0.0.1:8080/human_matting"
files = {"input_image": open("photo.jpg", "rb")}
data = {
    "human_matting_model": "modnet_photographic_portrait_matting",
    "dpi": 300,
}

response = requests.post(url, files=files, data=data).json()

if response["status"]:
    matting_image = base64.b64decode(response["image_base64"])
    with open("matting.png", "wb") as f:
        f.write(matting_image)
```

--------------------------------

### Generate Layout Photos using Python

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Python script to generate a layout of ID photos. It sends an image file and parameters like height, width, KB, and DPI to the API and saves the resulting image.

```python
import requests
import base64

url = "http://127.0.0.1:8080/generate_layout_photos"
files = {"input_image": open("idphoto_with_bg.jpg", "rb")}
data = {
    "height": 413,    # 单张证件照高度
    "width": 295,     # 单张证件照宽度
    "kb": 200,        # 输出文件大小 (KB)
    "dpi": 300,
}

response = requests.post(url, files=files, data=data).json()

if response["status"]:
    layout_image = base64.b64decode(response["image_base64"])
    with open("layout_6inch.jpg", "wb") as f:
        f.write(layout_image)
```

--------------------------------

### Generate Layout Photos using cURL

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Use this cURL command to generate a layout of ID photos from an input image with specified dimensions and quality settings.

```bash
curl -X POST "http://127.0.0.1:8080/generate_layout_photos" \
  -F "input_image=@idphoto_with_bg.jpg" \
  -F "height=413" \
  -F "width=295" \
  -F "kb=200" \
  -F "dpi=300"
```

--------------------------------

### Docker Deployment: Run API Backend Service

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/README.md

Run the API backend service in detached mode, mapping port 8080 for API requests.

```bash
docker run -d -p 8080:8080 linzeyi/hivision_idphotos python3 deploy_api.py
```

--------------------------------

### POST /set_kb

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Adjusts the file size (in KB) of an input image.

```APIDOC
## POST /set_kb

### Description
Adjusts the file size of an input image to a specified value in kilobytes while maintaining image quality as much as possible.

### Method
POST

### Endpoint
/set_kb

### Parameters
#### Query Parameters
- **kb** (integer) - Required - The target file size in kilobytes.
- **dpi** (integer) - Required - The desired resolution in dots per inch.

### Request Body
- **input_image** (file) - Required - The input image file.

### Request Example
```json
{
  "input_image": "<binary file data>"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success or failure of the operation.
- **image_base64** (string) - The image with adjusted file size, encoded in base64 format.

#### Response Example
```json
{
  "status": "success",
  "image_base64": "/9j/4AAQSkZJRgABAQ..."
}
```
```

--------------------------------

### Command-line Inference: Add Background Color

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Add a background color to a transparent image using the command-line script. Supports solid colors, vertical gradients, and radial gradients.

```bash
# render: 0=纯色, 1=上下渐变, 2=中心渐变
python inference.py \
  -t add_background \
  -i ./idphoto.png \
  -o ./idphoto_blue.jpg \
  -c 638cce \
  -k 200 \
  -r 0
```

--------------------------------

### IDCreator Core Processing

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Use the IDCreator class for local image processing. It supports various matting and detection models, as well as fine-grained control over photo composition and image enhancement.

```python
from hivision import IDCreator
from hivision.creator.choose_handler import choose_handler
import cv2

# 创建 IDCreator 实例
creator = IDCreator()

# 可选：选择抠图模型和人脸检测模型
# 抠图模型选项: modnet_photographic_portrait_matting, hivision_modnet, rmbg-1.4, birefnet-v1-lite
# 人脸检测选项: mtcnn, face_plusplus, retinaface-resnet50
choose_handler(creator, "modnet_photographic_portrait_matting", "mtcnn")

# 读取输入图像
image = cv2.imread("input.jpg")

# 生成证件照 - 基本用法
result = creator(image, size=(413, 295))  # 一寸照片尺寸 (高度, 宽度)
cv2.imwrite("standard.png", result.standard)  # 标准证件照
cv2.imwrite("hd.png", result.hd)              # 高清证件照
cv2.imwrite("matting.png", result.matting)    # 抠图结果

# 生成证件照 - 完整参数
result = creator(
    image,
    size=(413, 295),                    # 输出尺寸 (高度, 宽度)
    change_bg_only=False,               # 仅抠图模式
    crop_only=False,                    # 仅裁剪模式（输入为已抠图的RGBA图像）
    head_measure_ratio=0.2,             # 人脸面积与照片面积的比例
    head_height_ratio=0.45,             # 人脸中心在照片高度的比例
    head_top_range=(0.12, 0.1),         # 头顶距照片顶部比例范围 (max, min)
    whitening_strength=0,               # 美白强度 (0-100)
    brightness_strength=0,              # 亮度调整强度
    contrast_strength=0,                # 对比度调整强度
    sharpen_strength=0,                 # 锐化强度
    saturation_strength=0,              # 饱和度强度
    face_alignment=True,                # 是否进行人脸旋转矫正
    horizontal_flip=False,              # 是否水平翻转
)

# 仅抠图模式
matting_result = creator(image, change_bg_only=True)
cv2.imwrite("matting_only.png", matting_result.hd)
```

--------------------------------

### Human Matting API

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Performs human matting on an input RGB image, outputting a transparent RGBA image.

```APIDOC
## POST /human_matting - 人像抠图接口

### Description
This interface accepts an RGB image and outputs a matting RGBA four-channel transparent image (without background fill).

### Method
POST

### Endpoint
/human_matting

### Parameters
#### Query Parameters
- **human_matting_model** (string) - Optional - The model to use for matting. Options: modnet_photographic_portrait_matting, hivision_modnet, rmbg-1.4, birefnet-v1-lite.
- **dpi** (integer) - Optional - Dots per inch.

#### Request Body
- **input_image** (file) - Required - The input image file.

### Request Example
```json
{
  "input_image": "@photo.jpg",
  "human_matting_model": "modnet_photographic_portrait_matting",
  "dpi": 300
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the operation was successful.
- **image_base64** (string) - Base64 encoded RGBA image data.

#### Response Example
```json
{
  "status": true,
  "image_base64": "base64_encoded_rgba_image_data"
}
```
```

--------------------------------

### POST /human_matting

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Performs human matting on an input image to isolate the subject.

```APIDOC
## POST /human_matting

### Description
Performs human matting on an input image to create a transparent background around the subject using a specified model.

### Method
POST

### Endpoint
/human_matting

### Parameters
#### Query Parameters
- **human_matting_model** (string) - Required - The model to use for human matting (e.g., "modnet_photographic_portrait_matting").
- **dpi** (integer) - Required - The desired resolution in dots per inch.

### Request Body
- **input_image** (file) - Required - The input image file.

### Request Example
```json
{
  "input_image": "<binary file data>"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success or failure of the operation.
- **image_base64** (string) - The resulting image with a transparent background, encoded in base64 format.

#### Response Example
```json
{
  "status": "success",
  "image_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
}
```
```

--------------------------------

### Set Image KB Size

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Adjusts the file size of an image to a target KB value. If the target is smaller, compression is used; if larger, header information is added.

```bash
curl -X 'POST' \
  'http://127.0.0.1:8080/set_kb' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'input_image=@demo/images/test0.jpg;type=image/jpeg' \
  -F 'kb=50' \
  -F 'dpi=300'
```

--------------------------------

### Generate Layout Photos API

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Generates a 6-inch layout photo from an input image with specified dimensions and file size.

```APIDOC
## POST /generate_layout_photos

### Description
Generates a 6-inch layout photo from an input image with specified dimensions and file size.

### Method
POST

### Endpoint
/generate_layout_photos

### Parameters
#### Query Parameters
- **height** (integer) - Required - Height of the single ID photo.
- **width** (integer) - Required - Width of the single ID photo.
- **kb** (integer) - Required - Output file size in KB.
- **dpi** (integer) - Required - Dots per inch.

#### Request Body
- **input_image** (file) - Required - The input image file.

### Request Example
```json
{
  "input_image": "@idphoto_with_bg.jpg",
  "height": 413,
  "width": 295,
  "kb": 200,
  "dpi": 300
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the operation was successful.
- **image_base64** (string) - Base64 encoded image data.

#### Response Example
```json
{
  "status": true,
  "image_base64": "base64_encoded_image_data"
}
```
```

--------------------------------

### Set KB API

Source: https://context7.com/zeyi-lin/hivisionidphotos/llms.txt

Adjusts the image file size to a specified KB value by modifying compression or adding file header information.

```APIDOC
## POST /set_kb - 设置图像文件大小接口

### Description
This interface adjusts the image file size to a specified KB value, achieved by modifying compression or adding file header information.

### Method
POST

### Endpoint
/set_kb

### Parameters
#### Query Parameters
- **kb** (integer) - Required - The target file size in KB.
- **dpi** (integer) - Optional - Dots per inch.

#### Request Body
- **input_image** (file) - Required - The input image file.

### Request Example
```json
{
  "input_image": "@photo.jpg;type=image/jpeg",
  "kb": 50,
  "dpi": 300
}
```

### Response
#### Success Response (200)
- **status** (boolean) - Indicates if the operation was successful.
- **image_base64** (string) - Base64 encoded resized image data.

#### Response Example
```json
{
  "status": true,
  "image_base64": "base64_encoded_resized_image_data"
}
```
```

--------------------------------

### POST /generate_layout_photos

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Generates a six-inch formatted ID photo from an input image.

```APIDOC
## POST /generate_layout_photos

### Description
Generates a six-inch formatted ID photo from an input image with specified dimensions and file size.

### Method
POST

### Endpoint
/generate_layout_photos

### Parameters
#### Query Parameters
- **height** (integer) - Required - The desired height of the output image in pixels.
- **width** (integer) - Required - The desired width of the output image in pixels.
- **kb** (integer) - Required - The target file size in kilobytes.
- **dpi** (integer) - Required - The desired resolution in dots per inch.

### Request Body
- **input_image** (file) - Required - The input image file.

### Request Example
```json
{
  "input_image": "<binary file data>"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success or failure of the operation.
- **image_base64** (string) - The generated image encoded in base64 format.

#### Response Example
```json
{
  "status": "success",
  "image_base64": "/9j/4AAQSkZJRgABAQ..."
}
```
```

--------------------------------

### Generate ID Photo (Transparent Background)

Source: https://github.com/zeyi-lin/hivisionidphotos/blob/master/docs/api_CN.md

Generates standard and high-definition ID photos with transparent backgrounds from an input image. The transparent images can later have backgrounds added using the `add_background` endpoint.

```APIDOC
## POST /idphoto

### Description
Generates standard and high-definition ID photos with transparent backgrounds. The output includes a standard size ID photo and a high-definition version based on the specified size ratio. Both outputs are RGBA images.

### Method
POST

### Endpoint
/idphoto

### Parameters
#### Request Body
- **input_image** (file) - Optional - The input image file (RGB). Mutually exclusive with `input_image_base64`.
- **input_image_base64** (str) - Optional - Base64 encoded string of the input image (RGB). Mutually exclusive with `input_image`.
- **height** (int) - Optional - Standard ID photo height. Defaults to `413`.
- **width** (int) - Optional - Standard ID photo width. Defaults to `295`.
- **human_matting_model** (str) - Optional - Human matting model to use. Defaults to `modnet_photographic_portrait_matting`. Options: `modnet_photographic_portrait_matting`, `hivision_modnet`, `rmbg-1.4`, `birefnet-v1-lite`.
- **face_detect_model** (str) - Optional - Face detection model to use. Defaults to `mtcnn`. Options: `mtcnn`, `face_plusplus`, `retinaface-resnet50`.
- **hd** (bool) - Optional - Whether to generate high-definition ID photo. Defaults to `true`.
- **dpi** (int) - Optional - Image resolution. Defaults to `300`.
- **face_alignment** (bool) - Optional - Whether to perform face alignment. Defaults to `true`.
- **head_measure_ratio** (float) - Optional - Ratio of face area to photo area. Defaults to `0.2`.
- **head_height_ratio** (float) - Optional - Ratio of face center to photo top. Defaults to `0.45`.
- **top_distance_max** (float) - Optional - Maximum ratio of head to photo top distance. Defaults to `0.12`.
- **top_distance_min** (float) - Optional - Minimum ratio of head to photo top distance. Defaults to `0.1`.
- **brightness_strength** (float) - Optional - Brightness adjustment strength. Defaults to `0`.
- **contrast_strength** (float) - Optional - Contrast adjustment strength. Defaults to `0`.
- **sharpen_strength** (float) - Optional - Sharpening adjustment strength. Defaults to `0`.
- **saturation_strength** (float) - Optional - Saturation adjustment strength. Defaults to `0`.

### Response
#### Success Response (200)
- **status** (int) - Status code, `true` indicates success.
- **image_base64_standard** (str) - Base64 encoded string of the standard ID photo.
- **image_base64_hd** (str) - Base64 encoded string of the high-definition ID photo. Omitted if `hd` is `false`.

#### Response Example
```json
{
  "status": true,
  "image_base64_standard": "...",
  "image_base64_hd": "..."
}
```
```
Tokens:
Raw