sdwebuiapi
AUTOMATIC1111 Stable Diffusion WebUI 的 Python API 客户端，几行代码完成 txt2img/img2img/ControlNet 等全部功能
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
AUTOMATIC1111 Stable Diffusion WebUI 的 Python API 客户端，几行代码完成 txt2img/img2img/ControlNet 等全部功能
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
图1：sdwebuiapi 通过 txt2img 生成可爱松鼠图片的示例效果。
想象一下，你是一位 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 生图任务。
这是最常用的功能。通过一行代码即可调用 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 允许在已有图片的基础上进行二次创作，传入一张图片作为输入，通过调整 denoising_strength（降噪强度）控制保留原图的程度（值越小越接近原图，越大越自由发挥）。这对局部重绘、风格迁移、分辨率放大等场景非常有用。
结合遮罩（mask）可以对图片的特定区域进行精准重绘。创建一个黑白遮罩图片，白色区域代表需要重新生成的部分，传入 img2img 调用即可完成局部修改。
代码库中内置了完整的 Upscaler 枚举（包括 ESRGAN、LDSR、BSRGAN、SwinIR 等主流放大算法）和 HiResUpscaler 枚举，支持在 txt2img 中启用高清修复（enable_hr=True），设置上采样缩放因子、目标分辨率和二次降噪强度，实现图片的智能放大与细节增强。此外还支持 extra-single-image（单图超分）和 extra-batch-images（批量超分）端点。
ControlNetUnit 类封装了 ControlNet 的所有控制参数，包括控制模块（module）、模型选择、权重、缩放模式、低显存模式、处理器分辨率、引导起止范围、像素级精确模式等。同时支持 SDXL ControlNet 和高分辨率下的 ControlNet 独立选项（hr_option）。这使得 SD WebUI 最强大的可控生成能力也能通过 Python 脚本程序化调用。
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 而非独立服务，因此不支持通过容器直接部署运行。
sdwebuiapi 填补了 Stable Diffusion 生态中程序化调用这一关键空白。在 AIGC 应用快速发展的当下，从研究实验到产品落地，需要的都是可编程的 API 接口而非图形界面。该项目虽然代码量不大，但恰好解决了 AI 绘画工作流自动化的最后一公里问题，是 Stable Diffusion 从玩具走向工具的重要桥梁。 1424 颗星的数量说明了社区的真实需求——对于需要批量生图、集成 AI 能力的开发者来说，这是一个高性价比的选择。