如何快速掌握sd-webui-controlnet API：Python/JavaScript调用控制接口完整指南

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

sd-webui-controlnet是一款强大的WebUI扩展，为AI绘图提供精准的控制能力。本文将帮助新手开发者快速掌握其API客户端开发，通过Python和JavaScript两种语言实现对控制接口的调用，轻松实现AI绘图的自动化与定制化。

准备工作：环境搭建与项目克隆

在开始API开发前，需要先完成基础环境的搭建。首先确保你的系统已安装Python 3.8+和Git，然后通过以下命令克隆项目仓库：

git clone https://gitcode.com/gh_mirrors/sd/sd-webui-controlnet
cd sd-webui-controlnet
pip install -r requirements.txt

项目结构中，API相关的核心代码主要集中在scripts/api.py文件，该文件定义了所有可用的API端点和请求处理逻辑。

核心API端点解析

sd-webui-controlnet提供了丰富的API接口，让开发者能够全面控制AI绘图过程。以下是几个最常用的核心端点：

1. 获取版本信息

import requests

response = requests.get("http://localhost:7860/controlnet/version")
print(response.json())  # {"version": "1.1.152"}

这个简单的GET请求可以验证API服务是否正常运行，返回的版本号有助于确保客户端与服务端的兼容性。

2. 模型与模块列表

获取可用的ControlNet模型列表：

response = requests.get("http://localhost:7860/controlnet/model_list")
models = response.json()["model_list"]
print("可用模型:", models)

获取预处理器模块列表：

response = requests.get("http://localhost:7860/controlnet/module_list")
modules = response.json()["module_list"]
print("可用预处理器:", modules)

这些接口对于动态生成UI选项或验证用户输入非常有用。

3. 图像检测接口

最核心的API功能是图像检测，它可以将输入图像转换为ControlNet所需的控制信号。以下是一个Python调用示例：

import base64
import requests

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

base64_image = encode_image("input.jpg")

payload = {
    "controlnet_module": "canny",
    "controlnet_input_images": [base64_image],
    "controlnet_processor_res": 512,
    "controlnet_threshold_a": 100,
    "controlnet_threshold_b": 200
}

response = requests.post("http://localhost:7860/controlnet/detect", json=payload)
result = response.json()
print("检测结果:", result)

这个接口支持多种预处理器，如canny边缘检测、openpose姿态检测等，返回的结果可以直接用于后续的图像生成。

ControlNet WebUI界面展示了模型参数配置和生成结果预览，API调用可以实现同样的功能

Python客户端开发实例

下面我们将创建一个完整的Python客户端，实现从图像检测到最终图像生成的全流程：

import requests
import base64
import json

class ControlNetClient:
    def __init__(self, base_url="http://localhost:7860"):
        self.base_url = base_url
        
    def detect(self, image_path, module="canny", processor_res=512, threshold_a=100, threshold_b=200):
        """使用ControlNet检测图像特征"""
        with open(image_path, "rb") as f:
            image_data = base64.b64encode(f.read()).decode('utf-8')
            
        payload = {
            "controlnet_module": module,
            "controlnet_input_images": [image_data],
            "controlnet_processor_res": processor_res,
            "controlnet_threshold_a": threshold_a,
            "controlnet_threshold_b": threshold_b
        }
        
        response = requests.post(f"{self.base_url}/controlnet/detect", json=payload)
        return response.json()
    
    def generate_image(self, prompt, controlnet_result, model="v1-5-pruned-emaonly"):
        """生成图像"""
        payload = {
            "prompt": prompt,
            "steps": 20,
            "cfg_scale": 7,
            "width": 512,
            "height": 512,
            "controlnet_units": [
                {
                    "input_image": controlnet_result["images"][0],
                    "module": "canny",
                    "model": model,
                    "weight": 1.0
                }
            ]
        }
        
        response = requests.post(f"{self.base_url}/sdapi/v1/txt2img", json=payload)
        return response.json()

