unet人像卡通化API封装：Python调用接口实战教程-深圳市維司達科技有限公司

UNet人像卡通化API封装：Python调用接口实战教程

1. 为什么需要封装成API？——从WebUI到程序集成的跨越

你可能已经试过科哥构建的UNet人像卡通化Web工具：上传照片、点几下参数、5秒后就看到一张生动的卡通头像。界面友好，操作简单，但如果你正开发一个批量处理用户头像的社交App，或者想把卡通化能力嵌入到企业内部系统里，每次手动点选就完全不现实了。

这时候，WebUI就变成了“看得见摸不着”的孤岛——它很好用，但无法被你的Python脚本调用，不能和数据库联动，也不能写进自动化流水线。

本文要带你做的，就是把那个漂亮的网页背后的能力，变成一行代码就能调用的API服务。不是教你重写模型，也不是从零搭服务，而是基于科哥已有的DCT-Net WebUI，用最轻量、最稳妥的方式，把它“打开一扇门”，让你的Python程序能直接送图、取图、批量跑任务。

整个过程不需要改一行模型代码，不碰CUDA配置，不部署新容器，只靠几个HTTP请求+少量Python胶水代码，就能让卡通化能力真正“活”进你的项目里。

2. 理解底层机制：WebUI本身就是个API服务器

很多人误以为Gradio/WebUI只是“图形界面”，其实它本质是一个自带HTTP服务的API网关。当你访问http://localhost:7860，浏览器看到的是美化后的页面，但页面背后，所有按钮点击、参数提交、结果返回，全都是通过标准HTTP请求完成的。

科哥的这个工具使用Gradio启动，而Gradio在启动时会自动暴露一组RESTful接口（默认路径为/run/predict），它接收JSON格式的输入，返回JSON格式的结果，中间自动完成：图片base64编码 → 模型推理 → 结果图片base64解码 → 组装响应。

换句话说：你已经在用API了，只是之前用的是浏览器这个“客户端”。现在，我们换一个客户端——你的Python脚本。

2.1 接口通信流程还原

我们来拆解一次单图转换背后的完整链路：

Python脚本 ↓ 发起POST请求（含图片+参数） http://localhost:7860/run/predict ↓ Gradio接收并解析 模型推理层（DCT-Net） ↓ 处理完成，生成卡通图 Gradio将结果打包为JSON（含base64图片字符串） ↓ 返回HTTP响应 Python脚本接收并解码base64 → 保存为本地文件

整个过程没有魔法，只有清晰的输入输出契约。接下来，我们就按这个契约，手写一个真正可用的调用器。

3. 实战：三步封装Python调用函数

我们不依赖任何SDK或第三方包，只用Python标准库requests和内置模块，写出干净、健壮、可复用的调用函数。

3.1 第一步：准备图片并编码为base64

Gradio接口要求图片以base64字符串形式传入。注意：不是文件路径，不是二进制流，而是标准base64编码后的字符串，且需带data URL前缀。

import base64 import requests import json from pathlib import Path def image_to_base64(image_path: str) -> str: """将本地图片转为Gradio兼容的base64字符串""" with open(image_path, "rb") as f: img_bytes = f.read() img_b64 = base64.b64encode(img_bytes).decode("utf-8") # Gradio要求格式：data:image/png;base64,xxxx suffix = Path(image_path).suffix.lower().replace(".", "") if suffix == "jpg": suffix = "jpeg" return f"data:image/{suffix};base64,{img_b64}"

小贴士：这个函数自动识别.jpg/.png/.webp，并拼出正确MIME类型，避免因格式不匹配导致接口报错。

3.2 第二步：构造标准请求体与发送调用

Gradio的/run/predict接口接收一个固定结构的JSON，核心是data字段，它是一个列表，按WebUI组件顺序排列参数。根据科哥UI的单图页结构，顺序为：

图片（base64字符串）
风格选择（字符串，当前仅"cartoon"）
输出分辨率（整数，如1024）
风格强度（浮点数，如0.8）
输出格式（字符串，如"png"）

def cartoonize_single( image_path: str, host: str = "http://localhost:7860", style: str = "cartoon", resolution: int = 1024, strength: float = 0.8, output_format: str = "png" ) -> bytes: """ 调用UNet人像卡通化API处理单张图片 Args: image_path: 本地图片路径 host: WebUI服务地址（默认本机） style: 卡通风格（目前仅支持"cartoon"） resolution: 输出最长边像素（512/1024/2048） strength: 风格强度（0.1~1.0） output_format: 输出格式（"png"/"jpg"/"webp"） Returns: 卡通化后的图片二进制数据（可直接写入文件） """ # 1. 编码图片 img_b64 = image_to_base64(image_path) # 2. 构造Gradio标准请求体 payload = { "data": [ img_b64, # 图片 style, # 风格 resolution, # 分辨率 strength, # 强度 output_format # 格式 ] } # 3. 发送请求（超时设为30秒，覆盖大图处理时间） try: resp = requests.post( f"{host}/run/predict", json=payload, timeout=30 ) resp.raise_for_status() except requests.exceptions.RequestException as e: raise RuntimeError(f"API调用失败: {e}") # 4. 解析响应：Gradio返回JSON，结果在data[0]中（base64字符串） result = resp.json() if "data" not in result or len(result["data"]) == 0: raise RuntimeError("API返回无效结果，缺少data字段") img_b64_out = result["data"][0] if not img_b64_out.startswith("data:image/"): raise RuntimeError("API返回非图片base64数据") # 5. 提取纯base64部分并解码 _, b64_data = img_b64_out.split(",", 1) return base64.b64decode(b64_data)

关键设计点：

