Skip to main content

Knowledge > Runbooks > Content Ops > Add or Update Illustration Images

Add or Update Illustration Images

Source, optimize, and attach cover images to sermon illustrations on ITW. Images improve engagement and SEO on illustration detail pages.

Prerequisites​

  • Unsplash API access ($UNSPLASH_ACCESS_KEY env var) — for sourcing free-use images
  • Supabase Storage access (for image hosting)
  • Image editing tool capable of resizing (ImageMagick, Sharp, or similar)
  • Illustration IDs for the records to be updated

Image Specifications​

PropertyValue
FormatJPEG (preferred) or WebP
Dimensions1200 × 675px (16:9 ratio)
File sizeUnder 300KB after optimization
ContentThematic/abstract — avoid stock photo clichés
LicenseUnsplash license (free for commercial use) or explicitly licensed

Steps​

Source an Image from Unsplash​

  1. Search Unsplash for a relevant image using the API:

    curl "https://api.unsplash.com/search/photos?query=[theme]&orientation=landscape&per_page=10" \
      -H "Authorization: Client-ID $UNSPLASH_ACCESS_KEY" \
      | jq '.results[] | {id: .id, description: .description, url: .urls.regular}'

    Replace [theme] with a relevant keyword (e.g., "forgiveness light", "prayer mountain", "community church").

  2. Download the selected image at the appropriate resolution:

    curl "[image_url]?w=1200&h=675&fit=crop&q=85" -o illustration-[id].jpg

  3. Verify license compliance — Unsplash images are free for commercial use without attribution (recommended but not required). Document the Unsplash photo ID in case of dispute.

Optimize the Image​

  1. Compress to under 300KB using ImageMagick or Sharp: 
    # Using ImageMagick
    convert illustration-[id].jpg -resize 1200x675 -quality 82 illustration-[id]-opt.jpg
    ls -lh illustration-[id]-opt.jpg  # confirm file size

Upload to Supabase Storage​

  1. Upload the optimized image to the ITW illustrations storage bucket:

    # Using Supabase CLI or direct API
    # The bucket is typically named 'illustrations' or 'itw-images'
    # Check the bucket name in the Supabase dashboard or via MCP

    Via Supabase MCP or the REST API:

    POST /storage/v1/object/illustrations/[illustration-uuid].jpg

  2. Get the public URL of the uploaded image:

    https://wrwkszmobuhvcfjipasi.supabase.co/storage/v1/object/public/illustrations/[illustration-uuid].jpg

Attach the Image to the Illustration​

  1. UPDATE the unified_rag_content record with the image URL:

    UPDATE unified_rag_content
    SET image_url = 'https://wrwkszmobuhvcfjipasi.supabase.co/storage/v1/object/public/illustrations/[illustration-uuid].jpg',
        updated_at = now()
    WHERE id = '[illustration-uuid]'
      AND category = 'illustration';

  2. Verify the image field is set:

    SELECT id, title, image_url FROM unified_rag_content WHERE id = '[illustration-uuid]';

  3. Confirm the image renders on ITW by visiting the illustration detail page:

    https://illustratetheword.com/illustrations/[slug]

Batch Image Assignment​

For adding images to many illustrations at once, use the image assignment script:

cd /c/dev/sermon-illustrations
unset CLAUDE_CODE_ENTRYPOINT
unset CLAUDECODE
node scripts/assign-images.js --topic "forgiveness" --limit 20

This script searches Unsplash, downloads, optimizes, uploads, and updates image_url in a single pass.

Verification​

  • unified_rag_content.image_url is populated for the target illustration.
  • Image loads correctly on the ITW illustration detail page.
  • No 404 errors for the image URL.
  • Image dimensions and file size meet specifications.

See Also​