Generate images with Flash and SDXL

Flash is now part of the Runpod SDK. This page documents the standalone runpod-flash package, which stops getting fixes and updates after its deprecation date. For new projects, use the Runpod SDK. To see how Flash commands and imports map to the SDK, see Migrating from Flash.

This tutorial shows you how to build an image generation script using Flash and Stable Diffusion XL (SDXL). You’ll learn how to load a pretrained diffusion model on a GPU worker and generate images from text prompts.

Requirements

You’ve created a Runpod account.
You’ve created a Runpod API key.
You’ve installed Python 3.10 to 3.14.
You’ve completed the Flash quickstart or are familiar with Flash basics.

What you’ll build

By the end of this tutorial, you’ll have a working image generation application that:

Accepts text prompts as input.
Generates photorealistic images using Stable Diffusion XL.
Runs entirely on Runpod’s GPU infrastructure.
Saves generated images to your local machine.

Step 1: Set up your project

Create a new directory for your project and set up a Python virtual environment:

mkdir flash-image-generation
cd flash-image-generation

Install Flash using uv:

uv venv
source .venv/bin/activate
uv pip install runpod-flash

flash login

Alternatively, create a .env file with your API key. Flash loads .env from the current directory automatically:

echo "RUNPOD_API_KEY=YOUR_API_KEY" > .env

Replace YOUR_API_KEY with your API key from the Runpod console.

The directory name becomes your Flash app name. Run flash deploy and your script from this directory.

Step 2: Understand Stable Diffusion XL

Stable Diffusion XL (SDXL) is a text-to-image model from Stability AI. It generates 1024x1024 images and follows prompts more closely than Stable Diffusion 1.5. What to expect when you run it on Runpod:

Model size: about 7 GB of fp16 weights, downloaded by the worker the first time it loads the model.
VRAM: at least 16 GB. This tutorial uses 24 GB GPUs.
Speed: once the model is loaded, 30 steps take about 4-5 seconds on an RTX 4090.

You’ll use the diffusers library from Hugging Face to load and run the model.

Step 3: Create your project file

Create a file called image_generation.py in your project directory. The next three steps build it up section by section. The complete file is at the end of Step 6.

Step 4: Add imports and configuration

import asyncio
import base64
from pathlib import Path

from runpod_flash import Endpoint, GpuGroup

MODEL_ID = "stabilityai/stable-diffusion-xl-base-1.0"

# Each worker keeps the loaded pipeline here between requests.
_pipeline = None

_pipeline caches the model on the worker. Without it, every request would load 7 GB of weights from disk into GPU memory again, which adds about 20 seconds per image.

Step 5: Define the image generation function

Add the endpoint function that runs on the GPU worker:

@Endpoint(
    name="image-generation",
    gpu=[GpuGroup.ADA_24, GpuGroup.AMPERE_24],  # 24 GB GPUs
    workers=2,
    idle_timeout=900,  # Keep workers warm for 15 minutes
    dependencies=["diffusers", "torch", "transformers"],
)
def generate_image(prompt, negative_prompt="", num_steps=30, guidance_scale=7.5, seed=None):
    """Generate an image with Stable Diffusion XL and return it as base64 PNG."""
    import time
    from io import BytesIO

    import torch
    from diffusers import StableDiffusionXLPipeline

    global _pipeline
    cached = _pipeline is not None
    start = time.perf_counter()
    if _pipeline is None:
        _pipeline = StableDiffusionXLPipeline.from_pretrained(
            MODEL_ID,
            torch_dtype=torch.float16,
            use_safetensors=True,
            variant="fp16",
        ).to("cuda")
    load_seconds = time.perf_counter() - start

    generator = None
    if seed is not None:
        generator = torch.Generator("cuda").manual_seed(seed)

    start = time.perf_counter()
    image = _pipeline(
        prompt=prompt,
        negative_prompt=negative_prompt,
        num_inference_steps=num_steps,
        guidance_scale=guidance_scale,
        generator=generator,
    ).images[0]
    generate_seconds = time.perf_counter() - start

    buffer = BytesIO()
    image.save(buffer, format="PNG")

    return {
        "image_base64": base64.b64encode(buffer.getvalue()).decode(),
        "gpu": torch.cuda.get_device_name(0),
        "model_cached": cached,
        "load_seconds": round(load_seconds, 1),
        "generate_seconds": round(generate_seconds, 1),
    }

