HivisionIDPhotos v1.3.1 API 使用详解

目标：把 HivisionIDPhotos 的证件照能力集成进你自己的系统。本篇面向开发者，覆盖项目对外暴露的全部 7 个 HTTP 接口——生成证件照（/idphoto）、人像抠图（/human_matting）、添加背景色（/add_background）、生成六寸排版照（/generate_layout_photos）、图像加水印（/watermark）、设置图像 KB（/set_kb）、证件照裁切（/idphoto_crop）。该项目无官方鉴权、无内建限流，定位是纯内网 API：所有业务接口均为 POST multipart/form-data，图像以「文件上传」或「base64 字符串」二选一传入。文中全部请求与回显均为 2026-10-25 在本地部署的 v1.3.1 实例上 curl 实测取证，逐条可复现；官方文档与本机 OpenAPI 规范逐条比对过的差异点也会明确标出。部署过程见本专栏部署篇，模型选择与配置见本专栏配置篇，项目定位与选型见本专栏介绍篇。

一、环境信息

本篇实测与取证环境如下，读者操作时请替换为自己的取值：

• 服务版本：HivisionIDPhotos v1.3.1（官方仓库 release v1.3.1 口径）
• API 服务：FastAPI 应用（入口 deploy_api.py，底层 uvicorn），API base http://localhost:8139
• Web UI：Gradio 应用，独立监听 http://localhost:8138——它是给人用的网页界面，不是本篇 API 的一部分，两者不要混用
• 交互式文档：GET /docs（Swagger UI 页面）、GET /openapi.json（机器可读接口规范），这两个 GET 请求同时也是最方便的探活手段
• 测试图像：test0.jpg（正常人像照，作为主测试图）；blank.jpg（600×800 的 JPEG，画面无正脸，用于触发「未检测到人脸」错误）
• 实测工具：curl 命令行；耗时数据为本地热态实测（CPU 推理），仅供量级参考

取证方式说明：接口清单与参数定义以本机 GET /openapi.json 实查为准（v1.3.1 实例），并与官方仓库 docs/api_CN.md（查询日期 2026-10-25）逐条比对；文中每条 curl 请求都配有真实回显，base64 字段过长时以「…（共 N 字符）」形式截断，字符数与关键字段均为实测原值。

二、API 总览

v1.3.1 共 7 个业务端点，全部为 POST，请求体统一为 multipart/form-data：

两个非业务请求：GET /docs 返回 Swagger UI 页面（HTTP 200），GET /openapi.json 返回 OpenAPI 3.1 规范 JSON——生产探活建议用后者，响应小且能顺带校验服务进程存活。

三、请求格式与鉴权

3.1 无鉴权，但要先想好暴露面

本机实例的 OpenAPI 规范中未定义任何 security scheme，所有接口不带 Token、不做签名，请求头无任何要求。这意味着网络可达即可调用：部署时务必让它只监听内网/本机，公网暴露必须自己加前置层（见第八章）。

3.2 图像的两种传法：文件上传与 base64 字符串

每个接口都接受 input_image（文件上传）与 input_image_base64（base64 字符串）二选一。对同一张 test0.jpg，两种传法实测输出完全一致（两次请求回显中 image_base64_standard 均为 209046 字符、image_base64_hd 均为 629158 字符）：

# 传法一：multipart 文件上传（2026-10-25 实测，http=200，time=0.680s）
curl -s -o resp1.json -w "http=%{http_code} time=%{time_total}s\n" \
  http://localhost:8139/idphoto \
  -F "input_image=@test0.jpg"

# 传法二：multipart 表单字段里放裸 base64（不带 data: 前缀）
# 实测 http=200，time=0.367s，输出与传法一逐字符一致
curl -s -o resp2.json -w "http=%{http_code} time=%{time_total}s\n" \
  http://localhost:8139/idphoto \
  -F "input_image_base64=<b64.txt"

-F "input_image_base64=<b64.txt" 的 < 语义是「把文件内容作为字段值」而不是上传文件，正好用来绕开命令行参数长度限制——直接把几十万字符的 base64 拼在命令行里会报 Argument list too long（实测踩过）。base64 串用裸串即可（实测素材以 /9j/ 开头的 JPEG 裸 base64 成功），无需拼 data URI。

3.3 千万别用 application/json 发请求体

接口 schema 是 multipart/form-data，把 base64 装进 JSON 用 Content-Type: application/json 发送不是 422 而是 500（2026-10-25 实测，0.0015s 即被拒）：

