Stable Diffusion WebUI API接口开发与集成指南

Stable Diffusion WebUI API接口开发与集成指南

【免费下载链接】stable-diffusion-webui AUTOMATIC1111/stable-diffusion-webui - 一个为Stable Diffusion模型提供的Web界面，使用Gradio库实现，允许用户通过Web界面使用Stable Diffusion进行图像生成。 项目地址: https://gitcode.com/GitHub_Trending/st/stable-diffusion-webui

本文详细介绍了Stable Diffusion WebUI的RESTful API接口设计与实现，涵盖了图像生成、模型管理、系统监控等核心功能。基于FastAPI框架构建的API系统提供了完整的请求/响应模型定义，支持身份验证和错误处理机制。文章将深入解析文本到图像生成API、图像处理与后处理API、以及模型管理与训练API的具体实现和使用方法。

RESTful API接口设计

Stable Diffusion WebUI 提供了完善的 RESTful API 接口，基于 FastAPI 框架构建，支持通过 HTTP 请求进行图像生成、模型管理、系统监控等操作。API 设计遵循 RESTful 原则，使用 JSON 格式进行数据交换，支持身份验证和错误处理机制。

API 基础架构

API 系统采用 FastAPI 作为 Web 框架，Pydantic 用于数据验证，提供了完整的请求/响应模型定义。所有 API 端点都以 /sdapi/v1/ 为前缀，确保版本控制和向后兼容性。

核心 API 端点

图像生成接口

文本到图像生成 (POST /sdapi/v1/txt2img)

{
    "prompt": "a beautiful landscape",
    "negative_prompt": "blurry, low quality",
    "steps": 20,
    "width": 512,
    "height": 512,
    "cfg_scale": 7.5,
    "sampler_name": "Euler",
    "seed": -1
}

图像到图像生成 (POST /sdapi/v1/img2img)

{
    "init_images": ["base64_encoded_image"],
    "denoising_strength": 0.75,
    "prompt": "make it anime style",
    "steps": 25,
    "width": 768,
    "height": 768
}

图像处理接口

单图像后处理 (POST /sdapi/v1/extra-single-image)

{
    "image": "base64_encoded_image",
    "resize_mode": 0,
    "upscaling_resize": 2,
    "gfpgan_visibility": 0.8,
    "codeformer_visibility": 0.5,
    "upscaler_1": "ESRGAN_4x"
}

批量图像处理 (POST /sdapi/v1/extra-batch-images)

{
    "imageList": [
        {"data": "base64_image_1", "name": "image1.png"},
        {"data": "base64_image_2", "name": "image2.png"}
    ],
    "upscaling_resize": 2
}

系统管理接口

模型管理

端点	方法	描述
/sdapi/v1/sd-models	GET	获取可用 Stable Diffusion 模型列表
/sdapi/v1/sd-vae	GET	获取可用 VAE 模型列表
/sdapi/v1/refresh-checkpoints	POST	刷新模型检查点
/sdapi/v1/unload-checkpoint	POST	卸载当前模型
/sdapi/v1/reload-checkpoint	POST	重新加载模型

采样器和配置

端点	方法	描述
/sdapi/v1/samplers	GET	获取可用采样器列表
/sdapi/v1/schedulers	GET	获取调度器列表
/sdapi/v1/upscalers	GET	获取超分辨率模型列表
/sdapi/v1/options	GET	获取当前配置
/sdapi/v1/options	POST	更新系统配置

数据处理流程

API 请求处理遵循严格的数据验证和处理流程：

身份验证机制

API 支持 Basic Authentication 身份验证，可以在启动时通过 --api-auth 参数配置用户名和密码：

python webui.py --api-auth "username:password"

身份验证中间件会验证每个请求的凭证：

def auth(self, credentials: HTTPBasicCredentials = Depends(HTTPBasic())):
    if credentials.username in self.credentials:
        if compare_digest(credentials.password, self.credentials[credentials.username]):
            return True
    raise HTTPException(status_code=401, detail="Incorrect username or password")

错误处理设计

API 实现了统一的错误处理机制，包括：

1. HTTP 异常处理：使用 FastAPI 的异常处理器
2. 输入验证错误：Pydantic 自动验证请求参数
3. 业务逻辑错误：自定义错误码和错误信息
4. 图像处理错误：捕获图像解码和处理异常

