tessl/pypi-webuiapi

Python API client for AUTOMATIC1111/stable-diffusion-webui enabling programmatic Stable Diffusion image generation

Overview

Eval results

Files

Image Processing

Name: tessl/pypi-webuiapi
Author: tessl

Advanced image processing operations including upscaling, interrogation, metadata extraction, and batch processing capabilities. These functions provide essential post-processing and analysis tools for generated and existing images.

Capabilities

Image Upscaling and Enhancement

High-quality image upscaling and enhancement using various algorithms and models.

def extra_single_image(
    image: Image.Image,
    upscaler_1: str = "None",
    upscaling_resize: float = 2.0,
    upscaling_resize_w: int = 0,
    upscaling_resize_h: int = 0,
    upscaling_crop: bool = True,
    upscaler_2: str = "None",
    extras_upscaler_2_visibility: float = 0.0,
    gfpgan_visibility: float = 0.0,
    codeformer_visibility: float = 0.0,
    codeformer_weight: float = 0.0,
    **kwargs
) -> WebUIApiResult:
    """
    Upscale and enhance a single image.

    Parameters:
    - image: Input PIL Image to process
    - upscaler_1: Primary upscaling algorithm
    - upscaling_resize: Resize factor (e.g., 2.0 for 2x)
    - upscaling_resize_w: Target width (0 to use resize factor)
    - upscaling_resize_h: Target height (0 to use resize factor)
    - upscaling_crop: Crop to exact dimensions if needed
    - upscaler_2: Secondary upscaling algorithm
    - extras_upscaler_2_visibility: Blend factor for second upscaler (0.0-1.0)
    - gfpgan_visibility: GFPGAN face restoration strength (0.0-1.0)
    - codeformer_visibility: CodeFormer face restoration strength (0.0-1.0)
    - codeformer_weight: CodeFormer processing weight (0.0-1.0)

    Returns:
    WebUIApiResult containing the upscaled image
    """

def extra_batch_images(
    images: List[Image.Image],
    upscaler_1: str = "None",
    upscaling_resize: float = 2.0,
    upscaling_resize_w: int = 0,
    upscaling_resize_h: int = 0,
    upscaling_crop: bool = True,
    upscaler_2: str = "None",
    extras_upscaler_2_visibility: float = 0.0,
    gfpgan_visibility: float = 0.0,
    codeformer_visibility: float = 0.0,
    codeformer_weight: float = 0.0,
    **kwargs
) -> WebUIApiResult:
    """
    Upscale and enhance multiple images in batch.

    Parameters:
    - images: List of PIL Images to process
    - upscaler_1: Primary upscaling algorithm
    - upscaling_resize: Resize factor
    - upscaling_resize_w: Target width (0 to use resize factor)
    - upscaling_resize_h: Target height (0 to use resize factor)
    - upscaling_crop: Crop to exact dimensions
    - upscaler_2: Secondary upscaling algorithm
    - extras_upscaler_2_visibility: Blend factor for second upscaler
    - gfpgan_visibility: GFPGAN face restoration strength
    - codeformer_visibility: CodeFormer face restoration strength
    - codeformer_weight: CodeFormer processing weight

    Returns:
    WebUIApiResult containing all upscaled images
    """

Image Analysis and Interrogation

Extract information from images including generating prompts and reading metadata.

def interrogate(
    image: Image.Image,
    model: str = "clip"
) -> str:
    """
    Generate text description of an image using AI models.

    Parameters:
    - image: PIL Image to analyze
    - model: Interrogation model ("clip" or "deepdanbooru")

    Returns:
    Generated text description/tags for the image
    """

def png_info(image: Image.Image) -> Dict:
    """
    Extract generation parameters from PNG metadata.

    Parameters:
    - image: PIL Image with embedded metadata

    Returns:
    Dictionary containing:
    - info: Generation parameters text
    - items: Parsed parameter dictionary
    """

Utility Functions

Helper functions for image encoding and conversion operations.

def b64_img(image: Image.Image) -> str:
    """
    Convert PIL Image to base64 with data URL header.

    Parameters:
    - image: PIL Image to convert

    Returns:
    Base64-encoded image with data URL prefix (data:image/png;base64,...)
    """