curl -s -o err.txt -w "http=%{http_code} time=%{time_total}s\n" -X POST \
  http://localhost:8139/idphoto \
  -H 'Content-Type: application/json' \
  --data-binary '{"input_image_base64":"...","height":413,"width":295}'

http=500 time=0.001527s
Internal Server Error

这是集成时最容易踩的坑：直觉上「JSON API」就该发 JSON，但这个服务不认。所有请求老老实实走 multipart 表单。

四、核心端点详解

以下每个端点都给出用途、参数、真实 curl 与回显。回显中 base64 一律截断，但 status、字段名、字符数均为实测原值。耗时为 2026-10-25 本地热态实测。

4.1 /idphoto：生成证件照（底透明）

逻辑：输入一张 RGB 图像，输出两张透明底（RGBA）证件照——标准照尺寸严格等于 width×height（默认 295×413，即一寸），高清照按同比例放大制作。官方文档解释了为什么输出透明底：产品里用户会频繁切换底色预览，前端拿透明图自行合成底色体验最好；所以拿到结果后通常要接 /add_background。

参数表（来源：本机 OpenAPI 实查 v1.3.1）：

⚠️ 文档与实例不一致点：官方 docs/api_CN.md 把人脸对齐参数写作 face_alignment 且默认 true；本机 v1.3.1 实例的 OpenAPI 规范里参数名是 face_align、默认 false。实测日志佐证：不带该参数的请求没有对齐步骤，带 face_align=true 的请求多出 [3.1] Face Alignment Time: 0.059s 一段，且输出 base64 长度不同（默认 209046 字符 vs 开启对齐 199630 字符）。集成时以你部署版本的 /openapi.json 为准。

请求与回显（2026-10-25 实测，http=200 time=0.680s，首次调用含预热；同会话再次调用 0.367s）：

curl -s -o resp.json -w "http=%{http_code} time=%{time_total}s\n" \
  http://localhost:8139/idphoto \
  -F "input_image=@test0.jpg" \
  -F "height=413" -F "width=295" -F "hd=true" -F "dpi=300"

{
  "status": true,
  "image_base64_standard": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg…（共 209046 字符，295×413 RGBA PNG，约 157KB）",
  "image_base64_hd": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg…（共 629158 字符，600×844 RGBA PNG）"
}

• hd=false 时响应里没有 image_base64_hd 这个键（实测确认），解析时不要假设它存在。
• 单次响应 JSON 总体积约 0.8MB（素材实测 838,267 字节），客户端要按这个量级预留缓冲。
• 推理管线各段耗时（服务端日志实测）：人像抠图约 0.4s 占绝对大头，人脸检测约 0.02s，对齐约 0.06s，整请求约 0.43–0.68s。

4.2 /human_matting：人像抠图

输入 RGB 图像，输出一张无背景填充的透明底人像 PNG。适合不裁切、只要「抠出来」的场景（换自定义背景、贴到海报上等）。

⚠️ 又一处不一致：/idphoto 里该参数默认 modnet_photographic_portrait_matting，而 /human_matting 端点的 OpenAPI 默认写的是 hivision_modnet（官方文档则统一写前者）。建议集成时显式传参，不要依赖默认值。

请求与回显（2026-10-25 实测，http=200 time=0.405s）：

curl -s -o matting.json -w "http=%{http_code} time=%{time_total}s\n" \
  http://localhost:8139/human_matting \
  -F "input_image=@test0.jpg" \
  -F "human_matting_model=modnet_photographic_portrait_matting" \
  -F "dpi=300"

{
  "status": true,
  "image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg…（共 602694 字符，576×768 RGBA PNG，与输入图同尺寸）"
}

输出尺寸与输入图一致，不会缩放。

4.3 /add_background：添加背景色

输入 RGBA 透明图（一般来自 /idphoto 或 /human_matting），按 HEX 色值合成背景，输出成品证件照。

请求与回显（2026-10-25 实测，http=200 time=0.020s，输入为 4.1 的标准照文件 std.png）：

curl -s -o bg.json -w "http=%{http_code} time=%{time_total}s\n" \
  http://localhost:8139/add_background \
  -F "input_image=@std.png;type=image/png" \
  -F "color=438cdb" -F "render=0" -F "dpi=300"

{
  "status": true,
  "image_base64": "data:image/png;base64,…（解码后 111497 字节，295×413）"
}

带 kb 参数时（实测 kb=200，time=0.009s），解码后恰好 204800 字节 = 200 × 1024，且格式变为 JPEG。KB 控制是精确到字节的，不是「约等于」。

4.4 /generate_layout_photos：生成六寸排版照