@app.exception_handler(Exception)
async def fastapi_exception_handler(request: Request, e: Exception):
    err = {
        "error": type(e).__name__,
        "detail": vars(e).get('detail', ''),
        "body": vars(e).get('body', ''),
        "errors": str(e),
    }
    return JSONResponse(status_code=500, content=jsonable_encoder(err))

性能监控中间件

API 包含性能监控中间件，记录每个请求的处理时间：

@app.middleware("http")
async def log_and_time(req: Request, call_next):
    ts = time.time()
    res: Response = await call_next(req)
    duration = str(round(time.time() - ts, 4))
    res.headers["X-Process-Time"] = duration
    return res

响应数据格式

所有 API 响应都遵循统一的格式规范：

成功响应示例：

{
    "images": ["base64_encoded_image_data"],
    "parameters": {
        "prompt": "a beautiful landscape",
        "steps": 20,
        "sampler_name": "Euler"
    },
    "info": "Generation completed in 15.2 seconds"
}

错误响应示例：

{
    "error": "ValidationError",
    "detail": "Invalid sampler name",
    "errors": "Sampler 'InvalidSampler' not found"
}

扩展性设计

API 设计具有良好的扩展性，支持：

1. 自定义脚本集成：可以通过 API 调用自定义处理脚本
2. 插件系统支持：与 WebUI 的扩展系统无缝集成
3. 批量操作支持：支持批量图像处理和生成
4. 实时进度查询：可以通过进度接口监控生成状态

class ScriptsList(BaseModel):
    txt2img: list[str] = Field(title="Txt2Img Scripts")
    img2img: list[str] = Field(title="Img2Img Scripts")

这种设计使得 Stable Diffusion WebUI 的 API 不仅功能强大，而且具有良好的可维护性和扩展性，为开发者提供了完整的程序化访问能力。

文本到图像生成API详解

Stable Diffusion WebUI的文本到图像生成API（txt2img）是整个API体系中最核心的功能之一，它允许开发者通过RESTful接口将文本描述转换为高质量的图像。这个API基于FastAPI框架构建，提供了完整的参数控制和灵活的扩展机制。

API端点与请求结构

文本到图像生成API的端点为 /sdapi/v1/txt2img，支持POST方法。请求体使用JSON格式，基于Pydantic模型进行严格的参数验证。

基本请求示例：

import requests
import json

url = "http://localhost:7860/sdapi/v1/txt2img"
payload = {
    "prompt": "a beautiful sunset over mountains, digital art",
    "negative_prompt": "blurry, low quality, watermark",
    "steps": 20,
    "width": 512,
    "height": 512,
    "cfg_scale": 7,
    "sampler_name": "Euler a",
    "batch_size": 1
}

response = requests.post(url, json=payload)
result = response.json()

核心参数详解

文本到图像API提供了丰富的参数来控制生成过程，主要可以分为以下几类：

1. 提示词参数

参数名	类型	默认值	描述
prompt	string	""	正向提示词，描述期望生成的图像内容
negative_prompt	string	""	负向提示词，描述不希望出现在图像中的内容

2. 图像尺寸参数

参数名	类型	默认值	描述
width	integer	512	生成图像的宽度（像素）
height	integer	512	生成图像的高度（像素）

3. 生成控制参数

参数名	类型	默认值	描述
steps	integer	20	去噪步数，影响生成质量和时间
cfg_scale	float	7.0	分类器自由引导尺度，控制提示词影响力
sampler_name	string	"Euler"	采样器名称
seed	integer	-1	随机种子，-1表示随机

4. 批量生成参数

参数名	类型	默认值	描述
batch_size	integer	1	每批生成的图像数量
n_iter	integer	1	生成批次数量

API处理流程

文本到图像API的处理过程遵循清晰的执行流程：

详细处理步骤：

1. 请求验证：API首先验证所有输入参数的有效性，包括采样器名称、脚本名称等
2. 脚本处理：根据请求中的脚本参数初始化相应的处理脚本
3. 采样器配置：配置指定的采样器和调度器
4. 任务管理：创建唯一任务ID并添加到处理队列
5. 图像生成：调用Stable Diffusion处理管道生成图像
6. 结果编码：将生成的图像编码为Base64格式
7. 响应构建：构建包含图像和元数据的JSON响应

