ComfyUI Z-Image Streamlit Interface

A minimal and clean Streamlit web interface for generating images using the Z-Image Turbo model through ComfyUI.

Overview

This application provides an intuitive UI to interact with a running ComfyUI server, allowing you to generate high-quality images using the Z-Image Turbo model with customizable parameters.

Z-Image Model Capabilities

The Z-Image Turbo model excels at generating clean and accurate text within images, making it particularly well-suited for:

• Advertisement Creation: Generate professional ads with readable text overlays
• Marketing Content: Create social media posts, banners, and promotional materials
• Product Mockups: Design product packaging and labels with clear typography
• Infographics: Produce visual content with integrated text elements

Unlike many image generation models that struggle with text rendering, Z-Image can produce legible, well-formatted text as part of the generated image, making it an ideal choice for commercial and marketing applications.

Results

Here are some example images generated using this interface:

Features

• Two-Column Layout: Clean separation between controls and output
• Prompt Controls: Text areas for positive and negative prompts
• K-Sampler Settings: Adjustable parameters including:
  • Steps (1-50)
  • CFG Scale (1-15)
  • Seed control with randomization option
  • Sampler algorithm selection (euler, euler_a, dpmpp_2m)
  • Scheduler selection (simple, karras)
• Image Size Control: Customizable width and height (512-4096px)
• Real-time Preview: Generated images displayed immediately
• Download Capability: Save generated images locally
• Connection Testing: Verify ComfyUI server connectivity

Requirements

Python Dependencies

pip install streamlit requests

ComfyUI Setup

1. ComfyUI Server: Running instance of ComfyUI (default: http://127.0.0.1:8188)

2. Required Models:

   • UNET: z_image_turbo-Q3_K_M.gguf (in models/diffusion_models/)
   • CLIP: Qwen3-4B-Q3_K_M.gguf (in models/text_encoders/)
   • VAE: ae.safetensors (in models/vae/)

3. Custom Nodes:

   • ComfyUI-GGUF

Model Storage Structure

📂 ComfyUI/
├── 📂 models/
│   ├── 📂 text_encoders/
│   │   └── Qwen3-4B-Q3_K_M.gguf
│   ├── 📂 diffusion_models/
│   │   └── z_image_turbo-Q3_K_M.gguf
│   └── 📂 vae/
│       └── ae.safetensors

Installation

1. Clone or download this repository
2. Install Python dependencies:

   python -m pip install streamlit requests

3. Ensure ComfyUI is running with the required models and custom nodes

Usage

1. Start ComfyUI Server:

   # Navigate to your ComfyUI directory and start the server
   python main.py

2. Launch the Streamlit App:

   python -m streamlit run comfyui_streamlit_app.py

3. Access the Interface:

   • Open your browser to http://localhost:8501
   • The app will automatically open in your default browser

4. Generate Images:

   • Enter your prompt in the text area
   • Adjust K-Sampler settings as needed
   • Set image dimensions
   • Click "Generate"
   • Wait for the image to appear (typically 2-5 minutes)

Configuration

ComfyUI Host

Configure the ComfyUI server address in the sidebar:

• Default: http://127.0.0.1:8188
• Change if your ComfyUI runs on a different host/port

Timeout Settings

The app waits up to 5 minutes (300 seconds) for image generation. This can be adjusted in the code if needed:

def poll_for_image(host, prompt_id, max_wait=300, poll_interval=2):

Troubleshooting

Connection Issues

If you see "Connection failed. Is ComfyUI running?":

1. Verify ComfyUI is running
2. Check the host address in the sidebar
3. Click "Test Connection" to verify

Model Not Found Errors

If you get validation errors:

1. Ensure all required models are downloaded
2. Verify models are in the correct directories
3. Check that ComfyUI-GGUF custom node is installed

Timeout Errors

If generation times out:

1. Increase max_wait parameter in poll_for_image()
2. Check ComfyUI console for errors
3. Try reducing image dimensions

Project Structure

z-image/
├── comfyui_streamlit_app.py    # Main Streamlit application
├── example_workflow_z_image_compressed.json  # Reference workflow
├── Results/                     # Example generated images
└── README.md                    # This file

Technical Details

Workflow

The app constructs a ComfyUI workflow JSON with the following nodes:

• UnetLoaderGGUF: Loads the diffusion model
• CLIPLoaderGGUF: Loads the text encoder
• ModelSamplingAuraFlow: Configures model sampling
• CLIPTextEncode: Encodes positive and negative prompts
• EmptySD3LatentImage: Creates latent image canvas
• KSampler: Performs the sampling/generation
• VAELoader: Loads the VAE decoder
• VAEDecode: Decodes latent to image
• SaveImage: Saves the output

API Endpoints Used

• GET /system_stats: Connection testing
• POST /prompt: Submit generation workflow
• GET /history/{prompt_id}: Check generation status
• GET /view: Download generated image

Support

For issues related to:

• This UI: Check the troubleshooting section above
• ComfyUI: Visit the ComfyUI repository
• Z-Image Model: Visit the model page