hair/local_test

发型补全服务 API 文档

服务概述

本服务提供基于 ComfyUI 的发型补全（局部重绘）能力。通过传入人物图片和遮罩图片，调用 ComfyUI 工作流（0716add-hair.json）生成补全后的图片。

技术栈

• 框架: Flask
• 依赖: requests, Pillow, numpy
• 后端: ComfyUI (http://127.0.0.1:8188)

服务地址

• HTTP: http://127.0.0.1:8899
• 前端页面: http://127.0.0.1:8899/
• API接口: http://127.0.0.1:8899/api/generate

启动方式

使用脚本（推荐）

# 启动服务
cd /home/ubuntu/hair/local_test
./start.sh

# 停止服务
./stop.sh

直接运行

cd /home/ubuntu/hair/local_test
/home/ubuntu/ComfyUI/venv/bin/python app.py

API 接口

POST /api/generate

调用 ComfyUI 工作流，传入图片和遮罩，返回生成结果。

请求参数

参数名	类型	必填	说明
image	File	是	人物图片（支持 jpg, png 等常见格式）
mask	File	是	遮罩图片（支持 jpg, png，遮罩区域可用红色/白色/alpha 通道标识）
prompt	String	否	提示词，默认值："填充遮罩区域的头发，皮肤加一点磨皮"

遮罩图片格式说明

服务支持多种遮罩格式，自动提取遮罩区域：

格式类型	示例	遮罩区域标识
红色遮罩	红色画笔绘制	R=255 的像素
白色遮罩	白色画笔绘制	R=G=B=255 的像素
Alpha 遮罩	透明背景	A=255 的像素

服务会取所有通道的最大值作为遮罩强度，因此以上格式均可混用。

注意: 遮罩区域表示需要重绘的部分，非遮罩区域保持原图不变。

请求示例（curl）

curl -X POST http://127.0.0.1:8899/api/generate \
  -F "image=@/path/to/person.jpg" \
  -F "mask=@/path/to/mask.png" \
  -F "prompt=填充遮罩区域的头发，皮肤加一点磨皮" \
  --output result.png

请求示例（Python）

import requests

url = "http://127.0.0.1:8899/api/generate"
files = {
    "image": open("person.jpg", "rb"),
    "mask": open("mask.png", "rb"),
}
data = {
    "prompt": "填充遮罩区域的头发，皮肤加一点磨皮"
}

resp = requests.post(url, files=files, data=data, timeout=600)
if resp.status_code == 200:
    with open("result.png", "wb") as f:
        f.write(resp.content)
else:
    print(f"Error: {resp.json()}")

响应

成功 (HTTP 200):

返回 PNG 图片二进制数据，Content-Type: image/png。

失败 (HTTP 4xx/5xx):

返回 JSON 格式错误信息：

{
    "error": "错误描述"
}

错误码

状态码	说明
500	内部错误（文件处理失败、ComfyUI 返回错误等）
503	无法连接到 ComfyUI（服务未启动或端口错误）
500	超时（工作流执行超过 5 分钟）

工作流说明

服务使用的工作流 0716add-hair.json 包含以下处理步骤：

1. 加载模型: Flux 2 Klein 9B (FP8) + Qwen 3.8B CLIP
2. 图片上传: 将原图与遮罩合成为 RGBA 格式上传至 ComfyUI
3. 遮罩处理: 填充孔洞 → 转换为图像 → 缩放 → 转换回遮罩
4. 图像缩放: 按比例缩放至合适尺寸（最大边长 1024，8 的倍数）
5. VAE 编码: 将图像编码为 latent
6. 采样生成: 使用 Flux 模型 + ReferenceLatent 进行局部重绘
7. VAE 解码: 将 latent 解码为图像
8. 颜色匹配: 使用 ColorMatch 保持颜色一致
9. 保存结果: 返回生成的图片

前置依赖

启动服务前需确保：

1. ComfyUI 已启动: http://127.0.0.1:8188 可访问
2. 模型文件存在:
   • models/unet/flux2.0/flux-2-klein-9b-fp8.safetensors
   • models/vae/flux2-vae.safetensors
   • models/clip/qwen_3_8b_fp8mixed.safetensors
3. 虚拟环境已激活: 使用 /home/ubuntu/ComfyUI/venv/bin/python

文件结构

/home/ubuntu/hair/local_test/
├── app.py          # Flask 后端服务
├── index.html      # 前端测试页面
├── test_api.py     # API 测试脚本
├── README.md       # 本文档
├── output/         # 测试结果输出目录
├── 用来重绘.jpg     # 测试人物图片
└── 用来重绘.png     # 测试遮罩图片

使用流程

1. 启动 ComfyUI（python main.py --listen）
2. 启动本服务（python app.py）
3. 调用 API 或访问前端页面上传图片和遮罩
4. 等待生成完成（通常 30-60 秒）
5. 获取返回的 PNG 图片

注意事项

• 请求超时时间为 5 分钟，生成复杂图片可能需要较长时间
• 遮罩图片尺寸需与人物图片一致，服务会自动缩放对齐
• 建议使用红色或白色绘制遮罩，确保遮罩强度足够
• 服务会自动对遮罩边缘进行高斯模糊（radius=4），避免硬边