高级功能特性

脚本支持

API支持自定义脚本扩展，可以通过 script_name 和 script_args 参数调用特定的处理脚本：

{
    "prompt": "a cat wearing a hat",
    "script_name": "prompt_matrix",
    "script_args": ["hat:1.2", "glasses:0.8"]
}

实时进度监控

结合进度API (/sdapi/v1/progress) 可以实现生成进度的实时监控：

def monitor_progress(task_id):
    progress_url = "http://localhost:7860/sdapi/v1/progress"
    while True:
        response = requests.get(progress_url)
        progress_data = response.json()
        if progress_data['state'].get('job_id') == task_id:
            print(f"Progress: {progress_data['progress'] * 100:.1f}%")
            if progress_data['progress'] >= 1.0:
                break
        time.sleep(0.5)

错误处理与响应格式

API采用标准的HTTP状态码和详细的错误信息：

成功响应示例：

{
    "images": [
        "base64_encoded_image_data"
    ],
    "parameters": {
        "prompt": "a beautiful landscape",
        "steps": 20,
        "sampler_name": "Euler a",
        "cfg_scale": 7.0
    },
    "info": "Generation complete in 15.2s"
}

错误响应示例：

{
    "error": "ValidationError",
    "detail": "Invalid sampler name: InvalidSampler",
    "status_code": 400
}

性能优化建议

1. 批量处理：使用 batch_size 和 n_iter 参数进行批量生成，减少API调用次数
2. 适当步数：根据需求调整 steps 参数，平衡质量与生成时间
3. 缓存种子：固定 seed 值可以重现特定结果，适合调试和测试
4. 异步处理：对于长时间任务，考虑使用异步调用模式

安全考虑

• API支持HTTP Basic认证，可以通过启动参数 --api-auth username:password 启用
• 可以配置禁止外部URL图像下载 (--api-forbid-local-requests)
• 建议在生产环境中启用认证并限制访问权限

文本到图像生成API为开发者提供了稳定可靠的图像生成服务，通过合理的参数配置和错误处理机制，能够满足各种应用场景的需求。其模块化设计和扩展性支持使得集成和定制变得简单高效。

图像处理与后处理API

Stable Diffusion WebUI 提供了强大的图像处理与后处理API，允许开发者对生成的图像进行各种增强和优化操作。这些API涵盖了图像放大、人脸修复、元数据提取等多个方面，为AI图像生成工作流提供了完整的后处理解决方案。

图像放大与增强API

单图像处理 API

/sdapi/v1/extra-single-image 端点用于对单张图像进行后处理，支持多种增强功能：

import requests
import base64
import json

# 单图像后处理示例
def process_single_image(image_path, upscaler="R-ESRGAN 4x+", scale=2.0):
    # 读取并编码图像
    with open(image_path, "rb") as image_file:
        image_data = base64.b64encode(image_file.read()).decode('utf-8')
    
    # 构建请求参数
    payload = {
        "resize_mode": 0,
        "show_extras_results": True,
        "gfpgan_visibility": 0,
        "codeformer_visibility": 0,
        "codeformer_weight": 0,
        "upscaling_resize": scale,
        "upscaling_resize_w": 512,
        "upscaling_resize_h": 512,
        "upscaling_crop": True,
        "upscaler_1": upscaler,
        "upscaler_2": "None",
        "extras_upscaler_2_visibility": 0,
        "upscale_first": False,
        "image": image_data
    }
    
    # 发送请求
    response = requests.post(
        "http://localhost:7860/sdapi/v1/extra-single-image",
        json=payload
    )
    
    if response.status_code == 200:
        result = response.json()
        # 解码处理后的图像
        processed_image = base64.b64decode(result["image"])
        with open("processed_image.png", "wb") as f:
            f.write(processed_image)
        return result["html_info"]
    else:
        raise Exception(f"API请求失败: {response.status_code}")

# 使用示例
# process_single_image("input.png", "R-ESRGAN 4x+", 2.0)

批量图像处理 API

/sdapi/v1/extra-batch-images 端点支持批量处理多张图像，适合大规模图像处理任务：

