Based on the HivisionIDPhotos API to generate compliant ID photos.
Prerequisites
# 部署 API 服务（任选一种）
docker run -d -p 8080:8080 linzeyi/hivision_idphotos python3 deploy_api.py
# 设置环境变量
export IDPHOTO_API_URL="http://127.0.0.1:8080"
Quick Start
bash {skillDir}/scripts/idphoto.sh --image photo.jpg --color blue --size 一寸
Preset Sizes
| --size | Pixels @300DPI | Width×Height (mm) | Common Uses |
|---|---|---|---|
| 1-inch | 295×413 | 25×35 | ID card, resume |
| 2-inch | 413×579 | 35×49 | Graduation certificate |
| Small 1-inch | 260×378 | 22×32 | Driver's license |
| Small 2-inch | 413×531 | 35×45 | Passport (some countries) |
| Large 1-inch | 390×567 | 33×48 | Passport, Hong Kong and Macau Travel Permit |
| Passport | 390×567 | 33×48 | Chinese passport |
| Hong Kong and Macau Travel Permit | 390×567 | 33×48 | Hong Kong and Macau Travel Permit |
Preset Colors
| --color | HEX | Use |
|---|---|---|
| white / white | #FFFFFF | ID card, passport, driver's license |
| blue / blue | #438EDB | Graduation certificate, Hong Kong and Macau Travel Permit |
| red / red | #C8102E | Marriage certificate |
Custom HEX is also supported:--color 4CAF50
Custom Size
bash {skillDir}/scripts/idphoto.sh --image photo.jpg --color white --width 390 --height 567
Parameter Reference
| Parameter | Required | Description |
|---|---|---|
--image |
Yes | Input photo path |
--color |
No | Background color (default white) |
--size |
No | Preset size name |
--width |
No | Custom width, overrides --size |
--height |
No | Custom height, overrides --size |
--output |
No | Output directory (default .) |
--dpi |
No | DPI (default 300) |
Processing Flow
输入照片
│
▼
Step 1: POST /idphoto
人脸检测 → 抠图 → 人脸对齐 → 裁切
→ 输出透明底 RGBA PNG
│
▼
Step 2: POST /add_background
透明底 + 指定背景色 → JPG 成品
→ 输出合规证件照
Advanced Usage
Adjust Face Proportion
Default values in the edit script:
# 头部占画面高度比 (默认 0.45, 范围 0.4-0.5)
HEAD_HEIGHT_RATIO=0.45
# 头部宽度占画面比 (默认 0.2, 范围 0.15-0.25)
HEAD_MEASURE_RATIO=0.2
# 顶部边距范围 (默认 0.1-0.12)
TOP_DISTANCE_MIN=0.1
TOP_DISTANCE_MAX=0.12
Generate a layout photo (6-inch photo paper)
curl -X POST "$IDPHOTO_API_URL/generate_layout_photos" \
-F "input_image=@photo.jpg" \
-F "height=413" -F "width=295" -F "dpi=300" \
-o layout.jpg
Cutout Model Selection
| Model | Speed | Accuracy | Suitable For |
|---|---|---|---|
hivision_modnet (default) |
Fast | Medium | Best for solid-color background replacement |
modnet_photographic_portrait_matting |
Fastest | Medium | General purpose |
birefnet-v1-lite |
Slow | Highest | Fine hair strands, semi-transparent clothing |
API Reference
For the full API documentation, see references/openapi.yaml
Troubleshooting
| Problem | Solution |
|---|---|
| Connection failed | Check whether $IDPHOTO_API_URL and Docker are running |
| Face not detected | Use a frontal photo with even lighting |
| Crop too high/too low | Adjust head_height_ratio and top_distance_* |
| File too large | Use the /set_kb endpoint to compress |
Source
HivisionIDPhotos - https://github.com/Zeyi-Lin/HivisionIDPhotos (MIT)