# 使用示例
client = ControlNetClient()
detect_result = client.detect("example/advanced_weighting_example/stock_mountain.png", "canny")
generate_result = client.generate_image("雪山风景, 高清, 细节丰富", detect_result)

# 保存生成的图像
with open("output.png", "wb") as f:
    f.write(base64.b64decode(generate_result["images"][0].split(",")[1]))

这个客户端类封装了ControlNet的核心功能，使得调用变得简单直观。你可以根据需要扩展更多方法，如支持批量处理、不同的预处理器等。

用于ControlNet处理的原始风景图像，通过API可以生成风格化的雪山图像

JavaScript客户端开发实例

对于Web前端开发者，使用JavaScript调用ControlNet API同样简单。以下是一个使用fetch API的示例：

// 图像编码函数
async function encodeImage(file) {
    return new Promise((resolve, reject) => {
        const reader = new FileReader();
        reader.onload = (e) => {
            const base64 = e.target.result.split(',')[1];
            resolve(base64);
        };
        reader.onerror = reject;
        reader.readAsDataURL(file);
    });
}

// 检测图像
async function detectImage(imageFile) {
    const base64Image = await encodeImage(imageFile);
    
    const response = await fetch('http://localhost:7860/controlnet/detect', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            controlnet_module: 'canny',
            controlnet_input_images: [base64Image],
            controlnet_processor_res: 512,
            controlnet_threshold_a: 100,
            controlnet_threshold_b: 200
        })
    });
    
    return response.json();
}

// 生成图像
async function generateImage(prompt, controlnetResult) {
    const response = await fetch('http://localhost:7860/sdapi/v1/txt2img', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            prompt: prompt,
            steps: 20,
            cfg_scale: 7,
            width: 512,
            height: 512,
            controlnet_units: [
                {
                    input_image: controlnetResult.images[0],
                    module: 'canny',
                    model: 'v1-5-pruned-emaonly',
                    weight: 1.0
                }
            ]
        })
    });
    
    return response.json();
}

// 使用示例
document.getElementById('image-upload').addEventListener('change', async (e) => {
    const file = e.target.files[0];
    if (!file) return;
    
    const detectResult = await detectImage(file);
    const generateResult = await generateImage("雪山风景, 高清, 细节丰富", detectResult);
    
    // 显示结果
    const img = document.createElement('img');
    img.src = `data:image/png;base64,${generateResult.images[0]}`;
    document.body.appendChild(img);
});

在实际项目中，你可能需要添加错误处理、加载状态指示等功能，以提升用户体验。

高级应用：Openpose姿态编辑

ControlNet的一个强大应用是姿态控制，通过API可以实现姿态的检测和编辑。以下是一个使用Openpose的示例：

# 检测姿态
payload = {
    "controlnet_module": "openpose",
    "controlnet_input_images": [base64_image]
}
response = requests.post("http://localhost:7860/controlnet/detect", json=payload)
poses = response.json()["poses"]

# 修改姿态数据
# ... 这里可以通过代码调整姿态关键点 ...

# 渲染修改后的姿态
response = requests.post("http://localhost:7860/controlnet/render_openpose_json", 
                         json={"pose_data": poses})
new_pose_image = response.json()["images"][0]

使用Openpose检测的人物姿态图像，通过API可以修改姿态并生成新的图像

常见问题与解决方案

1. API调用超时：增大timeout参数或检查服务端是否正常运行
2. 模型加载失败：确保模型文件放在models/目录下
3. 图像编码问题：使用正确的base64编码方式，确保不包含额外字符
4. 参数错误：参考scripts/api.py中的参数定义，确保类型和范围正确

总结

通过本文的指南，你已经掌握了sd-webui-controlnet API的基本调用方法和高级应用技巧。无论是Python还是JavaScript，都可以轻松实现对ControlNet的控制，为AI绘图添加更多可能性。随着项目的不断发展，更多强大的API功能将被添加，建议定期查看项目更新和文档，以获取最新的API信息。

开始你的ControlNet API开发之旅吧，创造出令人惊艳的AI艺术作品！

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