def process_batch_images(image_paths, upscaler="R-ESRGAN 4x+", scale=2.0):
    # 准备图像数据
    image_list = []
    for path in image_paths:
        with open(path, "rb") as f:
            image_data = base64.b64encode(f.read()).decode('utf-8')
            image_list.append({
                "data": image_data,
                "name": path.split("/")[-1]
            })
    
    # 构建请求
    payload = {
        "resize_mode": 0,
        "show_extras_results": True,
        "gfpgan_visibility": 0.5,  # 人脸修复可见度
        "codeformer_visibility": 0.5,  # CodeFormer可见度
        "codeformer_weight": 0.5,  # CodeFormer权重
        "upscaling_resize": scale,
        "upscaling_crop": True,
        "upscaler_1": upscaler,
        "upscaler_2": "None",
        "extras_upscaler_2_visibility": 0,
        "upscale_first": False,
        "imageList": image_list
    }
    
    response = requests.post(
        "http://localhost:7860/sdapi/v1/extra-batch-images",
        json=payload
    )
    
    if response.status_code == 200:
        result = response.json()
        # 保存所有处理后的图像
        for i, img_data in enumerate(result["images"]):
            with open(f"processed_{i}.png", "wb") as f:
                f.write(base64.b64decode(img_data))
        return result["html_info"]

图像后处理参数详解

后处理API支持丰富的参数配置，下表列出了主要参数及其功能：

参数名称	类型	默认值	描述
resize_mode	int	0	缩放模式：0-按比例缩放，1-指定尺寸
gfpgan_visibility	float	0	GFPGAN人脸修复可见度(0-1)
codeformer_visibility	float	0	CodeFormer人脸修复可见度(0-1)
codeformer_weight	float	0	CodeFormer修复权重(0-1)
upscaling_resize	float	2	放大倍数
upscaling_resize_w	int	512	目标宽度(当resize_mode=1时)
upscaling_resize_h	int	512	目标高度(当resize_mode=1时)
upscaling_crop	bool	True	是否裁剪以适应尺寸
upscaler_1	string	"None"	主放大器名称
upscaler_2	string	"None"	辅助放大器名称
extras_upscaler_2_visibility	float	0	辅助放大器可见度(0-1)
upscale_first	bool	False	是否先放大再修复人脸

图像元数据提取API

PNG信息提取 API

/sdapi/v1/png-info 端点用于从PNG图像中提取生成参数和元数据：

def extract_png_info(image_path):
    with open(image_path, "rb") as f:
        image_data = base64.b64encode(f.read()).decode('utf-8')
    
    payload = {"image": image_data}
    
    response = requests.post(
        "http://localhost:7860/sdapi/v1/png-info",
        json=payload
    )
    
    if response.status_code == 200:
        result = response.json()
        print("生成参数:", result["info"])
        print("元数据项:", json.dumps(result["items"], indent=2))
        print("解析后的参数:", json.dumps(result["parameters"], indent=2))
        return result

图像分析API

图像描述生成 API

/sdapi/v1/interrogate 端点使用CLIP或DeepDanbooru模型分析图像内容并生成描述：

def analyze_image(image_path, model="clip"):
    with open(image_path, "rb") as f:
        image_data = base64.b64encode(f.read()).decode('utf-8')
    
    payload = {
        "image": image_data,
        "model": model  # "clip" 或 "deepdanbooru"
    }
    
    response = requests.post(
        "http://localhost:7860/sdapi/v1/interrogate",
        json=payload
    )
    
    if response.status_code == 200:
        result = response.json()
        print(f"图像描述 ({model}):", result["caption"])
        return result["caption"]

后处理工作流程

Stable Diffusion WebUI的后处理系统遵循清晰的工作流程：

高级后处理配置

自定义后处理脚本

API支持通过脚本系统扩展后处理功能：

def get_available_upscalers():
    """获取可用的放大器列表"""
    response = requests.get("http://localhost:7860/sdapi/v1/upscalers")
    if response.status_code == 200:
        upscalers = response.json()
        return [upscaler["name"] for upscaler in upscalers]
    return []

def get_face_restorers():
    """获取可用的人脸修复器列表"""
    response = requests.get("http://localhost:7860/sdapi/v1/face-restorers")
    if response.status_code == 200:
        restorers = response.json()
        return [restorer["name"] for restorer in restorers]
    return []