输入 RGB 成品证件照，按 height×width 的小照尺寸自动排布，输出一张六寸照（300dpi 下实测 1795×1205 像素）。用于直接送打印。

请求与回显（2026-10-25 实测，http=200 time=0.067s，输入为 4.3 的换底成品 bg.jpg）：

curl -s -o layout.json -w "http=%{http_code} time=%{time_total}s\n" \
  http://localhost:8139/generate_layout_photos \
  -F "input_image=@bg.jpg;type=image/jpeg" \
  -F "height=413" -F "width=295" -F "dpi=300"

{
  "status": true,
  "image_base64": "data:image/png;base64,…（解码后 262690 字节，1795×1205 PNG）"
}

4.5 /watermark：图像加水印

给图像平铺水印文字。注意它的参数分两处：水印样式走 URL 查询串，图像与文本走 multipart 表单——这是 7 个端点里唯一的特例。

请求与回显（2026-10-25 实测，http=200 time=0.022s，输入为 4.3 的换底成品）：

curl -s -o wm.json -w "http=%{http_code} time=%{time_total}s\n" \
  "http://localhost:8139/watermark?size=20&opacity=0.5&angle=30&color=%23000000&space=25" \
  -F "input_image=@bg.jpg;type=image/jpeg" \
  -F "text=QUZUO DEMO" -F "dpi=300"

{
  "status": true,
  "image_base64": "data:image/png;base64,iVBORw0KGgo…（解码后 150744 字节，295×413 PNG）"
}

💡 水印输出是无损 PNG：111KB 的 JPEG 输入加水印后变成约 151KB 的 PNG，体积不降反升。在意体积就再过一道 /set_kb，或直接给 /watermark 传 kb 参数。

4.6 /set_kb：设置图像 KB 大小

把任意图像调整到指定文件大小：目标小于原文件就走压缩，大于原文件就往文件头填充信息，最终大小与目标一致。报名系统、签证系统对照片体积有硬性要求时用它兜底。

请求与回显（2026-10-25 实测，http=200 time=0.005s）：

curl -s -o kb.json -w "http=%{http_code} time=%{time_total}s\n" \
  http://localhost:8139/set_kb \
  -F "input_image=@bg.jpg;type=image/jpeg" \
  -F "kb=50" -F "dpi=300"

{
  "status": true,
  "image_base64": "data:image/png;base64,…（解码后恰好 51200 字节 = 50×1024，JPEG）"
}

实测 kb=50 得 51200 字节、kb=100 得 102400 字节、kb=200 得 204800 字节——精确等于 KB×1024，这是 7 个端点里行为最「死板」也最可靠的一个。

4.7 /idphoto_crop：证件照裁切

输入 RGBA 透明人像（/human_matting 或 /idphoto 的产物），按目标尺寸重新裁切出标准照 + 高清照。适合「先抠图存底、再按多种规格反复出照」的集成形态，裁切阶段不再跑分割模型，速度比 /idphoto 快（实测 0.28s vs 0.68s）。

请求与回显（2026-10-25 实测，http=200 time=0.279s，输入为 4.2 的抠图结果）：

curl -s -o crop.json -w "http=%{http_code} time=%{time_total}s\n" \
  http://localhost:8139/idphoto_crop \
  -F "input_image=@matting.png;type=image/png" \
  -F "height=413" -F "width=295" \
  -F "face_detect_model=mtcnn" -F "hd=true" -F "dpi=300"

{
  "status": true,
  "image_base64_standard": "data:image/png;base64,iVBORw0KGgo…（共 209046 字符，295×413 RGBA PNG）",
  "image_base64_hd": "data:image/png;base64,iVBORw0KGgo…（共 629158 字符）"
}

⚠️ 输入通道要求是硬约束：直接把 RGB 的 JPG 喂给它，服务直接 500（实测回显见第六章），报错信息不会提示「通道不对」。

五、参数组合实战

需求：一张 295×413、蓝色底（#438CDB）、不超过 200KB 的 JPG 成品照，外加一张六寸排版照。三个接口串联即可，全程 2026-10-25 实测，产物字节量逐一落盘核对。

第 1 步：生成透明底标准照 + 高清照（耗时 0.680s）

curl -s http://localhost:8139/idphoto -F "input_image=@test0.jpg" \
  -F "height=413" -F "width=295" -F "hd=true" -F "dpi=300" > step1.json

回显关键字段：status=true，image_base64_standard 209046 字符。解码落盘 std.png（156767 字节，file 确认 PNG image data, 295 x 413, 8-bit/color RGBA）。