def raw_b64_img(image: Image.Image, format: str = "PNG") -> str:
    """
    Convert PIL Image to raw base64 encoding without header.

    Parameters:
    - image: PIL Image to convert
    - format: Output format ("PNG", "JPEG", "WEBP")

    Returns:
    Raw base64-encoded image data without data URL prefix
    """

Usage Examples:

from PIL import Image
import webuiapi

api = webuiapi.WebUIApi()

# Single image upscaling
input_image = Image.open("low_res_image.jpg")

# Basic 2x upscaling with ESRGAN
result = api.extra_single_image(
    image=input_image,
    upscaler_1="R-ESRGAN 4x+",
    upscaling_resize=2.0
)

upscaled_image = result.image
upscaled_image.save("upscaled_2x.png")

# High-quality upscaling with face restoration
result = api.extra_single_image(
    image=input_image,
    upscaler_1="R-ESRGAN 4x+",
    upscaling_resize=4.0,
    gfpgan_visibility=0.8,  # Strong face restoration
    codeformer_visibility=0.5  # Additional face enhancement
)

enhanced_image = result.image
enhanced_image.save("enhanced_4x.png")

# Dual upscaler blending
result = api.extra_single_image(
    image=input_image,
    upscaler_1="R-ESRGAN 4x+",
    upscaler_2="SwinIR 4x",
    upscaling_resize=2.0,
    extras_upscaler_2_visibility=0.3  # 30% second upscaler
)

# Batch processing multiple images
image_list = [
    Image.open("image1.jpg"),
    Image.open("image2.jpg"),
    Image.open("image3.jpg")
]

batch_result = api.extra_batch_images(
    images=image_list,
    upscaler_1="R-ESRGAN 4x+",
    upscaling_resize=2.0,
    gfpgan_visibility=0.5
)

# Save all batch results
for i, enhanced_img in enumerate(batch_result.images):
    enhanced_img.save(f"batch_enhanced_{i}.png")

# Image interrogation for prompt generation
test_image = Image.open("generated_art.png")

# Generate descriptive prompt using CLIP
clip_description = api.interrogate(test_image, model="clip")
print(f"CLIP description: {clip_description}")

# Generate tags using DeepDanbooru (good for anime/art)
danbooru_tags = api.interrogate(test_image, model="deepdanbooru")
print(f"Danbooru tags: {danbooru_tags}")

# Extract generation parameters from PNG
generated_image = Image.open("stable_diffusion_output.png")
metadata = api.png_info(generated_image)

if metadata.get('info'):
    print("Original generation parameters:")
    print(metadata['info'])
    
    # Parse parameters if available
    params = metadata.get('items', {})
    if params:
        print(f"Prompt: {params.get('Prompt', 'N/A')}")
        print(f"Steps: {params.get('Steps', 'N/A')}")
        print(f"Sampler: {params.get('Sampler', 'N/A')}")
        print(f"CFG Scale: {params.get('CFG scale', 'N/A')}")
        print(f"Seed: {params.get('Seed', 'N/A')}")

Error Handling

Image processing operations may fail due to various reasons. Handle common scenarios:

import webuiapi
from PIL import Image

api = webuiapi.WebUIApi()

try:
    image = Image.open("input.jpg")
    result = api.extra_single_image(
        image=image,
        upscaler_1="R-ESRGAN 4x+",
        upscaling_resize=4.0
    )
    
    if result.images:
        result.image.save("output.png")
    else:
        print("No images returned")
        
except Exception as e:
    print(f"Processing failed: {e}")
    # Handle specific error cases:
    # - Invalid upscaler name
    # - Out of memory for large images
    # - Network connection issues

Types

class WebUIApiResult:
    """Result container for image processing operations."""
    images: List[Image.Image]  # Processed images
    parameters: Dict  # Processing parameters used
    info: Dict  # Processing metadata
    json: Dict  # Raw API response
    
    @property
    def image(self) -> Image.Image:
        """First processed image (convenience property)."""

Install with Tessl CLI