实时进度监控

/sdapi/v1/progress 端点允许监控后处理任务的进度：

def monitor_progress():
    """监控处理进度"""
    response = requests.get("http://localhost:7860/sdapi/v1/progress")
    if response.status_code == 200:
        progress = response.json()
        print(f"进度: {progress['progress']*100:.1f}%")
        print(f"预计剩余时间: {progress['eta_relative']:.1f}秒")
        return progress

错误处理与最佳实践

健壮的API调用

def safe_api_call(url, payload, max_retries=3):
    """安全的API调用实现"""
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, timeout=30)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"尝试 {attempt + 1} 失败: {e}")
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # 指数退避

内存管理

大规模图像处理时需要注意内存管理：

def process_large_batch(image_paths, batch_size=10):
    """分批处理大量图像以避免内存溢出"""
    results = []
    for i in range(0, len(image_paths), batch_size):
        batch = image_paths[i:i + batch_size]
        print(f"处理批次 {i//batch_size + 1}/{(len(image_paths)-1)//batch_size + 1}")
        result = process_batch_images(batch)
        results.append(result)
        # 强制垃圾回收
        import gc
        gc.collect()
    return results

性能优化技巧

1. 选择合适的放大器：根据图像内容选择最适合的放大算法
2. 批量处理：使用批量API减少HTTP请求开销
3. 内存优化：合理设置批量大小，避免内存溢出
4. 网络优化：使用Keep-Alive连接减少连接建立开销
5. 缓存策略：对重复处理任务实现结果缓存

通过合理利用Stable Diffusion WebUI的图像处理与后处理API，开发者可以构建高效、可靠的AI图像处理流水线，满足各种商业和创意需求。

模型管理与训练API

Stable Diffusion WebUI 提供了完整的模型管理与训练API接口，允许开发者通过编程方式创建、训练和管理文本嵌入（Embeddings）和超网络（Hypernetworks）。这些API为自动化训练流程和集成到现有工作流提供了强大的工具支持。

文本嵌入管理API

文本嵌入（Textual Inversion）是一种通过少量图像训练自定义概念的技术。WebUI提供了完整的嵌入创建和训练API：

创建新嵌入

import requests

# 创建新的文本嵌入
def create_embedding(name, num_vectors, overwrite_old):
    url = "http://localhost:7860/sdapi/v1/create/embedding"
    payload = {
        "name": name,
        "num_vectors": num_vectors,
        "overwrite_old": overwrite_old
    }
    response = requests.post(url, json=payload)
    return response.json()

# 示例：创建包含10个向量的新嵌入
result = create_embedding("my_custom_style", 10, False)
print(result["info"])  # 返回创建信息

训练文本嵌入

def train_embedding(embedding_name, learn_rate, batch_size, data_root, steps):
    url = "http://localhost:7860/sdapi/v1/train/embedding"
    payload = {
        "embedding_name": embedding_name,
        "learn_rate": learn_rate,
        "batch_size": batch_size,
        "gradient_step": 1,
        "data_root": data_root,
        "steps": steps,
        "log_directory": "logs/embeddings",
        "training_width": 512,
        "training_height": 512,
        "varsize": False,
        "clip_grad_mode": "disabled",
        "clip_grad_value": 1.0,
        "shuffle_tags": True,
        "tag_drop_out": 0,
        "latent_sampling_method": "once",
        "create_image_every": 100,
        "save_embedding_every": 500,
        "template_file": "style_filewords.txt"
    }
    response = requests.post(url, json=payload)
    return response.json()

# 示例：训练自定义嵌入
result = train_embedding("my_custom_style", 0.005, 1, "/path/to/training/images", 1000)

超网络管理API

超网络（Hypernetwork）是一种更复杂的模型扩展技术，WebUI同样提供了完整的API支持：

创建超网络

def create_hypernetwork(name, sizes, layer_structure, activation_func):
    url = "http://localhost:7860/sdapi/v1/create/hypernetwork"
    payload = {
        "name": name,
        "sizes": sizes,
        "layer_structure": layer_structure,
        "activation_func": activation_func,
        "initialization_option": "Normal",
        "add_layer_norm": False,
        "use_dropout": False,
        "overwrite_old": False
    }
    response = requests.post(url, json=payload)
    return response.json()

