Flash - Image Generation Example

Demo repo for deploying AI image generation endpoints with Runpod Flash. Built for AI Engineer Europe 2026.

What This Does

1. image_generation.py -- Defines a Flash endpoint that runs DreamShaper 8 (Stable Diffusion 1.5) on serverless GPUs. A Flash endpoint is just a decorated Python function.

2. pipeline.py -- Full demo pipeline that chains multiple Runpod public endpoints together:

   • Qwen3 32B generates optimized scene prompts from free-form input (e.g. "Weekend in Paris")
   • Your Flash endpoint generates images in parallel on GPU
   • (Optional) Nano Banana 2 composes reference photos into the generated scenes
   • Builds an HTML gallery and opens it in the browser

Quick Start

# Install dependencies
uv sync

# Set your API key
export RUNPOD_API_KEY="your-key-here"

# Optional: HuggingFace token for gated models
export HF_TOKEN="your-hf-token"

Step 1: Run the Flash dev server

uv run flash run

This starts a local development server at http://localhost:8888 with hot reload. Edit image_generation.py and the server reloads automatically -- try switching between SDXL Turbo and DreamShaper 8 to see the difference live.

Step 2: Send requests to the endpoint

With the dev server running, use run_endpoint.py to send requests:

uv run run_endpoint.py --url http://localhost:8888/image_generation/runsync \
  --prompt "a cat astronaut"

Images are decoded from base64 and saved to output_images/.

Step 3: Run the full pipeline

Once the endpoint is working, run the full pipeline that builds a prompt-to-gallery workflow around it:

# Default: generates 8 images of Paris scenes
uv run pipeline.py

# Custom prompt
uv run pipeline.py "Autumn in Tokyo, ukiyo-e woodblock print style"

# Quick test: 1 image only
uv run pipeline.py "Rainy day in Seattle" -t

# Limit to N images
uv run pipeline.py "Streets of Rome" -n 3

# With reference photo composition (requires AWS + S3)
uv run pipeline.py "Weekend in London" --compose

The pipeline sends requests to public Runpod endpoints (Qwen3 32B for prompt generation, your Flash endpoint for images). Results are saved to output/images/ and an HTML gallery opens in the browser.

--compose is optional. It uploads generated images to S3 and sends them to Nano Banana 2 to composite your reference photos into the scenes. Requires:

• AWS credentials (aws sso login)
• S3_BUCKET env var (or set a default in upload.py)
• REFERENCE_URLS env var (comma-separated S3 URLs of your reference photos)

Step 4: Deploy to serverless GPUs

Once you're happy with the endpoint:

uv run flash deploy

This builds and deploys to Runpod's serverless infrastructure with autoscaling.

run_endpoint.py -- Endpoint Utility

Standalone utility for sending requests to any Runpod endpoint. Handles job submission, polling, and base64 image decoding/saving. Works with both local dev servers and deployed endpoints.

# Local dev server (sync)
uv run run_endpoint.py --url http://localhost:8888/image_generation/runsync \
  --prompt "a dragon in a forest"

# Deployed Runpod endpoint (async: submit + poll)
uv run run_endpoint.py <endpoint-id> --prompt "a dragon in a forest"

# Custom parameters
uv run run_endpoint.py <endpoint-id> \
  --prompt "mountain landscape at sunset" \
  --size 1024 \
  --steps 25 \
  --guidance-scale 7.5 \
  --num-images 3

Demo Outline

1. Show image_generation.py -- a Flash endpoint is just a decorated Python function with SDXL Turbo
2. uv run flash run -- start the local dev server
3. Send a request with uv run run_endpoint.py --url http://localhost:8888/image_generation/runsync
4. Edit the model (swap SDXL Turbo for DreamShaper 8) -- server hot reloads
5. Send another request, compare the output
6. uv run pipeline.py "Weekend in London" -- full chain: LLM prompt generation -> parallel image generation -> gallery
7. Show --compose to demo Nano Banana 2 compositing reference photos into scenes
8. uv run flash deploy -- deploy to serverless GPUs

Project Structure

image_generation.py   # Flash endpoint definition (DreamShaper 8)
pipeline.py           # Full pipeline: prompts -> images -> (compose) -> gallery
generate_single.py    # Single image generation + optional compose
prompts.py            # Qwen3 32B prompt generation + fallbacks
compose.py            # Nano Banana 2 image composition
gallery.py            # HTML gallery generator
helpers.py            # Shared constants and utilities
upload.py             # S3 upload for reference photos
run_endpoint.py       # Standalone endpoint request utility

Environment Variables

Variable	Required	Description
RUNPOD_API_KEY	Yes	Runpod API key for endpoint access
HF_TOKEN	No	HuggingFace token for gated models
S3_BUCKET	Only with --compose	S3 bucket for image uploads
S3_REGION	No	S3 region (default: us-east-1)
REFERENCE_URLS	Only with --compose	Comma-separated S3 URLs of reference photos