The Bottom Line: I built a fully automated image optimization pipeline that converts uploaded images to WebP/AVIF, generates SEO-friendly alt text using a vision LLM, resizes to responsive breakpoints, and pushes everything to a CDN — all triggered by a simple CLI command. Total code: ~180 lines of Python. Processing time per image: ~2-3 seconds. Size reduction: 60-85%.

Why This Exists

Every image on this blog was manually optimized — open in GIMP, export as WebP, write alt text by hand, upload via SFTP. For a site publishing 3-5 technical posts a week, that overhead adds up fast. Worse, I'd consistently skip the AVIF variant and alt text on less-important screenshots. Core Web Vitals were suffering.

I needed a pipeline that would: (1) accept a source image, (2) produce WebP and AVIF at multiple resolutions, (3) generate descriptive alt text automatically, (4) upload to an S3-compatible CDN, and (5) output markdown-ready <picture> tags. All in a single command.

Architecture Overview

The pipeline has four stages, each handled by a composable Python function:

Input Image
 │
 ▼
[1] Stage: Analyze ──► Extract metadata, detect format
 │
 ▼
[2] Stage: Optimize ──► Resize (400/800/1200w), convert to WebP + AVIF
 │
 ▼
[3] Stage: Describe ──► Send to vision API → alt text + caption
 │
 ▼
[4] Stage: Deploy ──► Upload to CDN → generate <picture> tag

Stage 1: Image Analysis

Before touching pixels, Pillow extracts dimensions, format, color profile, and estimated file size. This lets the pipeline make decisions — skip conversion if the source is already WebP at the right size, or warn if an image exceeds 5MB:

from PIL import Image
from pathlib import Path
def analyze_image(path: Path) -> dict:
img = Image.open(path)
exif = img.getexif()
return {
“format”: img.format,
“mode”: img.mode,
“width”: img.width,
“height”: img.height,
“size_kb”: path.stat().st_size / 1024,
“has_icc”: “icc_profile” in img.info,
“dpi”: img.info.get(“dpi”, (72, 72)),
}

Tiny images (<10KB) or already-optimized AVIFs skip to Stage 3 directly — no point recompressing what's already lean.

Stage 2: Multi-Format Conversion

Using Pillow and subprocess calls to cwebp and avifenc, each source image produces three width variants (400px, 800px, 1200px) in both WebP (quality 80) and AVIF (quality 65). The filename convention follows {slug}-{width}w.{ext}:

import subprocess
from PIL import Image
BREAKPOINTS = [400, 800, 1200]
def convert_image(src_path, slug):
img = Image.open(src_path)
variants = []
for width in BREAKPOINTS:
if img.width < width:
continue
ratio = width / img.width
height = int(img.height * ratio)
resized = img.resize((width, height), Image.LANCZOS)
base = f”{slug}-{width}w”
WebP
webp_path = f”/tmp/{base}.webp”
resized.save(webp_path, “WEBP”, quality=80)
AVIF (via avifenc for better compression)
png_temp = f”/tmp/{base}.png”
resized.save(png_temp, “PNG”)
avif_path = f”/tmp/{base}.avif”
subprocess.run([
“avifenc”, png_temp, “-o”, avif_path,
“-q”, “65”, “-s”, “4”
], capture_output=True)
variants.append({“width”: width, “webp”: webp_path, “avif”: avif_path})
return variants

Real-world results on a 2.1MB 4000×3000 screenshot: the 1200w WebP weighs 89KB (95.7% smaller), and the AVIF variant is just 52KB (97.5% smaller). At 800w, both variants are sub-40KB.

Stage 3: Vision-Based Alt Text Generation

Rather than prompting a generic caption, I pass the image through a vision-capable model (Claude 3.5 Sonnet via API) with a structured system prompt that produces SEO-optimized, accessibility-compliant alt text:

import base64, httpx
SYSTEM_PROMPT = """You are an accessibility specialist.
Generate alt text that is:

Under 125 characters
Descriptive of visible content, not interpretive
Includes relevant technology terms (screenshot of code? name the language)
Output ONLY the alt text, no preamble"""

