5分钟上手！sd-webui-controlnet API实战指南：从安装到AI应用落地

【免费下载链接】sd-webui-controlnet WebUI extension for ControlNet 项目地址: https://gitcode.com/gh_mirrors/sd/sd-webui-controlnet

你还在为AI绘图缺乏精准控制而烦恼？想让生成的图像严格遵循参考线稿、姿势或深度信息？本文将带你零基础掌握sd-webui-controlnet API，通过5个实用场景案例，让你在1小时内具备AI图像精准控制能力。读完本文你将获得：

• 3分钟快速搭建API服务
• 5类核心接口全解析
• 3个实战案例源代码
• 常见错误解决方案

项目简介与核心价值

sd-webui-controlnet是Stable Diffusion WebUI的扩展插件（Extension），通过API（应用程序接口）允许开发者将图像控制能力集成到自定义应用中。与手动操作Web界面相比，API集成能实现：

• 批量处理图像生成任务
• 构建自动化工作流
• 开发定制化前端界面
• 与其他AI服务联动

项目核心功能模块位于scripts/controlnet.py，API实现代码详见scripts/api.py，官方示例代码可参考example/目录。

图1：ControlNet基本工作流程 - 输入图像（左）→ 提取特征（中）→ 生成结果（右）

环境准备与快速启动

安装部署步骤

1. 克隆仓库

git clone https://gitcode.com/gh_mirrors/sd/sd-webui-controlnet
cd sd-webui-controlnet

2. 安装依赖

pip install -r requirements.txt

3. 启动WebUI与API

# 确保已安装Stable Diffusion WebUI，然后启动时添加--api参数
cd .. && ./webui.sh --api

模型文件需放置在models/目录，具体要求见models/put_controlnet_models_here.txt

验证API服务

服务启动后，通过以下命令验证API可用性：

curl http://localhost:7860/controlnet/version

成功响应示例：

{"version": "1.1.0"}

核心API接口详解

1. 版本与配置接口

接口地址	方法	功能描述
/controlnet/version	GET	获取API版本信息
/controlnet/settings	GET	获取当前配置信息
/controlnet/model_list	GET	获取可用模型列表
/controlnet/module_list	GET	获取可用预处理器列表

模型列表请求示例：

import requests
response = requests.get("http://localhost:7860/controlnet/model_list")
print(response.json())

2. 图像检测接口（核心功能）

detect接口是最常用的API之一，用于从输入图像中提取控制特征（如边缘、姿势、深度等）。

请求参数：

• controlnet_module: 预处理器名称（如"canny"、"openpose"）
• controlnet_input_images: 输入图像的base64编码列表
• controlnet_processor_res: 处理分辨率（默认-1）

使用示例：

import requests
import base64

def encode_image(image_path):
    with open(image_path, "rb") as f:
        return base64.b64encode(f.read()).decode('utf-8')

payload = {
    "controlnet_module": "canny",
    "controlnet_input_images": [encode_image("samples/mahiro_input.png")],
    "controlnet_processor_res": 512
}

response = requests.post(
    "http://localhost:7860/controlnet/detect",
    json=payload
)

# 保存检测结果图像
with open("canny_result.png", "wb") as f:
    f.write(base64.b64decode(response.json()["images"][0]))

图2：Canny边缘检测示例 - 输入图像经API处理后生成的边缘图

3. 姿态渲染接口

render_openpose_json接口允许将JSON格式的姿态数据渲染为可视化图像，特别适用于动画制作和人物姿势控制场景。

请求示例：

import requests

pose_data = {
    "people": [{
        "pose_keypoints_2d": [
            320.5, 180.2, 0.8,  #  nose
            340.1, 160.3, 0.9,  #  neck
            # ... 其他关键点
        ]
    }],
    "canvas_width": 640,
    "canvas_height": 480
}

response = requests.post(
    "http://localhost:7860/controlnet/render_openpose_json",
    json=[pose_data]
)

# 保存渲染结果
with open("pose_render.png", "wb") as f:
    f.write(base64.b64decode(response.json()["images"][0]))

图3：OpenPose姿态检测效果 - 从输入图像提取的人体关键点及骨骼结构

实战案例：构建你的AI应用

案例1：文本生成图像（txt2img）

使用example/txt2img_example/api_txt2img.py示例，通过API实现文本到图像的生成，并使用Canny边缘控制：

from example.txt2img_example.api_txt2img import ControlnetRequest

# 初始化请求
control_net = ControlnetRequest(
    prompt="a beautiful mountain landscape, 4k, detailed",
    path="samples/stock_mountain.png"
)

# 构建请求体并发送
control_net.build_body()
output = control_net.send_request()

# 保存结果
with open("generated_mountain.png", "wb") as f:
    f.write(base64.b64decode(output["images"][0]))

图4：文本生成图像案例 - 左侧为控制图像，右侧为生成结果

案例2：图像修复（Inpaint）

图像修复功能可用于去除图像中的不需要元素或修复破损区域，相关示例代码位于example/inpaint_example/api_inpaint.py。

核心参数配置：

{
    "module": "inpaint",
    "model": "control_v11p_sd15_inpaint",
    "image": base64_image,
    "mask": base64_mask,
    "resize_mode": "Resize and Fill"
}

图5：图像修复案例 - 左侧为原始图像，右侧为修复结果

案例3：高级权重控制

example/advanced_weighting_example/api_advanced_weighting.py展示了如何通过权重控制实现多区域差异化生成。关键代码片段：

"args": [
    {
        "enabled": True,
        "module": "canny",
        "model": "canny",
        "weight": 1.0,  # 整体权重
        "image": image1,
        # ...
    },
    {
        "enabled": True,
        "module": "depth",
        "model": "depth",
        "weight": 0.7,  # 深度信息权重
        "image": image2,
        # ...
    }
]

常见问题与解决方案

API调用失败排查流程

1. 检查服务状态：确认WebUI已启动并启用API
2. 验证模型文件：确保models/目录下存在所需模型
3. 参数格式检查：使用JSON验证工具检查请求体格式
4. 查看日志信息：WebUI控制台输出的错误日志位于scripts/logging.py定义

性能优化建议

• 低显存模式：设置lowvram: True，代码实现见scripts/api.py#L109
• 分辨率调整：适当降低processor_res参数
• 批量处理：使用batch_size参数减少请求次数

错误码参考

状态码	含义	解决方案
422	参数错误	检查必填参数是否齐全，格式是否正确
500	服务器错误	查看WebUI控制台日志，检查模型文件
404	接口不存在	确认API路径正确，WebUI版本是否支持

总结与进阶学习

通过本文介绍的API，你已经掌握了sd-webui-controlnet的核心功能。想要进一步提升？推荐学习：

1. 源码深入：

   • 控制逻辑：scripts/controlnet_core/controlnet_union.py
   • 预处理模块：scripts/preprocessor/

2. 社区资源：

   • 官方文档：README.md
   • 测试案例：tests/
   • UI组件：javascript/

3. 扩展开发：

   • 自定义预处理：annotator/
   • 新模型支持：参考scripts/controlnet_model_guess.py

图6：多模块综合应用 - 结合Canny、Depth等多种控制方式生成的复杂场景

立即开始你的AI创作之旅吧！如有问题，可查阅项目tests/web_api/目录下的测试用例，或参考internal_controlnet/external_code.py中的API定义。

【免费下载链接】sd-webui-controlnet WebUI extension for ControlNet 项目地址: https://gitcode.com/gh_mirrors/sd/sd-webui-controlnet