Show HN: Auto-optimize and upload images with AI alt text

2 days ago 2

Created by Cagri Sarigoz | Open Source | MIT License

A comprehensive tool for downloading, optimizing, and uploading images to AWS S3 with CloudFront distribution. Features automatic image optimization, format conversion, unique URL generation, and AI-powered alt text generation for accessibility and SEO.

Batch Image Processing: Download images from URLs and upload to S3/CloudFront
Image Optimization: Automatic resizing, quality adjustment, and format conversion
Smart Format Selection: Automatically chooses the best format (JPEG, PNG, WebP) for optimal file size
Unique URLs: Adds timestamps to prevent filename conflicts and ensure cache busting
AI Alt Text Generation: Generate descriptive alt text using AltText.ai API
REST API: HTTP endpoints for programmatic access
Interactive CLI: User-friendly command-line interface
Comprehensive Logging: Detailed progress tracking and error reporting

Python 3.9+ (Recommended: Python 3.13 for best performance)
AWS account with S3 and CloudFront access
AltText.ai API key (optional, for alt text generation)

Recommended Setup with Python 3.13 Virtual Environment

For the best and most consistent experience, we recommend using Python 3.13 with a virtual environment:

macOS (using Homebrew):

Ubuntu/Debian:

sudo apt update sudo apt install python3.13 python3.13-venv python3.13-pip

Windows: Download from python.org or use Windows Store.

Verify installation:

python3.13 --version # Should output: Python 3.13.x

2. Create and Activate Virtual Environment

Create virtual environment:

# Clone the repository first git clone https://github.com/cagrisarigoz/image-optimization.git cd image-optimization # Create virtual environment with Python 3.13 python3.13 -m venv venv # Alternative if python3.13 is your default python python -m venv venv

Activate virtual environment:

Linux/macOS:

Windows (Command Prompt):

Windows (PowerShell):

venv\Scripts\Activate.ps1

Verify activation:

which python # Should point to venv/bin/python python --version # Should show Python 3.13.x

# Upgrade pip to latest version python -m pip install --upgrade pip # Install project dependencies pip install -r requirements.txt

# Copy environment template cp env.example .env # Edit .env with your credentials (use your preferred editor) nano .env # or vim .env, code .env, etc.

Quick Start (Alternative Method)

If you prefer a simpler setup or already have Python 3.9+ installed:

Clone the repository:

git clone https://github.com/cagrisarigoz/image-optimization.git cd image-optimization
Install dependencies:

pip install -r requirements.txt
Run setup:
Configure environment:

cp env.example .env # Edit .env with your credentials

Virtual Environment Benefits

Using a virtual environment provides several advantages:

Isolation: Dependencies don't conflict with system packages
Reproducibility: Consistent environment across different machines
Version Control: Lock specific package versions
Clean Uninstall: Easy to remove by deleting the venv folder
Multiple Projects: Different Python versions for different projects

Deactivating Virtual Environment

When you're done working on the project:

Python 3.9+ (Tested on 3.9, 3.10, 3.11, 3.12, 3.13)
AWS account with S3 and CloudFront access
AltText.ai API key (optional, for alt text generation)

Interactive CSV Processing

from upload_files import download_and_upload_from_csv # Process images with alt text generation download_and_upload_from_csv( generate_alt_text=True, alt_text_keywords="product, ecommerce, lifestyle" )

# Start the API server export FLASK_RUN=1 python upload_files.py # Upload a file curl -X POST -F "[email protected]" http://localhost:5000/upload

Create a .env file with your configuration:

# AWS Configuration (Required) AWS_ACCESS_KEY=your_aws_access_key AWS_SECRET_KEY=your_aws_secret_key S3_BUCKET=your_s3_bucket_name CLOUDFRONT_DOMAIN=your_cloudfront_domain # AltText.ai Configuration (Optional) ALTTEXT_AI_API_KEY=your_alttext_ai_api_key ALTTEXT_AI_KEYWORDS=default,keywords,for,seo ALTTEXT_AI_WEBHOOK_URL=your_webhook_url

Create data/input/images_to_download_and_upload.csv:

URL https://example.com/image1.jpg https://example.com/image2.png https://example.com/image3.webp

# Interactive mode with prompts ./process_csv.sh # Follow the prompts to configure: # - Alt text generation (Y/N) # - Keywords for SEO # - Image optimization settings # - Quality and format options

# Set environment variables for automation export PROCESS_CSV=1 export GENERATE_ALT_TEXT=true export ALT_TEXT_KEYWORDS="product, lifestyle, modern" export MAX_WIDTH=1200 export QUALITY=85 export SMART_FORMAT=true python upload_files.py

from upload_files import upload_files # Upload local files with optimization upload_files( max_width=800, quality=82, smart_format=True, generate_alt_text=True )

# Start the server export FLASK_RUN=1 python upload_files.py & # Upload single file curl -X POST -F "[email protected]" http://localhost:5000/upload # List uploaded files curl http://localhost:5000/files # Process CSV via API curl http://localhost:5000/process-csv