所有参数都设了合理默认值，调用时只需填image_path即可快速上手
显式错误分类：网络异常、HTTP错误、响应格式错误，便于调试
自动剥离data:image/xxx;base64,前缀，专注解码核心数据

3.3 第三步：保存结果并验证效果

调用函数返回的是原始字节流，我们封装一个保存函数，自动补全后缀，并做基础校验：

def save_cartoon_result( image_bytes: bytes, output_path: str, auto_suffix: bool = True ) -> None: """安全保存卡通化结果""" path = Path(output_path) if auto_suffix and not path.suffix: # 根据字节头推测格式（PNG/JPG/WEBP） if image_bytes.startswith(b"\x89PNG\r\n\x1a\n"): path = path.with_suffix(".png") elif image_bytes.startswith(b"\xff\xd8\xff"): path = path.with_suffix(".jpg") elif image_bytes.startswith(b"RIFF") and b"WEBP" in image_bytes[:12]: path = path.with_suffix(".webp") else: raise ValueError("无法识别图片格式，请指定后缀") path.parent.mkdir(parents=True, exist_ok=True) with open(path, "wb") as f: f.write(image_bytes) print(f" 卡通图已保存至：{path.resolve()}") # 快速使用示例 if __name__ == "__main__": # 假设你有一张叫 "me.jpg" 的照片 cartoon_bytes = cartoonize_single("me.jpg") save_cartoon_result(cartoon_bytes, "output/cartoon_me.png")

运行后，你会在output/目录下看到一张全新的卡通头像——和你在网页上点出来的效果完全一致，只是现在它诞生于你的Python脚本之中。

4. 进阶技巧：批量处理与错误重试

单张调用只是起点。真实业务中，你往往需要处理上百张用户头像。下面两个技巧，能让你的调用更工程化。

4.1 批量处理：用循环 + 并发提升效率

虽然Gradio本身不支持原生批量接口，但我们可以通过并发请求模拟。使用concurrent.futures，控制并发数避免压垮服务：

from concurrent.futures import ThreadPoolExecutor, as_completed import time def batch_cartoonize( image_paths: list, output_dir: str = "outputs", max_workers: int = 3, # 建议3-5，避免显存溢出 **kwargs ) -> dict: """ 批量卡通化处理（线程池并发） Returns: {input_path: output_path} 映射字典 """ results = {} output_path = Path(output_dir) output_path.mkdir(exist_ok=True) def process_one(path): try: start = time.time() img_bytes = cartoonize_single(path, **kwargs) # 生成输出文件名：原名 + _cartoon stem = Path(path).stem out_path = output_path / f"{stem}_cartoon.png" save_cartoon_result(img_bytes, out_path, auto_suffix=True) cost = time.time() - start return path, str(out_path), f" 成功（{cost:.1f}s）" except Exception as e: return path, None, f"❌ 失败：{e}" with ThreadPoolExecutor(max_workers=max_workers) as executor: # 提交所有任务 future_to_path = { executor.submit(process_one, p): p for p in image_paths } # 收集结果 for future in as_completed(future_to_path): input_path, out_path, status = future.result() results[input_path] = {"output": out_path, "status": status} print(f"[{input_path}] {status}") return results # 使用示例 # batch_cartoonize(["a.jpg", "b.jpg", "c.jpg"], output_dir="batch_out", strength=0.75)

效果：3张图总耗时约12秒（串行需24秒），且失败单张不影响其他任务。

4.2 智能重试：应对临时性服务抖动

本地服务偶尔因模型加载、显存不足出现503错误。加一层指数退避重试，让脚本更鲁棒：

import random def cartoonize_single_with_retry( image_path: str, max_retries: int = 3, base_delay: float = 1.0, **kwargs ) -> bytes: """带指数退避重试的卡通化调用""" last_exc = None for i in range(max_retries + 1): try: return cartoonize_single(image_path, **kwargs) except RuntimeError as e: last_exc = e if "503" in str(e) or "timeout" in str(e).lower(): if i < max_retries: delay = base_delay * (2 ** i) + random.uniform(0, 1) print(f" 服务暂不可用，{delay:.1f}s后重试 ({i+1}/{max_retries})...") time.sleep(delay) else: raise e else: raise e raise last_exc

5. 生产就绪建议：不只是能跑，还要稳

当你把这段代码集成进正式项目，还需关注这几个关键点：

5.1 服务健康检查

在调用前，先确认Gradio服务是否存活，避免请求直接超时：

def check_gradio_health(host: str = "http://localhost:7860") -> bool: """检查Gradio服务是否就绪""" try: resp = requests.get(f"{host}/startup-events", timeout=5) return resp.status_code == 200 except: return False # 使用前加检查 if not check_gradio_health(): raise RuntimeError("Gradio服务未启动，请先运行 /root/run.sh")

5.2 输出目录权限与清理

确保outputs/目录可写，并定期清理旧文件（防止磁盘占满）：

import shutil from datetime import datetime, timedelta def cleanup_old_outputs(days: int = 7): """清理7天前的输出文件""" outputs = Path("outputs") if not outputs.exists(): return cutoff = datetime.now() - timedelta(days=days) for f in outputs.rglob("*"): if f.is_file() and f.stat().st_mtime < cutoff.timestamp(): f.unlink() print(f"🧹 已清理：{f}")

5.3 日志与监控（轻量级）

记录关键指标，便于问题追溯：

import logging logging.basicConfig( level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s", handlers=[logging.FileHandler("cartoon_api.log"), logging.StreamHandler()] ) # 在cartoonize_single函数内添加 logging.info(f"开始处理 {image_path} | 分辨率:{resolution} | 强度:{strength}") # ...处理完成后... logging.info(f"完成 {image_path} → {out_path} | 耗时:{cost:.1f}s")