HivisionIDPhoto Docker部署以及Springboot接口对接(AI证件照制作)

项目简介

项目以及官方文档地址

HivisionIDPhoto 旨在开发一种实用、系统性的证件照智能制作算法。

它利用一套完善的AI模型工作流程,实现对多种用户拍照场景的识别、抠图与证件照生成。

HivisionIDPhoto 可以做到:

  1. 轻量级抠图(纯离线,仅需 CPU 即可快速推理)
  2. 根据不同尺寸规格生成不同的标准证件照、六寸排版照
  3. 支持 纯离线 或 端云 推理
  4. 美颜
  5. 智能换正装(waiting)

Docker 部署

拉取镜像

官方再docker hub是有镜像源的,但是因为某些原因可能pull失败,我备份了一份到阿里云镜像仓库(官方版本为1.2.9),如下拉取镜像

docker pull registry.cn-hangzhou.aliyuncs.com/zr-dev/hivision_idphotos:v1.0

启动 Gradio Demo 服务

运行下面的命令,在你的本地访问 http://127.0.0.1:7860 即可使用。

docker run -d -p 7860:7860 registry.cn-hangzhou.aliyuncs.com/zr-dev/hivision_idphotos:v1.0

启动 API 后端服务

此处我将容器内部的8080端口映射到本机的8087,读者可以自定义想要映射的端口

docker run -d -p 8087:8080 registry.cn-hangzhou.aliyuncs.com/zr-dev/hivision_idphotos:v1.0 python3 deploy_api.py

服务启动后咱们就可以调用服务的接口了**(为了防止特殊原因,api文档也备份了一份在文章末尾,并附上官方接口文档地址)**

Springboot 进行接口对接

抽取配置文件,将HivisionIDPhoto后端服务的地址抽取为配置类

photo:
  id-photo-base-url: http://127.0.0.1:8087

生成证件照(底透明)+添加背景色

  1. 此处我只需要实现生成证件照的功能,总共需要对接如下两个接口,如果读者还有其他需求可以,参考官方文档
  2. callIdPhotoApi
    1. inputPath: 将图片上传到/ai/img/input/2024/10/24/60182299d7d371cbe2b0b7c9f9c8234_20241024111616A001.jpg(即代码中的inputPath)
      1. 上传代码可以参考我的另一篇文章SpringBoot 上传图片-指定目录按照日期存储
    2. height: 生成证件照的高
    3. width: 生成证件照的宽
    4. human_matting_model和face_detect_model可以根据自己的需求更换
  3. addBackground
    1. inputImageBase64: 生成的结果(base64图片)
    2. color: 背景色HEX值,默认为000000
    3. fileService.upload() :将生成的证件照上传到阿里云oss,生成url
import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.http.HttpUtil;
import com.alibaba.fastjson2.JSONObject;
import com.aliyun.openservices.shade.com.alibaba.fastjson.JSON;
import com.hss.common.utils.uuid.UUID;
import com.hss.system.service.FileService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;

import java.io.File;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;


/**
 * @author zr 2024/10/24
 */

@Service
@Slf4j
public class ImageProcessor {

    @Autowired
    private FileService fileService;

    @Value("${photo.id-photo-base-url}")
    private String idPhotoBaseUrl;

    public String callIdPhotoApi(String inputPath,Integer height,Integer width) {
        String url = idPhotoBaseUrl+"/idphoto";
        Map<String, String> headers = new HashMap<>();
        // 根据需要添加头部信息,例如:
        // headers.put("Content-Type", "multipart/form-data");

        Map<String, Object> parameters = new HashMap<>();
        parameters.put("input_image", new File(inputPath));
        parameters.put("height", height);
        parameters.put("width", width);
        parameters.put("human_matting_model", "rmbg-1.4"); //人像分割模型,默认为modnet_photographic_portrait_matting。可选值为modnet_photographic_portrait_matting、hivision_modnet、rmbg-1.4、birefnet-v1-lite
        parameters.put("face_detect_model", "mtcnn"); //人脸检测模型,默认为mtcnn。可选值为mtcnn、face_plusplus、retinaface-resnet50
        parameters.put("hd", true);
        parameters.put("dpi", 300);
        parameters.put("face_alignment", true);

        HttpResponse response = httpPost(url, headers, parameters);
        // 处理响应
        String body = response.body();
        JSONObject jsonObject = com.alibaba.fastjson2.JSON.parseObject(body);
        Boolean status = jsonObject.getBoolean("status");
        if (status){
            String imageData = jsonObject.getString("image_base64_hd");
            return imageData;
        } else {
            log.info("请求失败{}");
            return null;
        }
    }