Automatic descriptions: Generate descriptive alt text for accessibility
SEO optimization: Include custom keywords for better search rankings
Batch processing: Generate alt text for multiple images efficiently
Fallback handling: Graceful degradation when API is unavailable

# Enable alt text generation ALTTEXT_AI_API_KEY=your_api_key ALTTEXT_AI_KEYWORDS=product,ecommerce,lifestyle,modern # Optional webhook for async processing ALTTEXT_AI_WEBHOOK_URL=https://your-domain.com/webhook

from alttext_ai import generate_alt_text # Generate alt text for an image alt_text = generate_alt_text( image_url="https://example.com/image.jpg", keywords="product, modern, lifestyle" ) print(f"Generated alt text: {alt_text}")

The tool generates several output files in the data/output/ directory:

data/output/images_mapping.csv

Maps original URLs to optimized CloudFront URLs with alt text:

source_url,cloudfront_url,max_width,quality,smart_format,alt_text https://example.com/image1.jpg,https://cdn.example.com/image_123.webp,800,85,True,"Modern lifestyle product photo"

data/output/uploaded_files.json

Tracks upload status and metadata:

{ "image_123.webp": { "original_url": "https://example.com/image1.jpg", "cloudfront_url": "https://cdn.example.com/image_123.webp", "alt_text": "Modern lifestyle product photo", "upload_time": "2025-01-20T10:30:00Z" } }

data/output/local_files_alt_text.csv

Alt text for local files:

filename,alt_text photo1.jpg,"Beautiful sunset over mountains" product2.png,"Modern smartphone with sleek design"

Image Optimization Settings

# Customize optimization parameters optimize_image( image_path="photo.jpg", max_width=1200, # Maximum width in pixels quality=85, # JPEG/WebP quality (1-100) smart_format=True # Auto-select best format )

The tool automatically selects the best format:

JPEG: For photos with many colors
PNG: For images with transparency or few colors
WebP: For modern browsers (best compression)

90-100: Highest quality, larger files
80-89: High quality, good for most use cases
70-79: Good quality, smaller files
60-69: Acceptable quality, much smaller files

Upload and optimize a single file.

Request:

curl -X POST -F "[email protected]" \ -F "max_width=800" \ -F "quality=85" \ http://localhost:5000/upload

Response:

{ "success": true, "cloudfront_url": "https://cdn.example.com/image_123.webp", "alt_text": "Generated alt text description", "original_size": "150KB", "optimized_size": "45KB", "format": "webp" }

List all uploaded files.

Response:

{ "files": [ { "filename": "image_123.webp", "cloudfront_url": "https://cdn.example.com/image_123.webp", "upload_time": "2025-01-20T10:30:00Z" } ] }

Process images from CSV file.

Response:

{ "success": true, "processed": 5, "failed": 0, "output_file": "data/output/images_mapping.csv" }

image-optimization/ ├── Core Application Files │ ├── upload_files.py # Main application & Flask API │ ├── alttext_ai.py # AltText.ai API integration │ ├── setup.py # Setup & dependency checker │ ├── process_csv.sh # Interactive batch processor │ └── requirements.txt # Python dependencies ├── Configuration │ ├── .env # Environment variables (gitignored) │ ├── env.example # Environment template │ └── .gitignore # Git exclusions ├── Data Files │ ├── data/ │ │ ├── input/ # Input CSV files │ │ ├── output/ # Generated output files │ │ ├── examples/ # Example files for reference │ │ └── local_images/ # Downloaded/local image files ├── Utilities │ ├── check_s3_objects.py # S3 debugging utility │ └── regenerate_urls.py # URL mapping regeneration └── Documentation & CI/CD ├── README.md # Complete documentation ├── CONTRIBUTING.md # Contribution guidelines ├── PROJECT_RULES.md # Project rules and standards └── .github/ # GitHub workflows & templates

# Test core functionality python upload_files.py # Test AltText.ai integration python alttext_ai.py # Test CSV processing ./process_csv.sh # Test API endpoints export FLASK_RUN=1 python upload_files.py & curl -X POST -F "[email protected]" http://localhost:5000/upload

# Error: Python version not supported # Solution: Upgrade to Python 3.9+ python --version # Check current version # Install Python 3.13 (recommended) # See installation instructions above

Virtual Environment Issues

# Error: Command not found after activation # Solution: Ensure virtual environment is activated source venv/bin/activate # Linux/macOS # or venv\Scripts\activate # Windows # Verify activation which python # Should point to venv directory

# Error: AWS credentials not found # Solution: Check your .env file AWS_ACCESS_KEY=your_key_here AWS_SECRET_KEY=your_secret_here

# Error: AltText.ai connection failed # Solution: Verify your API key python -c "from alttext_ai import test_alttext_ai_connection; test_alttext_ai_connection()"

# Error: PIL/Pillow issues # Solution: Reinstall Pillow pip uninstall Pillow pip install Pillow

# Error: process_csv.sh permission denied # Solution: Make script executable chmod +x process_csv.sh

Enable verbose logging:

export DEBUG=1 python upload_files.py