如何通过ControlNet API构建JSON参数并发送多控制单元请求？

在Stable Diffusion的自动化工作流中，通过API调用ControlNet是实现图像精准控制的核心环节。相比于在WebUI界面上手动操作，API调用允许我们将ControlNet无缝集成到各种自动化脚本和业务系统中。然而，ControlNet API的参数结构相对复杂，尤其是JSON格式的构建和多控制单元的发送，往往成为开发者接入过程中的拦路虎。理解其底层的参数传递逻辑，对于构建稳定的图像生成服务至关重要。

ControlNet API 接口基础与请求结构分析

要通过API调用ControlNet，首先需要明确它依附于哪个接口。在Stable Diffusion WebUI的API体系中，文生图接口/sdapi/v1/txt2img和图生图接口/sdapi/v1/img2img是两大核心入口。ControlNet本身并不是一个独立的API端点，而是作为这两个接口的一个扩展参数存在的。这意味着我们在构建请求时，需要将ControlNet的配置信息嵌入到文生图或图生图的JSON请求体中。

在早期的版本中，ControlNet参数通常放在alwayson_scripts字段下，而随着API的更新，现在更推荐使用专门的controlnet字段进行传递。这个字段接收一个对象，其中最核心的属性是args。args是一个数组，数组中的每一个元素都代表一个独立的ControlNet控制单元。这种设计非常灵活，既支持单个控制单元的简单应用，也允许多个控制单元叠加使用，从而实现更复杂的图像控制。

理解这种嵌套结构是成功调用的第一步。如果JSON结构层级错误，比如将控制单元的参数直接放在了controlnet对象下，而没有用args数组包裹，API将会返回参数解析错误，导致图像生成失败。因此，在构建请求体时，务必严格按照接口文档的数据结构进行层级映射。

深入解析JSON格式参数构建细节

构建一个有效的ControlNet控制单元，需要了解其内部包含的具体参数。在args数组中，每一个元素都是一个JSON对象，包含了该控制单元的完整配置。其中最关键的几个参数包括model（指定使用的ControlNet模型，如control_v11p_sd15_canny）、module（预处理器名称，如canny）、input_image（输入图像的Base64编码字符串）以及weight（控制权重）。

除了上述核心参数，还有一些辅助参数对生成效果影响巨大。例如processor_res控制预处理器的分辨率，threshold_a和threshold_b用于设置边缘检测等预处理器的阈值。在构建这些参数时，必须注意数据类型的准确性。input_image必须是去除了头部信息（如data:image/png;base64,）的纯Base64字符串，否则预处理器无法正确解析图像数据，会直接导致控制失效。

下面是一个构建单控制单元JSON参数的代码示例，展示了如何将一张本地图片编码并组装成符合API规范的请求体。在这个示例中，我们使用Python的base64库处理图像，并将其嵌入到args数组中。需要注意的是，args数组中的对象索引位置实际上对应了ControlNet在WebUI中的扩展编号，通常从0开始。

import base64
import requests
import json

# 读取本地图片并转换为Base64编码
with open("input.png", "rb") as image_file:
    encoded_string = base64.b64encode(image_file.read()).decode("utf-8")

# 构建文生图请求的基础参数
payload = {
    "prompt": "a beautiful girl, high quality",
    "steps": 20,
    "cfg_scale": 7
}

# 构建ControlNet参数
controlnet_args = {
    "model": "control_v11p_sd15_canny",
    "module": "canny",
    "input_image": encoded_string,
    "weight": 1.0,
    "processor_res": 512,
    "threshold_a": 100,
    "threshold_b": 200
}

# 将ControlNet参数嵌入到请求体中
payload["controlnet"] = {
    "args": [controlnet_args]
}

多控制单元发送的实现与避坑指南

在实际的高级应用场景中，我们往往需要同时使用多个ControlNet来约束图像的不同方面。例如，使用Canny模型控制边缘轮廓，同时使用Depth模型控制深度层次。通过API发送多控制单元，实际上就是向args数组中添加多个控制单元对象。API会按照数组中的顺序，依次将这些控制单元应用到图像生成的去噪过程中。

实现多控制单元发送时，最容易踩坑的地方在于参数的叠加冲突和显存溢出。每个控制单元都会占用一定的显存进行预处理和特征提取，如果一次性发送过多高分辨率的控制单元，很容易导致CUDA Out of Memory错误。此外，不同控制单元的权重设置需要谨慎平衡，如果两个控制单元的权重都很高，可能会导致图像生成时出现伪影或结构崩坏。

为了避免这些问题，建议在发送多控制单元请求时，合理设置每个单元的weight，通常可以适当降低单个单元的权重（如设置为0.5到0.8之间），让它们相互配合而不是相互冲突。同时，可以通过调整processor_res来降低预处理器的运行分辨率，从而减少显存占用。下面是一个发送两个控制单元的完整请求示例，展示了如何在一个请求中同时传递Canny和Depth控制。

# 假设已经准备好了两张图片的Base64编码：encoded_canny 和 encoded_depth
encoded_canny = "..." # 替换为实际的Base64字符串
encoded_depth = "..." # 替换为实际的Base64字符串

# 构建第一个控制单元
unit1 = {
    "model": "control_v11p_sd15_canny",
    "module": "canny",
    "input_image": encoded_canny,
    "weight": 0.7,
    "processor_res": 512
}

# 构建第二个控制单元
unit2 = {
    "model": "control_v11f1p_sd15_depth",
    "module": "depth_midas",
    "input_image": encoded_depth,
    "weight": 0.6,
    "processor_res": 512
}

# 构建完整的请求体
payload = {
    "prompt": "a highly detailed portrait, cinematic lighting",
    "steps": 25,
    "cfg_scale": 7,
    "controlnet": {
        "args": [unit1, unit2]
    }
}

# 发送请求到Stable Diffusion WebUI API
url = "http://127.0.0.1:7860/sdapi/v1/txt2img"
response = requests.post(url, json=payload)
print(response.status_code)

在上述代码中，我们将unit1和unit2同时放入了args数组中。API在接收到这个请求后，会分别对两张输入图像进行预处理，并将提取到的特征图叠加到U-Net的去噪过程中。通过这种方式，开发者可以构建出非常复杂且精确的图像生成工作流，充分发挥ControlNet在图像结构控制方面的强大能力。掌握多控制单元的JSON构建方法，是迈向自动化AI绘画生产的高级阶梯。

ControlNet APIJSON参数多控制单元修改时间：2026-08-28 08:21:07