Configuration breakdown:

name="image-generation": Identifies your endpoint in the Runpod console.
gpu=[GpuGroup.ADA_24, GpuGroup.AMPERE_24]: Uses 24 GB GPUs such as the RTX 4090, L4, or A5000. SDXL needs at least 16 GB.
workers=2: Allows up to 2 parallel workers.
idle_timeout=900: Keeps a worker running for 15 minutes after its last request, so the loaded model stays in memory.
dependencies: Installed into your build. torch is already in the worker image, so Flash leaves it out of the upload.

Don’t add accelerate to dependencies. It requires torch, so on Linux flash deploy downloads torch and several GB of CUDA libraries into the local build, which can fill your disk. Without it, the build is about 50 MB.

Code breakdown

Imports inside the function: torch and diffusers are imported inside generate_image because they’re installed on the worker, not on your machine.Model caching:

global _pipeline
if _pipeline is None:
    _pipeline = StableDiffusionXLPipeline.from_pretrained(...).to("cuda")

The worker imports your file once and keeps it in memory between requests, so module-level variables like _pipeline persist. The first request on a worker loads the model. Later requests on the same worker reuse it. model_cached in the result tells you which happened.Model loading parameters:

torch_dtype=torch.float16: Half precision. Uses less VRAM and runs faster.
use_safetensors=True: Loads the safetensors format.
variant="fp16": Downloads the fp16 weights (about 7 GB instead of 14 GB).

Generation parameters:

prompt: What you want to see in the image.
negative_prompt: What you don’t want, such as “blurry, low quality”.
num_inference_steps: More steps give more refined images but take longer. 20-50 is typical.
guidance_scale: How closely to follow the prompt. 7-10 is typical.
generator: A seeded generator makes results reproducible. The same prompt and seed give the same image.

Image encoding:

buffer = BytesIO()
image.save(buffer, format="PNG")
base64.b64encode(buffer.getvalue()).decode()

Endpoint results are sent back as JSON, so the PNG is encoded as a base64 string.

Step 6: Add the main function and image saving

Add a helper that saves images and a main() function that calls the endpoint. Everything in this step runs on your machine:

def save_image(image_base64, path):
    """Decode a base64 PNG and write it to disk."""
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_bytes(base64.b64decode(image_base64))
    print(f"Saved {path}")


async def main():
    print("Generating an image with SDXL on a Runpod GPU...")
    result = await generate_image(
        prompt="A serene mountain lake at sunset, highly detailed, photorealistic",
        negative_prompt="blurry, low quality, distorted",
        num_steps=30,
        seed=42,
    )
    save_image(result["image_base64"], Path("generated_images") / "sdxl_output.png")
    print(f"GPU: {result['gpu']}")
    print(f"Model already loaded: {result['model_cached']}")
    print(f"Model load: {result['load_seconds']}s, generation: {result['generate_seconds']}s")


if __name__ == "__main__":
    asyncio.run(main())

Keep the if __name__ == "__main__": block at the end of the file. Without it, the script exits without doing anything.

Complete file

image_generation.py

import asyncio
import base64
from pathlib import Path

from runpod_flash import Endpoint, GpuGroup

MODEL_ID = "stabilityai/stable-diffusion-xl-base-1.0"

# Each worker keeps the loaded pipeline here between requests.
_pipeline = None