    public String addBackground(String inputImageBase64,String color) {
        String url = idPhotoBaseUrl+"/add_background";
        Map<String, String> headers = new HashMap<>();
        // 根据需要添加头部信息,例如:
        // headers.put("Content-Type", "multipart/form-data");

        Map<String, Object> parameters = new HashMap<>();

        // 添加请求参数
        parameters.put("input_image_base64", inputImageBase64);
        parameters.put("color", color);
//        parameters.put("kb", kb); //输出照片的 KB 值,默认为None,即不对图像进行KB调整。
//        parameters.put("render", render); //渲染模式,默认为0。可选值为0、1、2,分别对应纯色、上下渐变、中心渐变。
//        parameters.put("dpi", dpi); //图像分辨率,默认为300

        HttpResponse response = httpPost(url, headers, parameters);
        // 处理响应
        String body = response.body();
        JSONObject jsonObject = com.alibaba.fastjson2.JSON.parseObject(body);
        Boolean status = jsonObject.getBoolean("status");
        if (status){
            String imageData = jsonObject.getString("image_base64");
            // 检查并去掉 Base64 前缀
            if (imageData.startsWith("data:image/")) {
                imageData = imageData.substring(imageData.indexOf(",") + 1);
            }
            byte[] imageBytes = Base64.getDecoder().decode(imageData);
            String upload = fileService.upload(imageBytes, UUID.fastUUID() + ".jpg");
            return upload;
        } else {
            log.info("请求失败{}");
            return null;
        }
    }
    private HttpResponse httpPost(String url,Map<String, String> headers,Map<String, Object> parameter) {
        HttpRequest httpRequest = HttpUtil.createPost(url).form(parameter).addHeaders(headers);
        HttpResponse response = httpRequest.execute();
        log.info("Url: "+httpRequest.getUrl());
        log.info("head: "+JSON.toJSONString(httpRequest.headers()));
        log.info("parame: "+JSON.toJSONString(httpRequest.form()));
        log.info("res: "+response.body());
        return response;
    }
}

测试

import lombok.extern.slf4j.Slf4j;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

/**
 * @author zr 2024/10/24
 */
@RunWith(SpringRunner.class)
@SpringBootTest(classes = HssApplication.class)
@Slf4j
public class IdPhotoTest {
    @Autowired
    private ImageProcessor imageProcessor;

    @Test
    public void callIdPhotoApi() {
        String s = imageProcessor.callIdPhotoApi("/ai/img/input/2024/10/24/60182299d7d371cbe2b0b7c9f9c8234_20241024111616A001.jpg",413,295);
        log.info(s);
    }

    @Test
    public void addBackground() {
        String s = imageProcessor.addBackground(imageProcessor.callIdPhotoApi("/ai/img//input/2024/10/24/23-Authentic-Chinese-Hairstyle-Ideas-00-scaled_20241024133448A001.jpg",413,295), "638cce");
        log.info(s);
    }
}

测试结果

  1. 原图

  1. callIdPhotoApi测试结果

  1. addBackground测试结果

API Docs

官方api文档地址

目录

开始之前:开启后端服务

在请求 API 之前,请先运行后端服务

python deploy_api.py

接口功能说明

1.生成证件照(底透明)

接口名:idphoto

生成证件照接口的逻辑是发送一张 RGB 图像,输出一张标准证件照和一张高清证件照:

  • 高清证件照:根据size的宽高比例制作的证件照,文件名为output_image_dir增加_hd后缀
  • 标准证件照:尺寸等于size,由高清证件照缩放而来,文件名为output_image_dir

需要注意的是,生成的两张照片都是透明的(RGBA 四通道图像),要生成完整的证件照,还需要下面的添加背景色接口。

问:为什么这么设计?
答:因为在实际产品中,经常用户会频繁切换底色预览效果,直接给透明底图像,由前端 js 代码合成颜色是更好体验的做法。

请求参数:

参数名类型必填说明
input_imagefileinput_image_base64二选一传入的图像文件,图像文件为需为RGB三通道图像。
input_image_base64strinput_image二选一传入的图像文件的base64编码,图像文件为需为RGB三通道图像。
heightint标准证件照高度,默认为413
widthint标准证件照宽度,默认为295
human_matting_modelstr人像分割模型,默认为modnet_photographic_portrait_matting。可选值为modnet_photographic_portrait_mattinghivision_modnetrmbg-1.4birefnet-v1-lite
face_detect_modelstr人脸检测模型,默认为mtcnn。可选值为mtcnnface_plusplusretinaface-resnet50
hdbool是否生成高清证件照,默认为true
dpiint图像分辨率,默认为300
face_alignmentbool是否进行人脸对齐,默认为true
head_measure_ratiofloat面部面积与照片面积的比例,默认为0.2
head_height_ratiofloat面部中心与照片顶部的高度比例,默认为0.45
top_distance_maxfloat头部与照片顶部距离的比例最大值,默认为0.12
top_distance_minfloat头部与照片顶部距离的比例最小值,默认为0.1

返回参数:

参数名类型说明
statusint状态码,true表示成功
image_base64_standardstr标准证件照的base64编码
image_base64_hdstr高清证件照的base64编码。如hd参数为false,则不返回该参数

2.添加背景色

接口名:add_background

添加背景色接口的逻辑是接收一张 RGBA 图像(透明图),根据color添加背景色,合成一张 JPG 图像。

请求参数:

参数名类型必填说明
input_imagefileinput_image_base64二选一传入的图像文件,图像文件为需为RGBA四通道图像。
input_image_base64strinput_image二选一传入的图像文件的base64编码,图像文件为需为RGBA四通道图像。
colorstr背景色HEX值,默认为000000
kbint输出照片的 KB 值,默认为None,即不对图像进行KB调整。
renderint渲染模式,默认为0。可选值为012,分别对应纯色上下渐变中心渐变
dpiint图像分辨率,默认为300

返回参数:

参数名类型说明
statusint状态码,true表示成功
image_base64str添加背景色之后的图像的base64编码

3.生成六寸排版照

接口名:generate_layout_photos

生成六寸排版照接口的逻辑是接收一张 RGB 图像(一般为添加背景色之后的证件照),根据size进行照片排布,然后生成一张六寸排版照。

请求参数:

参数名类型必填说明
input_imagefileinput_image_base64二选一传入的图像文件,图像文件为需为RGB三通道图像。
input_image_base64strinput_image二选一传入的图像文件的base64编码,图像文件为需为RGB三通道图像。
heightint输入图像的高度,默认为413
widthint输入图像的宽度,默认为295
kbint输出照片的 KB 值,默认为None,即不对图像进行KB调整。
dpiint图像分辨率,默认为300

返回参数:

参数名类型说明
statusint状态码,true表示成功
image_base64str六寸排版照的base64编码

4.人像抠图

接口名:human_matting

人像抠图接口的逻辑是接收一张 RGB 图像,输出一张标准抠图人像照和高清抠图人像照(无任何背景填充)。

请求参数:

参数名类型必填说明
input_imagefile传入的图像文件,图像文件为需为RGB三通道图像。
human_matting_modelstr人像分割模型,默认为modnet_photographic_portrait_matting。可选值为modnet_photographic_portrait_mattinghivision_modnetrmbg-1.4birefnet-v1-lite
dpiint图像分辨率,默认为300

返回参数:

参数名类型说明
statusint状态码,true表示成功
image_base64str抠图人像照的base64编码

5.图像加水印

接口名:watermark

图像加水印接口的功能是接收一个水印文本,然后在原图上添加指定的水印。用户可以指定水印的位置、透明度和大小等属性,以便将水印无缝地融合到原图中。

请求参数:

参数名类型必填说明
input_imagefileinput_image_base64二选一传入的图像文件,图像文件为需为RGB三通道图像。
input_image_base64strinput_image二选一传入的图像文件的base64编码,图像文件为需为RGB三通道图像。
textstr水印文本,默认为Hello
sizeint水印字体大小,默认为20
opacityfloat水印透明度,默认为0.5
angleint水印旋转角度,默认为30
colorstr水印颜色,默认为#000000
spaceint水印间距,默认为25
dpiint图像分辨率,默认为300

返回参数:

参数名类型说明
statusint状态码,true表示成功
image_base64str添加水印之后的图像的base64编码

6.设置图像KB大小

接口名:set_kb