第 2 步：合成蓝底并压到 200KB（耗时 0.009s）

curl -s http://localhost:8139/add_background \
  -F "input_image=@std.png;type=image/png" \
  -F "color=438cdb" -F "render=0" -F "kb=200" -F "dpi=300" > step2.json

回显 status=true；解码落盘 204800 字节（=200×1024，恰好达标），file 确认 JPEG、300dpi。

第 3 步：出六寸排版照（耗时 0.019s）

curl -s http://localhost:8139/generate_layout_photos \
  -F "input_image=@bg200.jpg;type=image/jpeg" \
  -F "height=413" -F "width=295" -F "kb=200" -F "dpi=300" > step3.json

回显 status=true；解码落盘同样 204800 字节，JPEG。

三点经验：① 换底这步顺手带 kb 参数，可以省掉单独调 /set_kb 的一次往返；② 排版照的 height/width 填的是小照尺寸（第 2 步产物是 295×413，就传 413/295），不是排版照尺寸；③ 全链路热态总耗时 1 秒上下，其中 /idphoto 占九成。

六、错误语义与限流

6.1 三种响应形态

422 的响应体是标准 FastAPI 结构（2026-10-25 实测原文）：

{"detail":[{"type":"int_parsing","loc":["body","height"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"abc"}]}

6.2 500 的四种实测场景

业务失败和服务器异常都返回同一个 500 纯文本，无法从响应区分：

1. 图里没有正脸：blank.jpg（600×800、无正脸）POST /idphoto → 500。服务端日志显示 mtcnn 检测阶段抛 ValueError: need at least one array to concatenate。
2. 两个图像字段都没传：只带 height 调 /idphoto → 500。
3. 用了 JSON 请求体：Content-Type: application/json 打 /idphoto → 500（0.0015s 拒绝，见 3.3）。
4. 通道不对：RGB 的 JPG 直接打 /idphoto_crop（要求 RGBA）→ 500。

集成的正确姿势：把 500 当作「请求被拒」处理并附上重试上限，同时在客户端先做前置校验（图片能解码、含可检人脸、RGBA 给对端点），不要指望服务端给你细粒度错误信息。另外注意 /idphoto 内部还有可选的第三方云检测模型 face_plusplus，选它就要出网调外部服务，与纯内网部署的定位冲突，内网集成别选它。

6.3 无内建限流

OpenAPI 规范中没有任何限流相关定义，服务也不自带鉴权——防刷、排队、按调用方限速全部要靠前置反向代理或网关实现（见第八章）。

七、CLI 形态速览

同一套能力还有命令行形态，入口是仓库根目录的 inference.py，本地跑模型、不经 HTTP。python inference.py -h 实测帮助原文（节选）：

usage: inference.py [-h]
                    [-t {idphoto,human_matting,add_background,generate_layout_photos,idphoto_crop}]
                    -i INPUT_IMAGE_DIR -o OUTPUT_IMAGE_DIR [--height HEIGHT]
                    [--width WIDTH] [-c COLOR] [--hd HD] [-k KB] [-r {0,1,2}]
                    [--dpi DPI] [--face_align FACE_ALIGN]
                    [--matting_model {hivision_modnet,modnet_photographic_portrait_matting,mnn_hivision_modnet,rmbg-1.4,birefnet-v1-lite}]
                    [--face_detect_model {mtcnn,face_plusplus,retinaface-resnet50}]

HivisionIDPhotos 证件照制作推理程序。
  -t, --type          请求 API 的种类
  -i, --input_image_dir   输入图像路径
  -o, --output_image_dir  保存图像路径
  -k, --kb            输出照片的 KB 值，仅对换底和制作排版照生效
  -r, --render        底色合成的模式，有 0:纯色、1:上下渐变、2:中心渐变 可选

与 HTTP API 的三点差异：① 任务只覆盖 5 种，没有 watermark 和 set_kb；② 分割模型多一个 mnn_hivision_modnet（MNN 加速版，API 端点不提供）；③ 产物直接落盘文件，不走 base64。-t idphoto 跑单张的实测日志回显：

[1]  Start Human Matting...
[1]  Human Matting Time: 0.281s
[2]  Start Beauty...
[2]  Beauty Time: 0.000s
[3]  Start Face Detection...
[3]  Face Detection Time: 0.016s
[4]  Start Image Post-Adjustment...
[4]  Image Post-Adjustment Time: 0.003s
[Total]  Total Time: 0.301s

选型建议：偶尔批量处理本机文件用 CLI 更省事；要嵌进业务系统、多调用方共享一套模型服务，用本篇的 HTTP API。

八、集成注意事项

1. 响应体积按 MB 级预留：base64 编码膨胀约 37%，/idphoto 一次返回标准 + 高清两张 PNG，响应 JSON 实测约 0.8MB。网关、负载均衡的请求/响应体上限别按普通 JSON API 配。
2. 别信 base64 前缀，按魔数解码：所有接口的 data URI 前缀固定是 data:image/png;base64,，但带 kb 参数时（/add_background、/generate_layout_photos、/set_kb）实际负载是 JPEG（实测 /9j/ 开头）。正确做法：掐掉逗号前的前缀后，按文件魔数（\x89PNG / \xff\xd8\xff）判断真实格式再落盘。
3. KB 是精确控制：kb=N 输出严格等于 N×1024 字节（50/100/200 三档实测），可以做依赖体积上限的业务断言。
4. 超时与冷启动：热态下所有接口亚秒级返回；但服务刚启动后的第一批请求要现场加载分割/检测模型，耗时显著变长。客户端超时建议放宽到 30s 以上，并在发布后做一次预热调用。
5. 并发能力有限：每个请求同步执行 CPU 推理（抠图一段约占 0.4s），服务没有内建排队机制。高并发场景在前置层做排队/限并发，或按流量水平扩多个服务实例分摊。
6. 暴露面收口：无鉴权 + 无限流意味着只能内网互信。生产形态建议：服务只绑定内网地址，前面挂反向代理补「鉴权 + 限流 + 请求体大小限制」，对外绝不直接裸暴露 8139 端口。
7. 客户端传 base64 的姿势：程序内构造 multipart 表单时，input_image_base64 字段直接放裸 base64 字符串即可；命令行 curl 用 -F "字段=<文件" 读文件，避免参数超长。

九、FAQ

Q1：base64 图片到底怎么传？直接 POST JSON 为什么不行？ 放进 multipart 表单字段 input_image_base64。服务只按 multipart/form-data 解析请求体，发 application/json 直接 500（第三章实测）。Python requests 用 files={"input_image_base64": (None, b64_str)} 的写法即可。

Q2：拿到 500 是不是服务挂了？ 不一定。无人脸、缺图像字段、JSON 体、通道不对这四种请求侧问题都返回 500 纯文本。先自查请求，再看 /docs 是否还活着，最后才考虑服务故障。

Q3：为什么解码出来的图片是 JPG，前缀却是 data:image/png？ 服务的固定行为，前缀不可信，按魔数判断格式（第八章第 2 条）。只有不带 kb 的换底/排版输出和 /idphoto、/human_matting、/watermark、/idphoto_crop 的输出才是真 PNG。

Q4：要 JPG 不要 PNG 怎么办？ 换底（/add_background）或排版（/generate_layout_photos）时带上 kb 参数，输出即为 JPEG 且体积精确可控；或对任意成品图调 /set_kb。

Q5：人脸对齐参数到底叫什么？默认开还是关？ 以你部署实例的 /openapi.json 为准。本机 v1.3.1 实测参数名 face_align、默认关闭（开启后服务端日志多出 Face Alignment 段、输出 base64 长度变化）；官方文档写作 face_alignment 默认开启，与实例不一致。

Q6：/watermark 的样式参数（字号、透明度、角度）放在哪？ 放 URL 查询串，不放在表单里；color 的 # 必须编码为 %23。这是 7 个端点里唯一的参数位置特例（4.5 节实测请求可照抄）。

Q7：命令行传大 base64 报 Argument list too long？ 用 curl -F "input_image_base64=<b64.txt" 让 curl 从文件读字段值（3.2 节实测解法）。

Q8：六寸排版照到底是多大？ 300dpi 下实测 1795×1205 像素（4.4 节 file 确认）。若导出打印件尺寸不对，先检查 dpi 参数是否与打印设置一致。

十、参考链接

• 官方仓库：https://github.com/Zeyi-Lin/HivisionIDPhotos （查询日期 2026-10-25）
• 官方 API 中文文档：https://github.com/Zeyi-Lin/HivisionIDPhotos/blob/master/docs/api_CN.md （查询日期 2026-10-25；本文参数已与本机 v1.3.1 实例 /openapi.json 逐条比对）
• 本机 Swagger UI：http://localhost:8139/docs （内网）
• 服务启动入口与监听参数：仓库 deploy_api.py（支持 --port / --host / --root_path）
• 本专栏系列：项目定位与选型见本专栏介绍篇，部署过程见本专栏部署篇，模型选择与配置见本专栏配置篇