@Endpoint(
    name="image-generation",
    gpu=[GpuGroup.ADA_24, GpuGroup.AMPERE_24],  # 24 GB GPUs
    workers=2,
    idle_timeout=900,  # Keep workers warm for 15 minutes
    dependencies=["diffusers", "torch", "transformers"],
)
def generate_image(prompt, negative_prompt="", num_steps=30, guidance_scale=7.5, seed=None):
    """Generate an image with Stable Diffusion XL and return it as base64 PNG."""
    import time
    from io import BytesIO

    import torch
    from diffusers import StableDiffusionXLPipeline

    global _pipeline
    cached = _pipeline is not None
    start = time.perf_counter()
    if _pipeline is None:
        _pipeline = StableDiffusionXLPipeline.from_pretrained(
            MODEL_ID,
            torch_dtype=torch.float16,
            use_safetensors=True,
            variant="fp16",
        ).to("cuda")
    load_seconds = time.perf_counter() - start

    generator = None
    if seed is not None:
        generator = torch.Generator("cuda").manual_seed(seed)

    start = time.perf_counter()
    image = _pipeline(
        prompt=prompt,
        negative_prompt=negative_prompt,
        num_inference_steps=num_steps,
        guidance_scale=guidance_scale,
        generator=generator,
    ).images[0]
    generate_seconds = time.perf_counter() - start

    buffer = BytesIO()
    image.save(buffer, format="PNG")

    return {
        "image_base64": base64.b64encode(buffer.getvalue()).decode(),
        "gpu": torch.cuda.get_device_name(0),
        "model_cached": cached,
        "load_seconds": round(load_seconds, 1),
        "generate_seconds": round(generate_seconds, 1),
    }


def save_image(image_base64, path):
    """Decode a base64 PNG and write it to disk."""
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_bytes(base64.b64decode(image_base64))
    print(f"Saved {path}")


async def main():
    print("Generating an image with SDXL on a Runpod GPU...")
    result = await generate_image(
        prompt="A serene mountain lake at sunset, highly detailed, photorealistic",
        negative_prompt="blurry, low quality, distorted",
        num_steps=30,
        seed=42,
    )
    save_image(result["image_base64"], Path("generated_images") / "sdxl_output.png")
    print(f"GPU: {result['gpu']}")
    print(f"Model already loaded: {result['model_cached']}")
    print(f"Model load: {result['load_seconds']}s, generation: {result['generate_seconds']}s")


if __name__ == "__main__":
    asyncio.run(main())

Step 7: Deploy and run your first generation

Deploy the endpoint from your project directory:

flash deploy

# If using uv:
uv run flash deploy

Flash installs your dependencies into a local build directory, uploads the build, and creates the image-generation endpoint:

✓ built flash-image-generation  1 files, 2 deps, 50.2 MB
No app 'flash-image-generation' found. Creating app and 'production' environment...

✓ uploaded  50.2 MB  3.0s
✓ deployed to production  1.9s

  image-generation  https://api.runpod.ai/v2/abc123xyz/runsync

curl -X POST https://api.runpod.ai/v2/abc123xyz/runsync \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RUNPOD_API_KEY" \
  -d '{"input": {}}'

Then run the script from the same directory:

python image_generation.py

The first run takes about 80 seconds. The worker starts, downloads the SDXL weights, and loads them onto the GPU:

Generating an image with SDXL on a Runpod GPU...
Saved generated_images/sdxl_output.png
GPU: NVIDIA GeForce RTX 4090
Model already loaded: False
Model load: 18.0s, generation: 4.9s

Run it again while the worker is warm. The model is already loaded, so the whole run takes about 7 seconds:

Generating an image with SDXL on a Runpod GPU...
Saved generated_images/sdxl_output.png
GPU: NVIDIA GeForce RTX 4090
Model already loaded: True
Model load: 0.0s, generation: 3.9s

Open generated_images/sdxl_output.png to see your image.

The first request on a new worker can take longer than the 90 seconds runpod-flash 1.21.0 waits for a result, especially if the worker has to wait for a free GPU. If the script fails with timed out after 90s. the endpoint may not be deployed or the worker is still starting or KeyError: 'image_base64', the endpoint is deployed and the worker is still loading the model. Run the script again. See First run fails after 90 seconds.

Step 8: Generate several images in parallel

Replace main() with a version that sends three prompts at once with asyncio.gather:

PROMPTS = {
    "cyberpunk_city": "A cyberpunk city at night with neon lights and rain, cinematic",
    "space_corgi": "A corgi puppy in a space suit floating in space, highly detailed",
    "wizard_study": "An ancient wizard's study full of books and potions, candlelight",
}


