Implementation:AUTOMATIC1111 Stable diffusion webui API Models
| Knowledge Sources | |
|---|---|
| Domains | API, Data Models, Pydantic |
| Last Updated | 2025-05-15 00:00 GMT |
Overview
Defines all Pydantic data models (request/response schemas) used by the REST API, including dynamically generated models for txt2img and img2img processing parameters and static models for extras, progress, samplers, models, embeddings, scripts, and extensions.
Description
This module provides the complete API contract layer through two mechanisms:
Dynamic model generation: The PydanticModelGenerator class introspects the constructor signatures of StableDiffusionProcessingTxt2Img and StableDiffusionProcessingImg2Img using inspect.signature, merges parameters from all parent classes via MRO, filters out internal-only parameters (listed in API_NOT_ALLOWED), and creates Pydantic BaseModel subclasses with optional typed fields mirroring each constructor parameter. Additional API-specific fields (e.g., sampler_index, script_name, script_args, send_images, save_images, alwayson_scripts, force_task_id, infotext) are appended. The resulting models are StableDiffusionTxt2ImgProcessingAPI and StableDiffusionImg2ImgProcessingAPI.
Static models: Over 30 BaseModel subclasses define schemas for: image generation responses (TextToImageResponse, ImageToImageResponse), extras processing (ExtrasBaseRequest, ExtrasSingleImageRequest, ExtrasBatchImagesRequest), PNG info (PNGInfoRequest, PNGInfoResponse), progress tracking (ProgressRequest, ProgressResponse), interrogation, training, and resource listing (samplers, schedulers, upscalers, SD models, VAEs, hypernetworks, face restorers, prompt styles, embeddings, scripts, extensions).
Dynamic options and flags: OptionsModel is dynamically generated from opts.data_labels (all WebUI settings), and FlagsModel is generated from the command-line argument parser, providing full API exposure of all configuration.
Usage
These models are imported by modules/api/api.py and used as FastAPI request/response type annotations, providing automatic validation, serialization, and OpenAPI documentation generation.
Code Reference
Source Location
- Repository: AUTOMATIC1111_Stable_diffusion_webui
- File: modules/api/models.py
- Lines: 1-329
Signature
class ModelDef(BaseModel):
field: str
field_alias: str
field_type: Any
field_value: Any
field_exclude: bool = False
class PydanticModelGenerator:
def __init__(self, model_name: str, class_instance, additional_fields): ...
def generate_model(self): ...
# Dynamically generated models:
StableDiffusionTxt2ImgProcessingAPI = PydanticModelGenerator(...).generate_model()
StableDiffusionImg2ImgProcessingAPI = PydanticModelGenerator(...).generate_model()
# Static response/request models:
class TextToImageResponse(BaseModel): ...
class ImageToImageResponse(BaseModel): ...
class ExtrasBaseRequest(BaseModel): ...
class ExtrasSingleImageRequest(ExtrasBaseRequest): ...
class ExtrasBatchImagesRequest(ExtrasBaseRequest): ...
class PNGInfoRequest(BaseModel): ...
class PNGInfoResponse(BaseModel): ...
class ProgressRequest(BaseModel): ...
class ProgressResponse(BaseModel): ...
class InterrogateRequest(BaseModel): ...
class InterrogateResponse(BaseModel): ...
# Resource listing models:
class SamplerItem(BaseModel): ...
class SchedulerItem(BaseModel): ...
class UpscalerItem(BaseModel): ...
class SDModelItem(BaseModel): ...
class SDVaeItem(BaseModel): ...
class HypernetworkItem(BaseModel): ...
class EmbeddingItem(BaseModel): ...
class EmbeddingsResponse(BaseModel): ...
class MemoryResponse(BaseModel): ...
class ScriptsList(BaseModel): ...
class ScriptInfo(BaseModel): ...
class ExtensionItem(BaseModel): ...
# Dynamically generated from settings/flags:
OptionsModel = create_model("Options", **fields)
FlagsModel = create_model("Flags", **flags)
Import
from modules.api import models
# Access specific models:
models.StableDiffusionTxt2ImgProcessingAPI
models.TextToImageResponse
models.SDModelItem
models.OptionsModel
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| model_name | str | Yes (PydanticModelGenerator) | Name for the dynamically generated Pydantic model class |
| class_instance | type | Yes (PydanticModelGenerator) | The processing class to introspect (e.g., StableDiffusionProcessingTxt2Img) |
| additional_fields | list[dict] | Yes (PydanticModelGenerator) | List of extra field definitions with key, type, default, and optional exclude flag |
| prompt | str | No (Txt2Img API) | The text prompt for image generation |
| init_images | list[str] | Yes (Img2Img API) | Base64-encoded initial images for img2img processing |
| mask | str | No (Img2Img API) | Base64-encoded mask image for inpainting |
| image | str | Yes (Extras/PNGInfo) | Base64-encoded image for post-processing or info extraction |
Outputs
| Name | Type | Description |
|---|---|---|
| StableDiffusionTxt2ImgProcessingAPI | BaseModel | Dynamic Pydantic model with all txt2img parameters as optional fields plus API extras |
| StableDiffusionImg2ImgProcessingAPI | BaseModel | Dynamic Pydantic model with all img2img parameters as optional fields plus API extras |
| OptionsModel | BaseModel | Dynamic Pydantic model exposing all WebUI settings as typed optional fields |
| FlagsModel | BaseModel | Dynamic Pydantic model exposing all command-line flags as typed fields |
Usage Examples
from modules.api import models
# The dynamic models can be used for request validation:
txt2img_request = models.StableDiffusionTxt2ImgProcessingAPI(
prompt="a beautiful landscape",
steps=20,
sampler_name="Euler a",
width=512,
height=512,
cfg_scale=7,
seed=-1,
send_images=True,
save_images=False
)
# Static models for structured responses:
response = models.TextToImageResponse(
images=["base64encodedstring..."],
parameters={"prompt": "a beautiful landscape"},
info='{"seed": 12345, "steps": 20}'
)
# Extras request:
extras_req = models.ExtrasSingleImageRequest(
image="base64encodedimage...",
upscaling_resize=2,
upscaler_1="R-ESRGAN 4x+"
)
# PNG info extraction:
png_req = models.PNGInfoRequest(image="base64encodedpng...")