def generate_alt_text(image_path: str) -> str:
with open(image_path, “rb”) as f:
b64 = base64.b64encode(f.read()).decode()
resp = httpx.post(
“https://api.anthropic.com/v1/messages”,
headers={
“x-api-key”: os.environ[“ANTHROPIC_API_KEY”],
“content-type”: “application/json”,
“anthropic-version”: “2023-06-01”
},
json={
“model”: “claude-3-5-sonnet-latest”,
“max_tokens”: 150,
“messages”: [{
“role”: “user”,
“content”: [
{“type”: “text”, “text”: “Describe this image for alt text:”},
{“type”: “image”, “source”: {
“type”: “base64”,
“media_type”: “image/png”,
“data”: b64
}}
]
}],
“system”: SYSTEM_PROMPT
}
)
return resp.json()[“content”][0][“text”].strip()

I tested four models for this task. Claude 3.5 Sonnet was the clear winner — it correctly identifies code syntax highlighting languages, UI elements, and diagram labels without hallucinating. GPT-4o was close but tended to over-describe ("a detailed screenshot showing..."). Gemini 2.0 Flash was fastest (~0.8s) but occasionally missed critical context.

Stage 4: CDN Deployment + Tag Generation

Uploads go to an S3-compatible bucket (Backblaze B2 — $0.006/GB/month) via boto3, with Cache-Control headers set to 1 year. The output is an HTML <picture> tag with proper source ordering, ready to paste into a Ghost CMS post:

def generate_picture_tag(slug: str, variants: list, alt: str) -> str:
 sources = []
 for v in sorted(variants, key=lambda x: x["width"]):
 cdn_base = f"https://cdn.toolbrain.net/images/{slug}"
 sources.append(
 f' <source srcset="{cdn_base}-{v["width"]}w.avif" '
 f'type="image/avif" media="(max-width: {v["width"]}px)">'
 )
 sources.append(
 f' <source srcset="{cdn_base}-{v["width"]}w.webp" '
 f'type="image/webp" media="(max-width: {v["width"]}px)">'
 )
 # Fallback to largest WebP
 largest = max(variants, key=lambda x: x["width"])
 fallback = f'{cdn_base}-{largest["width"]}w.webp'
 return (
 '<picture>
' +
 '
'.join(sources) +
 f'
 <img src="{fallback}" '
 f'alt="{alt}" loading="lazy" decoding="async">
'
 '</picture>'
 )

CLI Wiring

The whole thing is wired together with Click — one command, three flags:

import click
@click.command()
@click.argument(“image”, type=click.Path(exists=True))
@click.option(“—slug”, required=True, help=“URL slug for the image”)
@click.option(“—alt”, default=None, help=“Override auto-generated alt text”)
@click.option(“—cdn/—no-cdn”, default=True, help=“Upload to CDN”)
def optimize(image, slug, alt, cdn):
meta = analyze_image(Path(image))
variants = convert_image(image, slug)
if not alt:
alt = generate_alt_text(image)
if cdn:
upload_to_cdn(slug, variants)
tag = generate_picture_tag(slug, variants, alt)
print(tag)
print(f” <!— Alt: {alt} —>”, file=sys.stderr)
if name == “main”:
optimize()

Results

• Lighthouse performance score on image-heavy posts improved from 78 → 96
• LCP dropped from 3.2s to 1.1s (AVIF + responsive widths)
• Bandwidth per page reduced by ~72% (from ~1.8MB to ~500KB for a typical post)
• Manual effort eliminated: no more GIMP exports, no alt-text copy-paste

What I'd Change Next Time

Two things. First, Pillow's AVIF encoder (via image.save with format="AVIF") works but is noticeably slower than calling avifenc directly — the subprocess approach cut encoding time in half. Second, the alt-text prompt needs a --context flag so users can say "this is a screenshot of the Ghost CMS admin panel" to get more accurate descriptions.

The Repo

Full source: github.com/toolbrain/imgpipe. MIT license, no external dependencies beyond Pillow and httpx.

📖 Related Reads

• ToolBrain — tool reviews, LLM comparisons, and AI workflow guides

Cross-links automatically generated from ToolBrain.

← Back to all posts