async def main():
    print(f"Generating {len(PROMPTS)} images in parallel...")
    results = await asyncio.gather(
        *(generate_image(prompt=prompt, seed=42) for prompt in PROMPTS.values())
    )
    for name, result in zip(PROMPTS, results):
        save_image(result["image_base64"], Path("generated_images") / f"{name}.png")
        print(f"  model already loaded: {result['model_cached']}, "
              f"generation: {result['generate_seconds']}s")


if __name__ == "__main__":
    asyncio.run(main())

You only changed code outside the @Endpoint function, so you don’t need to redeploy. Run the script:

python image_generation.py

Generating 3 images in parallel...
Saved generated_images/cyberpunk_city.png
  model already loaded: True, generation: 3.9s
Saved generated_images/space_corgi.png
  model already loaded: True, generation: 3.9s
Saved generated_images/wizard_study.png
  model already loaded: True, generation: 3.9s

All three requests are queued at once. A warm worker generates them one after another, about 18 seconds in total. If the queue builds up, Flash starts the second worker (workers=2). A new worker loads the model on its first request, so that result shows model already loaded: False.

Keep the endpoint function and the code that calls it in the same file. If a second file imports generate_image, flash deploy treats it as a second definition and fails with endpoint 'image-generation' is defined in multiple files.

Understanding generation parameters

Let’s explore how different parameters affect image quality:

Number of inference steps

# Fast but lower quality (15-20 steps)
result = await generate_image(prompt, num_steps=20)

# Balanced (30 steps) - recommended
result = await generate_image(prompt, num_steps=30)

# High quality but slower (50 steps)
result = await generate_image(prompt, num_steps=50)

Effects:

15-20 steps: Faster, but fewer refined details.
30 steps: A good balance of quality and speed (about 4-5 seconds on an RTX 4090). Recommended.
50+ steps: Diminishing returns, with little visible improvement.

Generation time grows roughly in proportion to the number of steps.

Guidance scale

# Low guidance - more creative, less faithful to prompt
result = await generate_image(prompt, guidance_scale=5.0)

# Medium guidance - balanced (recommended)
result = await generate_image(prompt, guidance_scale=7.5)

# High guidance - very faithful to prompt, may oversaturate
result = await generate_image(prompt, guidance_scale=12.0)

Effects:

3-5: More artistic freedom, less literal interpretation.
7-10: Balanced, follows prompt closely - recommended.
12+: Very literal, may produce oversaturated or exaggerated images.

Negative prompts

Negative prompts tell the model what to avoid:

# Good negative prompts for photorealistic images
negative_prompt = "blurry, low quality, distorted, ugly, bad anatomy, watermark"

# Good negative prompts for artistic images
negative_prompt = "realistic, photograph, blurry, low quality"

# Good negative prompts for portraits
negative_prompt = "distorted face, bad anatomy, extra limbs, low quality"

Use negative prompts to:

Remove common artifacts (“distorted”, “low quality”).
Avoid unwanted styles (“cartoon”, “3D render”).
Fix common issues (“bad anatomy”, “extra fingers”).

Troubleshooting

Out of memory error

Issue: RuntimeError: CUDA out of memory. Cause: SDXL requires significant VRAM (16GB minimum). Solutions:

Verify you’re using 24GB GPUs:

gpu=[GpuGroup.ADA_24, GpuGroup.AMPERE_24]  # 24GB GPUs

Use half-precision (already in the example):

torch_dtype=torch.float16  # Half precision

If still failing, use 48GB GPUs:

gpu=GpuGroup.AMPERE_48  # A40/A6000 with 48GB

Model download fails

Issue: Error: Failed to download model from Hugging Face. Solutions:

Increase execution timeout for first run:

@Endpoint(
    name="image-generation",
    gpu=GpuGroup.ADA_24,
    execution_timeout_ms=600000  # 10 minutes for first download
)

Check Hugging Face Hub status at status.huggingface.co.
Check the worker logs for the endpoint in the Runpod console. Download errors from Hugging Face appear there.

Image quality is poor

Issue: Generated images look blurry or low quality. Solutions:

Increase inference steps:

num_steps=40  # More steps = better quality

Adjust guidance scale:
guidance_scale=8.5 # Higher guidance

Improve your prompt:

prompt = "A detailed portrait, highly detailed, sharp focus, 8k, professional photography"

Add quality keywords to your prompt:
- “highly detailed”
- “sharp focus”
- “8k”
- “photorealistic”
- “professional”

Slow generation

Issue: Every request takes much longer than 10 seconds. Check model_cached in the result. If it’s False on most requests, workers are loading the model again:

Make sure _pipeline is a module-level variable and generate_image declares global _pipeline. A pipeline created as a local variable is loaded again on every request.

Increase idle_timeout so workers stay up between requests:

idle_timeout=1800  # Keep workers warm for 30 minutes

Set workers=(1, 2) to keep one worker running at all times. You pay for that worker while it’s idle.

If model_cached is True and generation is still slow, reduce num_steps.

First run fails after 90 seconds

Issue: The first run fails with one of these errors:

RuntimeError: request to endpoint 'image-generation' timed out after 90s. the endpoint may not be deployed or the worker is still starting. deploy with 'flash deploy' or increase timeout with FLASH_SENTINEL_TIMEOUT env var.

KeyError: 'image_base64'

Cause: runpod-flash 1.21.0 waits up to 90 seconds for a result. The first request on a new worker can take longer: the worker may wait for a free GPU, then it starts and loads the model. The endpoint is deployed, and the request keeps running after the error. Solution: Run the script again. The worker keeps starting after the error, so the next run is faster. Raising FLASH_SENTINEL_TIMEOUT above 90 doesn’t help in 1.21.0: the request returns at 90 seconds with the job still running, and the script fails with the KeyError instead. To see whether a worker is up, check the endpoint’s health with its ID from flash deploy. curl reads your API key from the RUNPOD_API_KEY environment variable, which flash login doesn’t set, so export it first:

export RUNPOD_API_KEY="your_key"
curl https://api.runpod.ai/v2/ENDPOINT_ID/health \
  -H "Authorization: Bearer $RUNPOD_API_KEY"

A non-zero workers.throttled means the worker is waiting for a GPU. A non-zero workers.idle, workers.ready, or workers.running means a worker is up.

Build runs out of disk space

Issue: flash deploy fails with No space left on device or Disk quota exceeded while installing dependencies. Cause: A dependency that requires torch, such as accelerate, makes the local build download torch and several GB of CUDA libraries on Linux. Solution: Remove that dependency, or exclude it from the build:

flash deploy --exclude accelerate

See flash deploy for --exclude and --no-deps.

Endpoint defined in multiple files

Issue: flash deploy fails with endpoint 'image-generation' is defined in multiple files. Cause: Another .py file in the project directory imports generate_image. Flash scans every file and counts the import as a second definition. Solution: Keep the endpoint function and the code that calls it in one file, or move the extra script out of the project directory.

Images look distorted or have artifacts

Issue: Generated images have weird artifacts or distortions. Solutions:

Use negative prompts:

negative_prompt="distorted, ugly, bad anatomy, extra limbs, disfigured"

Adjust guidance scale (try 7-9 range):
guidance_scale=8.0
Increase inference steps for better refinement:
num_steps=35

Next steps

Now that you’ve built an image generation script with Flash, you can:

Try other Stable Diffusion models

Explore different models from Hugging Face: SDXL Turbo uses the same pipeline and generates an image in 1-4 steps at 512x512. Change MODEL_ID at the top of the file:

MODEL_ID = "stabilityai/sdxl-turbo"

Run flash deploy again so the workers pick up the new model. Then call it with few steps and no guidance in main():

result = await generate_image(
    prompt="A cat in a spacesuit, digital art",
    num_steps=1,
    guidance_scale=0.0,
)

Models outside the SDXL family, such as Stable Diffusion 1.5, need a different pipeline class. Replace StableDiffusionXLPipeline with AutoPipelineForText2Image, which picks the right class for the model, and redeploy.

Add image-to-image generation

Use an existing image as a starting point:

from diffusers import StableDiffusionXLImg2ImgPipeline

