从零开始搭建free5GC：5G核心网实战部署完全指南
2026/1/22 5:46:06
UNet人脸融合二次开发接口文档在哪里？
1. 引言：为什么需要二次开发接口？
你是不是也遇到过这种情况：Face Fusion的WebUI用起来很方便，但一旦想把它集成到自己的项目里——比如做个小程序、做个自动化处理系统，或者和其他AI功能联动——就卡住了？界面操作再流畅，也无法直接调用，更别说批量处理或嵌入生产流程。
这时候你就需要二次开发接口（API）。它能让你绕开点击操作，通过代码直接控制“上传图片→设置参数→执行融合→获取结果”整个流程，实现自动化、批量化、服务化的人脸融合能力。
本文将基于镜像unet image Face Fusion人脸融合人脸合成 二次开发构建by科哥，带你找到并掌握其隐藏的API入口，手把手教你如何用Python发起请求，完成一次完整的人脸融合调用。
2. 镜像运行与服务启动
2.1 启动应用
该镜像基于Gradio搭建WebUI，默认监听7860端口。要启用API功能，必须先确保服务正常运行。
/bin/bash /root/run.sh这条命令会启动Gradio服务，访问地址为：
http://localhost:7860启动成功后，你会看到类似以下的日志输出：
Running on local URL: http://0.0.0.0:7860 Running on public URL: http://xxx.xxx.xxx.xxx:7860注意：Gradio默认开启API支持，所有组件都会自动生成对应的
/api/接口路径，无需额外配置。
3. API接口位置与结构解析
3.1 如何找到API文档？
Gradio服务启动后，可以直接在浏览器中访问：
http://localhost:7860/docs这是自动生成的Swagger UI 文档页面，展示了所有可用的API端点。你可以在这里查看请求格式、参数类型、示例数据，并进行在线测试。
如果你只想看原始接口列表，也可以访问：
http://localhost:7860/api返回的是JSON格式的API描述信息。
3.2 核心API端点分析
从/api返回的数据可以看出，主要接口位于：
POST /api/predict/这个接口用于调用Gradio Blocks中的任意函数节点。由于本项目使用了模块化设计，每个功能按钮都对应一个独立的处理函数。
主要可调用函数名（Endpoint）
| 函数名 | 功能说明 |
|---|---|
predict | 执行人脸融合主逻辑 |
clear | 清空输入与输出 |
我们重点关注predict接口。
4. 调用API：从零开始写一个Python脚本
下面是一个完整的Python示例，展示如何通过HTTP请求调用人脸融合API。
4.1 安装依赖
pip install requests pillow4.2 编写调用脚本
import requests import base64 from PIL import Image from io import BytesIO # 设置服务地址 url = "http://localhost:7860/api/predict/" # 读取图像并转为Base64编码 def image_to_base64(image_path): with open(image_path, "rb") as f: return base64.b64encode(f.read()).decode('utf-8') # 构造请求数据 payload = { "data": [ { "name": "source.jpg", "data": f"data:image/jpeg;base64,{image_to_base64('source.jpg')}" }, { "name": "target.jpg", "data": f"data:image/jpeg;base64,{image_to_base64('target.jpg')}" }, 0.6, # 融合比例 0.5, # 皮肤平滑 0.0, # 亮度调整 0.0, # 对比度调整 0.0, # 饱和度调整 0.5, # 人脸检测阈值 "normal", # 融合模式 "1024x1024" # 输出分辨率 ] } # 发起请求 response = requests.post(url, json=payload) if response.status_code == 200: result = response.json() # 解码返回的Base64图像 output_image_data = result["data"][0] header, encoded = output_image_data.split(",", 1) image_bytes = base64.b64decode(encoded) # 保存结果 with open("fused_result.jpg", "wb") as f: f.write(image_bytes) print(" 融合成功！结果已保存为 fused_result.jpg") else: print(f"❌ 请求失败，状态码：{response.status_code}") print(response.text)4.3 参数说明
data数组顺序必须严格匹配前端组件顺序：
| 位置 | 参数 | 类型 | 示例值 | 说明 |
|---|---|---|---|---|
| 0 | 源图像 | dict | {name, data} | 提供人脸特征的图片 |
| 1 | 目标图像 | dict | {name, data} | 被融合的目标背景图 |
| 2 | 融合比例 | float | 0.6 | 0.0~1.0 |
| 3 | 皮肤平滑 | float | 0.5 | 0.0~1.0 |
| 4 | 亮度调整 | float | 0.0 | -0.5~0.5 |
| 5 | 对比度调整 | float | 0.0 | -0.5~0.5 |
| 6 | 饱和度调整 | float | 0.0 | -0.5~0.5 |
| 7 | 人脸检测阈值 | float | 0.5 | 0.1~0.9 |
| 8 | 融合模式 | str | "normal" | normal,blend,overlay |
| 9 | 输出分辨率 | str | "1024x1024" | 原始,512x512,1024x1024,2048x2048 |
注意：字符串类参数（如模式、分辨率）必须完全匹配选项值，区分大小写。
5. 高级技巧：绕过WebUI直接调用底层模型
虽然API/predict已经足够强大，但在某些高性能场景下（如批量处理、低延迟服务），你可能希望跳过Gradio中间层，直接调用核心模型。
5.1 模型路径定位
进入容器内部，查看项目目录：
cd /root/cv_unet-image-face-fusion_damo/ ls关键文件包括：
app.py：Gradio主程序inference.py：推理逻辑封装models/：存放预训练权重utils/：工具函数（人脸检测、对齐、融合等）
5.2 直接导入模块进行调用
from inference import FaceFusionPipeline # 初始化管道 pipeline = FaceFusionPipeline( model_path="models/damo/cv_unet-image-face-fusion_damo", device="cuda" # 或 "cpu" ) # 加载图像 source_img = Image.open("source.jpg") target_img = Image.open("target.jpg") # 执行融合 result = pipeline( source_img=source_img, target_img=target_img, ratio=0.6, smooth=0.5, brightness=0.0, contrast=0.0, saturation=0.0, resolution=(1024, 1024) ) # 保存结果 result.save("direct_fused.jpg")这种方式性能更高，适合部署为微服务或集成进Docker流水线。
6. 常见问题与解决方案
6.1 API返回422错误？
通常是参数格式不正确。检查：
- 图像是否以
data:image/xxx;base64,xxx格式传递 - 字符串参数是否拼写错误
- 数值是否超出范围
建议先在/docs页面使用Swagger UI测试通后再写代码。
6.2 返回图像模糊？
请确认：
- 输入图像清晰度足够
- 输出分辨率设置为
1024x1024或更高 - 融合比例不宜过低（建议 ≥0.5）
6.3 多人脸场景如何处理？
当前版本默认只处理检测到的第一张人脸。若需支持多脸融合，需修改inference.py中的人脸检测逻辑，遍历所有检测框并逐个融合。
可扩展方向：
- 添加“自动识别所有人脸”开关
- 支持指定某一张人脸进行融合
- 实现人脸选择交互式API
7. 自定义开发建议
7.1 封装为RESTful服务
你可以用Flask/FastAPI包装Gradio后端，提供更友好的REST接口：
from fastapi import FastAPI, File, UploadFile from fastapi.responses import FileResponse app = FastAPI() @app.post("/fuse/") async def fuse_faces( source: UploadFile = File(...), target: UploadFile = File(...), ratio: float = 0.6 ): # 转换为Base64调用Gradio API... # 返回融合结果 return FileResponse("output.jpg", media_type="image/jpeg")这样就能对外提供标准HTTP接口，便于移动端、小程序调用。
7.2 添加水印与版权保护
在融合完成后，可在后处理阶段添加透明水印：
from PIL import ImageDraw, ImageFont def add_watermark(img: Image.Image, text="Generated by UNet-FaceFusion"): draw = ImageDraw.Draw(img) try: font = ImageFont.truetype("arial.ttf", 20) except: font = ImageFont.load_default() draw.text((10, 10), text, fill=(255, 255, 255, 128), font=font) return img既满足开源协议要求，又防止滥用。
8. 总结
通过本文，你应该已经掌握了以下关键能力：
- 找到了UNet人脸融合的API入口：
/api/predict/ - 学会了如何构造正确的HTTP请求体，包含图像Base64和参数
- 实现了Python脚本自动化调用
- 了解了如何绕过WebUI直接调用底层模型
- 掌握了常见问题排查方法
更重要的是，你现在有能力将这个人脸融合能力真正落地到实际项目中——无论是做智能证件照生成、虚拟形象定制，还是短视频特效自动化，都可以基于这套接口快速搭建原型。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。