设置图像KB大小接口的功能是接收一张图像和目标文件大小(以KB为单位),如果设置的KB值小于原文件,则调整压缩率;如果设置的KB值大于源文件,则通过给文件头添加信息的方式调大KB值,目标是让图像的最终大小与设置的KB值一致。

请求参数:

参数名类型必填说明
input_imagefileinput_image_base64二选一传入的图像文件,图像文件为需为RGB三通道图像。
input_image_base64strinput_image二选一传入的图像文件的base64编码,图像文件为需为RGB三通道图像。
kbint输出照片的 KB 值,默认为None,即不对图像进行KB调整。
dpiint图像分辨率,默认为300

返回参数:

参数名类型说明
statusint状态码,true表示成功
image_base64str设置KB大小之后的图像的base64编码

7.证件照裁切

接口名:idphoto_crop

证件照裁切接口的功能是接收一张 RBGA 图像(透明图),输出一张标准证件照和一张高清证件照。

请求参数:

参数名类型必填说明
input_imagefileinput_image_base64二选一传入的图像文件,图像文件为需为RGBA四通道图像。
input_image_base64strinput_image二选一传入的图像文件的base64编码,图像文件为需为RGBA四通道图像。
heightint标准证件照高度,默认为413
widthint标准证件照宽度,默认为295
face_detect_modelstr人脸检测模型,默认为mtcnn。可选值为mtcnnface_plusplusretinaface-resnet50
hdbool是否生成高清证件照,默认为true
dpiint图像分辨率,默认为300
head_measure_ratiofloat面部面积与照片面积的比例,默认为0.2
head_height_ratiofloat面部中心与照片顶部的高度比例,默认为0.45
top_distance_maxfloat头部与照片顶部距离的比例最大值,默认为0.12
top_distance_minfloat头部与照片顶部距离的比例最小值,默认为0.1

返回参数:

参数名类型说明
statusint状态码,true表示成功
image_base64str证件照裁切之后的图像的base64编码
image_base64_hdstr高清证件照裁切之后的图像的base64编码,如hd参数为false,则不返回该参数

cURL 请求示例

cURL 是一个命令行工具,用于使用各种网络协议传输数据。以下是使用 cURL 调用这些 API 的示例。

1. 生成证件照(底透明)

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"

2. 添加背景色

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

3. 生成六寸排版照

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"

4. 人像抠图

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"

5. 图片加水印

curl -X 'POST' \
  'http://127.0.0.1:8080/watermark?size=20&opacity=0.5&angle=30&color=%23000000&space=25' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'input_image=@demo/images/test0.jpg;type=image/jpeg' \
  -F 'text=Hello' \
  -F 'dpi=300'

6. 设置图像KB大小

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'

7. 证件照裁切

curl -X 'POST' \
  'http://127.0.0.1:8080/idphoto_crop?head_measure_ratio=0.2&head_height_ratio=0.45&top_distance_max=0.12&top_distance_min=0.1' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'input_image=@idphoto_matting.png;type=image/png' \
  -F 'height=413' \
  -F 'width=295' \
  -F 'face_detect_model=mtcnn' \
  -F 'hd=true' \
  -F 'dpi=300'

Python 请求示例

1.生成证件照(底透明)
import requests

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

# 设置请求参数
params = {
    "head_measure_ratio": 0.2,
    "head_height_ratio": 0.45,
    "top_distance_max": 0.12,
    "top_distance_min": 0.1,
}
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,
}

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

# response为一个json格式字典,包含status、image_base64_standard和image_base64_hd三项
print(response)
2.添加背景色
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)
3.生成六寸排版照
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)
4.人像抠图
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)
5.图片加水印
import requests

# 设置请求的 URL 和参数
url = "http://127.0.0.1:8080/watermark"
params = {
    "size": 20,
    "opacity": 0.5,
    "angle": 30,
    "color": "#000000",
    "space": 25,
}

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

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

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

6. 设置图像KB大小

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}")

7. 证件照裁切

import requests

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

# 设置请求参数
params = {
    "head_measure_ratio": 0.2,
    "head_height_ratio": 0.45,
    "top_distance_max": 0.12,
    "top_distance_min": 0.1,
}

# 设置文件和其他表单数据
input_image_path = "idphoto_matting.png"
files = {"input_image": ("idphoto_matting.png", open(input_image_path, "rb"), "image/png")}
data = {
    "height": 413,
    "width": 295,
    "face_detect_model": "mtcnn",
    "hd": "true",
    "dpi": 300,
}

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

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

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值