# Load img2img pipeline
pipe = StableDiffusionXLImg2ImgPipeline.from_pretrained(...)

# Generate variations of an existing image
image = pipe(prompt, image=init_image, strength=0.75).images[0]

Build a Flash app

Convert your script to a production Flash app:

flash init image-generation-app
cd image-generation-app
# Move generate_image into gpu_worker.py
# Add HTTP routes in lb_worker.py
flash deploy

flash init creates gpu_worker.py, cpu_worker.py, and lb_worker.py at the project root. See Build Flash apps for how they fit together.

Optimize with network volumes

Each new worker downloads the 7 GB of SDXL weights again. A network volume keeps one copy that every worker reads, so new workers skip the download. Point the Hugging Face cache at the volume with HF_HOME:

from runpod_flash import Endpoint, GpuGroup, NetworkVolume

vol = NetworkVolume(name="model-cache")  # Finds an existing volume or creates one

@Endpoint(
    name="image-generation",
    gpu=[GpuGroup.ADA_24, GpuGroup.AMPERE_24],
    volume=vol,
    env={"HF_HOME": "/runpod-volume/huggingface"},
    dependencies=["diffusers", "torch", "transformers"],
)
def generate_image(prompt, negative_prompt="", num_steps=30, guidance_scale=7.5, seed=None):
    ...

The volume is mounted at /runpod-volume on every worker. A network volume lives in one data center, so workers only run there.

Explore advanced features

LoRA fine-tuning: Customize SDXL for specific styles.
ControlNet: Guide generation with edge maps, depth, or pose.
Inpainting: Edit specific parts of images.
Upscaling: Generate higher resolution images.

Introduction

Serverless

Flash

Pods

Public Endpoints

Generate images with Flash and SDXL

Requirements

What you’ll build

Step 1: Set up your project

Step 2: Understand Stable Diffusion XL

Step 3: Create your project file

Step 4: Add imports and configuration

Step 5: Define the image generation function

Step 6: Add the main function and image saving

Complete file

Step 7: Deploy and run your first generation

Step 8: Generate several images in parallel

Understanding generation parameters

Number of inference steps

Guidance scale

Negative prompts

Troubleshooting

Out of memory error

Model download fails

Image quality is poor

Slow generation

First run fails after 90 seconds

Build runs out of disk space

Endpoint defined in multiple files

Images look distorted or have artifacts

Next steps

Try other Stable Diffusion models

Add image-to-image generation

Build a Flash app

Optimize with network volumes

Explore advanced features

​Requirements

​What you’ll build

​Step 1: Set up your project

​Step 2: Understand Stable Diffusion XL

​Step 3: Create your project file

​Step 4: Add imports and configuration

​Step 5: Define the image generation function

​Step 6: Add the main function and image saving

​Complete file

​Step 7: Deploy and run your first generation

​Step 8: Generate several images in parallel

​Understanding generation parameters

​Number of inference steps

​Guidance scale

​Negative prompts

​Troubleshooting

​Out of memory error

​Model download fails

​Image quality is poor

​Slow generation

​First run fails after 90 seconds

​Build runs out of disk space

​Endpoint defined in multiple files

​Images look distorted or have artifacts

​Next steps

​Try other Stable Diffusion models

​Add image-to-image generation

​Build a Flash app

​Optimize with network volumes

​Explore advanced features

​Related resources

Requirements

What you’ll build

Step 1: Set up your project

Step 2: Understand Stable Diffusion XL

Step 3: Create your project file

Step 4: Add imports and configuration

Step 5: Define the image generation function

Step 6: Add the main function and image saving

Complete file

Step 7: Deploy and run your first generation

Step 8: Generate several images in parallel

Understanding generation parameters

Number of inference steps

Guidance scale

Negative prompts

Troubleshooting

Out of memory error

Model download fails

Image quality is poor

Slow generation

First run fails after 90 seconds

Build runs out of disk space

Endpoint defined in multiple files

Images look distorted or have artifacts

Next steps

Try other Stable Diffusion models

Add image-to-image generation

Build a Flash app

Optimize with network volumes

Explore advanced features

Related resources