sdwebuiapi：为 Stable Diffusion 打造的 Python API 客户端

图1：sdwebuiapi 通过 txt2img 生成可爱松鼠图片的示例效果。

背景：为什么需要 sdwebuiapi？

想象一下，你是一位 AI 绘画爱好者，每天要在 Stable Diffusion WebUI 中反复调整提示词、切换采样器、尝试不同的降噪强度来生成理想中的图片。手动在 WebUI 界面操作效率低下，尤其是在做批量生成或需要程序化控制生成流程时，更是束手无策。 又或者，你是开发者，想要将 AI 绘画能力集成到自己的应用或工作流中——比如自动根据用户输入生成配图、自动批量处理图片变体、通过脚本进行大规模艺术创作实验——这些场景都需要程序化的 API 调用能力，而不是图形界面操作。 AUTOMATIC1111 的 Stable Diffusion WebUI 本身就内置了完整的 REST API 端点（通过 --api 参数开启），但直接调用这些 HTTP API 需要手动处理 Base64 编码、参数构造、图像与二进制数据的转换等繁琐细节。sdwebuiapi（webuiapi）正是为了解决这一痛点而生的 Python 封装库。 该项目由 ChunKoo Park（GitHub @mix1009）开发和维护，代码以 MIT 许可证开源，目前在 GitHub 上拥有 1424 颗星、收录了 4 个官方话题标签（api、automatic1111、python、stable-diffusion-webui），主要语言为 Jupyter Notebook。

核心功能：从文本到图片的完整管线

webuiapi 提供了对 AUTOMATIC1111 WebUI 所有核心生成功能的 Pythonic 封装，使用者无需关心底层 HTTP 通信细节，用几行 Python 代码即可完成复杂的 AI 生图任务。

文本生成图片（txt2img）

这是最常用的功能。通过一行代码即可调用 WebUI 的 txt2img 端点，传入提示词、负向提示词、采样器、步数、CFG 强度、种子等参数：

import webuiapi
api = webuiapi.WebUIApi()
result = api.txt2img(
    prompt="cute squirrel",
    negative_prompt="ugly, out of frame",
    seed=1003,
    styles=["anime"],
    cfg_scale=7,
    sampler="Euler a",
    steps=20
)
result.image  # PIL Image 对象

返回的 WebUIApiResult 包含三个核心属性：images（生成的图片列表，PIL Image 对象）、parameters（本次调用的参数记录）和 info（服务端返回的文本信息）。直接使用 result.image 即可获得第一张生成的图片。 图2：img2img 在已有图片基础上进行风格转换的效果——将 txt2img 生成的内容以新提示词进行二次创作。

图片生成图片（img2img）

img2img 允许在已有图片的基础上进行二次创作，传入一张图片作为输入，通过调整 denoising_strength（降噪强度）控制保留原图的程度（值越小越接近原图，越大越自由发挥）。这对局部重绘、风格迁移、分辨率放大等场景非常有用。

局部重绘（Inpainting）

结合遮罩（mask）可以对图片的特定区域进行精准重绘。创建一个黑白遮罩图片，白色区域代表需要重新生成的部分，传入 img2img 调用即可完成局部修改。

高清放大（Hi-Res / Extra）

代码库中内置了完整的 Upscaler 枚举（包括 ESRGAN、LDSR、BSRGAN、SwinIR 等主流放大算法）和 HiResUpscaler 枚举，支持在 txt2img 中启用高清修复（enable_hr=True），设置上采样缩放因子、目标分辨率和二次降噪强度，实现图片的智能放大与细节增强。此外还支持 extra-single-image（单图超分）和 extra-batch-images（批量超分）端点。

ControlNet 集成

ControlNetUnit 类封装了 ControlNet 的所有控制参数，包括控制模块（module）、模型选择、权重、缩放模式、低显存模式、处理器分辨率、引导起止范围、像素级精确模式等。同时支持 SDXL ControlNet 和高分辨率下的 ControlNet 独立选项（hr_option）。这使得 SD WebUI 最强大的可控生成能力也能通过 Python 脚本程序化调用。

ADetailer 人脸/人手修复

ADetailer 类封装了 ADetailer 扩展的参数，包括模型选择（ad_model）、置信度阈值、正负提示词叠加、检测间隔等，专门用于修复 AI 生成图片中常见的人脸/人手崩坏问题，提升最终输出质量。

技术架构：简洁清晰的实现设计

整个项目只有一个核心 Python 文件 webuiapi.py（约 77KB），加上一个 init.py 暴露公共接口，结构极为精简。 依赖极简：仅依赖 requests 和 Pillow 两个包，分别处理 HTTP 通信和图像处理。python_requires >= 3.7, < 4，兼容 Python 3.7 到 3.11+。 数据类设计：大量使用 @dataclass 定义结构化结果类型（如 WebUIApiResult），以及 Enum 定义枚举常量（如 Upscaler、HiResUpscaler），代码意图清晰。ControlNetUnit 和 ADetailer 也封装为独立类，各自管理自己的参数状态。 类型注解完整：大量使用 typing 模块的类型注解（List、Dict、Any、Optional、Union、Literal），便于 IDE 自动补全和静态分析工具检查。 图像处理：所有图像传输使用 Base64 编码，接收端自动转换为 PIL Image 对象，对外暴露的是用户友好的 PIL Image 接口，屏蔽了底层编码细节。

部署与使用门槛

使用门槛极低，但需要前置依赖：安装只需一行 pip install webuiapi，但使用前必须先有一台运行着 AUTOMATIC1111 Stable Diffusion WebUI 的机器，并额外开启 --api 参数。如果 WebUI 开启了 HTTP 认证（--api-auth），也只需调用 api.set_auth() 配置用户名密码。 webuiapi 本身是纯客户端——它不包含任何 AI 模型推理代码，也不占用 GPU 资源，只是远程调用已有的 SD WebUI 服务。这意味着可以将 WebUI 部署在高性能 GPU 服务器上，然后从任意客户端机器通过 webuiapi 发送生成请求，实现计算资源的集中管理。 不支持一键部署：项目没有提供 Dockerfile 或 docker-compose，代码库本质上是 SDK 而非独立服务，因此不支持通过容器直接部署运行。

项目局限与注意事项

1. 无独立运行能力：必须配合 AUTOMATIC1111 WebUI 使用，学习曲线实际上是 WebUI + API 两部分之和。
2. HTTP 认证安全性有限：--api-auth 使用的是 HTTP Basic Auth，密码以明文传输，非加密通道下存在被截获风险。生产环境建议配合 HTTPS 使用。
3. 同步阻塞式 API：当前版本的 API 调用是同步阻塞的，没有内置异步（async/await）支持，在高频调用场景下可能成为瓶颈。
4. 仅支持特定版本的 WebUI API：随着 WebUI 版本更新，API 参数可能有变化，需要确保 WebUI 版本与 webuiapi 版本兼容。

行业意义

sdwebuiapi 填补了 Stable Diffusion 生态中程序化调用这一关键空白。在 AIGC 应用快速发展的当下，从研究实验到产品落地，需要的都是可编程的 API 接口而非图形界面。该项目虽然代码量不大，但恰好解决了 AI 绘画工作流自动化的最后一公里问题，是 Stable Diffusion 从玩具走向工具的重要桥梁。 1424 颗星的数量说明了社区的真实需求——对于需要批量生图、集成 AI 能力的开发者来说，这是一个高性价比的选择。