# 示例：创建新的超网络
result = create_hypernetwork(
    "my_hypernetwork", 
    ["768", "320", "640", "1280"], 
    "1,2,1", 
    "relu"
)

训练超网络

def train_hypernetwork(hypernetwork_name, learn_rate, batch_size, data_root, steps):
    url = "http://localhost:7860/sdapi/v1/train/hypernetwork"
    payload = {
        "hypernetwork_name": hypernetwork_name,
        "learn_rate": learn_rate,
        "batch_size": batch_size,
        "gradient_step": 1,
        "data_root": data_root,
        "steps": steps,
        "log_directory": "logs/hypernetworks",
        "training_width": 512,
        "training_height": 512,
        "varsize": False,
        "clip_grad_mode": "disabled",
        "clip_grad_value": 1.0,
        "shuffle_tags": True,
        "tag_drop_out": 0,
        "latent_sampling_method": "once",
        "create_image_every": 100,
        "save_hypernetwork_every": 500,
        "template_file": "style_filewords.txt",
        "preview_from_txt2img": False
    }
    response = requests.post(url, json=payload)
    return response.json()

训练参数详解

以下是训练API的核心参数说明：

参数名	类型	默认值	描述
learn_rate	float	0.005	学习率，控制训练速度
batch_size	int	1	批次大小，影响内存使用
gradient_step	int	1	梯度累积步数
data_root	string	-	训练图像目录路径
steps	int	1000	总训练步数
training_width	int	512	训练图像宽度
training_height	int	512	训练图像高度
save_embedding_every	int	500	每隔多少步保存嵌入
create_image_every	int	100	每隔多少步生成预览图像

训练流程控制

错误处理与状态管理

训练API提供了完善的错误处理机制：

def train_with_error_handling(params):
    try:
        response = requests.post(
            "http://localhost:7860/sdapi/v1/train/embedding",
            json=params,
            timeout=3600  # 1小时超时
        )
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"训练失败: {response.text}")
    except requests.exceptions.Timeout:
        raise Exception("训练超时，请检查训练进度")
    except requests.exceptions.RequestException as e:
        raise Exception(f"网络错误: {str(e)}")

训练状态监控

可以通过进度API监控训练状态：

def get_training_progress():
    url = "http://localhost:7860/sdapi/v1/progress"
    response = requests.get(url)
    progress_data = response.json()
    
    if progress_data["state"]["job"] == "train-embedding":
        current_step = progress_data["state"]["sampling_step"]
        total_steps = progress_data["state"]["sampling_steps"]
        progress_percent = (current_step / total_steps) * 100
        return f"训练进度: {progress_percent:.1f}%"
    return "当前没有训练任务"

最佳实践建议

1. 数据准备: 确保训练图像质量高、主题一致，建议使用10-50张图像
2. 学习率设置: 嵌入训练建议0.005，超网络建议0.00001
3. 批量大小: 根据GPU内存调整，通常设置为1或2
4. 训练步数: 嵌入通常需要1000-3000步，超网络需要更多步数
5. 定期保存: 设置合理的保存间隔，防止训练中断丢失进度

通过合理使用这些API，开发者可以构建自动化的模型训练流水线，实现大规模定制化模型的批量训练和管理。

总结

Stable Diffusion WebUI提供了强大而完整的RESTful API接口体系，为开发者提供了程序化访问AI图像生成能力的完整解决方案。从基础的文本到图像生成，到复杂的图像后处理和模型训练管理，API设计都遵循了RESTful原则并具有良好的扩展性。通过合理的参数配置和错误处理机制，这些API能够满足各种商业和创意应用场景的需求。其模块化设计和插件系统支持使得集成和定制变得简单高效，为构建自动化AI图像处理流水线提供了坚实的技术基础。

【免费下载链接】stable-diffusion-webui AUTOMATIC1111/stable-diffusion-webui - 一个为Stable Diffusion模型提供的Web界面，使用Gradio库实现，允许用户通过Web界面使用Stable Diffusion进行图像生成。 项目地址: https://gitcode.com/GitHub_Trending/st/stable-diffusion-webui