README

Automatically generate WCAG-compliant alternative text for your images using OpenAI's Vision API

Transform your website's accessibility with AI-powered alternative text generation. This plugin automatically creates descriptive, WCAG-compliant alt text for your images, making your content accessible to everyone while saving you countless hours of manual work.

🌟 Why This Plugin?

The Problem: Writing quality alternative text for images is time-consuming and often neglected, leading to poor website accessibility and potential legal issues.

The Solution: This plugin uses OpenAI's advanced Vision API to automatically generate professional-quality, WCAG-compliant alternative text that:

✅ Describes image content accurately and concisely
✅ Follows accessibility best practices
✅ Integrates seamlessly into your Craft CMS workflow
✅ Processes images automatically on upload or in bulk operations

🚀 Key Features

🤖 Automatic AI Generation

Generates alt text automatically when images are uploaded
Uses OpenAI's latest vision models (GPT-5, GPT-4o, etc.)
WCAG 2.1 AA compliant output
Smart content analysis and description

⚙️ Flexible Configuration

Configure settings per asset volume
Choose which field stores your alt text
Customize image resolution for analysis
Override system prompts for specific needs

📊 Bulk Operations

Generate Missing: Process only images without alt text
Replace ALL: Update all images with fresh alt text
Background processing with progress tracking
Volume-specific or site-wide operations

🎯 Smart Integration

Asset Manager toolbar buttons
Dashboard widget for status monitoring
Real-time statistics and completion tracking
Seamless Craft CMS integration

🔧 Advanced Controls

Multiple OpenAI model options
Configurable retry logic and timeouts
Environment variable support
Comprehensive error handling and logging

📋 Requirements

Craft CMS: Version 5.3.0 or higher
PHP: Version 8.1 or higher
OpenAI API Key: Required for all functionality
Internet Connection: For OpenAI API communication
Asset Volumes: At least one configured asset volume

🔧 Installation

Via Craft Plugin Store (Recommended)

Open the Plugin Store
- In your Craft CMS admin panel, go to Settings → Plugin Store
- Search for "OpenAI Alternative Text Generator"
- Click Install on the plugin
Install the Plugin
- Click Try for a free trial or Buy Now to purchase
- The plugin will be automatically downloaded and installed
- No additional configuration needed

Via Composer

Install via Composer

composer require madebybramble/craft-openai-alt-generator

Install in Craft CMS
- Go to Settings → Plugins
- Find "OpenAI Alternative Text Generator"
- Click Install

⚡ Quick Start Guide

1. Get Your OpenAI API Key

Visit OpenAI Platform
Create account or sign in
Navigate to API Keys section
Create a new API key and copy it

2. Configure the Plugin

Go to Settings → Plugins → OpenAI Alternative Text Generator
Enter your OpenAI API Key
Click Test Connection to verify setup
Choose your preferred image resolution (Medium recommended)

3. Set Up Volumes

In the Volume Configuration section
Enable auto-generation for desired volumes
Choose which field stores the alt text (usually "Title" or custom field)
View real-time statistics for each volume

4. Test the Setup

Upload a new image to a configured volume
Check that alt text is automatically generated
View the generated text in your chosen field

📖 Detailed Configuration

🔑 API Configuration

OpenAI API Key

Required: Yes
Format: Your OpenAI API key or environment variable ($OPENAI_API_KEY)
Security: Store in environment variables for production

Model Selection

Choose from available OpenAI vision models:

GPT-5 (Latest): Best quality, higher cost
GPT-4o: Excellent balance of speed and quality ⭐ Recommended
GPT-4o-mini: Faster and more economical
Other models: Additional options based on availability

🖼️ Image Processing Settings

Resolution Options

Low (512×512): Fastest, most economical, basic detail
Medium (768×768): Balanced performance and quality ⭐ Recommended
High (1024×1024): Best detail, higher cost and processing time

Custom System Prompt

Default: WCAG-compliant prompt for accessibility
Custom: Override for specific brand voice or requirements
Important: Maintain accessibility compliance when customizing

📁 Volume Configuration

Per-Volume Settings

Configure each asset volume independently:

Auto Generate: Enable/disable automatic generation on upload
Alt Text Field: Choose field to store generated text:
- Default fields (Title, etc.)
- Custom Plain Text fields
- Asset volume-specific fields

Field Requirements

Alt text fields must be:

Plain Text or Single-line Text field types
Attached to the asset volume
Accessible for editing by the plugin

🔧 Advanced Settings

Retry Configuration

Max Retries: 1-10 attempts for failed requests (default: 3)
API Timeout: 10-120 seconds per request (default: 30)

Performance Tuning

Higher retries = better reliability, slower failure detection
Longer timeouts = handle complex images, delayed error notification

🔄 Using Bulk Operations

From Settings Page

Generate Missing Alt Text

Processes only images without existing alt text
Safe operation - won't overwrite existing content
Background processing with progress notifications
Can be applied globally or per volume

Replace ALL Alt Text ⚠️

DESTRUCTIVE: Replaces all existing alt text
Requires double confirmation
Use when updating alt text standards
Creates audit log entries

From Asset Manager

Context-Aware Operations

Buttons appear in Asset Manager toolbar
Volume-specific: When viewing single volume
Global: When viewing all assets
Real-time status feedback

Mobile & Responsive

Full labels on desktop
Icon-only on tablets
Hidden on mobile phones to save space

📊 Dashboard Widget

Alternative Text Status Widget

Add to your dashboard for quick monitoring:

Volume Overview: See all volumes at a glance
Completion Percentages: Color-coded progress indicators
- 🟢 Green: 90%+ complete
- 🟡 Yellow: 50-89% complete
- 🔴 Red: Under 50% complete
Image Counts: Total, completed, and missing statistics
Configuration Status: Identify unconfigured volumes

Adding the Widget

Go to Dashboard
Click + New Widget
Select Alternative Text Status
Configure size and position

🎯 Best Practices

📝 Alt Text Quality

Generated text follows WCAG guidelines
Under 125 characters when possible
Focuses on image purpose and essential content
Avoids redundant phrases like "image of"

🔧 Configuration Tips

Start with Medium resolution for best balance
Enable auto-generation on frequently used volumes
Use custom Plain Text fields for better organization
Test with representative images before bulk operations

⚡ Performance Optimization

Process bulk operations during off-peak hours
Monitor API usage and costs
Use appropriate retry settings for your network
Enable only needed volumes to reduce processing

🔒 Security & Compliance

Store API keys in environment variables
Regularly rotate API keys
Monitor usage for unexpected costs
Maintain audit logs for compliance

🔍 Troubleshooting

Common Issues

"API Key Not Configured"

✅ Verify API key is entered correctly
✅ Check environment variable syntax if using
✅ Ensure API key has proper permissions
✅ Test connection in settings

"Connection Test Failed"

✅ Check internet connectivity
✅ Verify OpenAI service status
✅ Confirm API key validity
✅ Check firewall settings

"No Alt Text Generated"

✅ Verify volume is configured and enabled
✅ Check image is supported format (JPEG, PNG, etc.)
✅ Confirm field mapping is correct
✅ Review error logs for details

"Field Not Found" Errors

✅ Ensure target field exists on volume
✅ Verify field type is Plain Text compatible
✅ Check field handle spelling
✅ Confirm user permissions

Performance Issues

Slow Processing

Reduce image resolution setting
Decrease retry attempts
Check network connectivity
Monitor OpenAI API status

High Costs

Use lower resolution setting
Choose more economical models
Optimize bulk operation timing
Review usage patterns

📈 Understanding Statistics

Volume Statistics Display

Total Images: All images in volume
Has Alt Text: Images with existing alt text
Missing: Images needing alt text
Complete %: Completion percentage

🔐 Environment Variables

For production deployments, use environment variables:

# .env file
OPENAI_API_KEY=sk-your-api-key-here

Then in settings, use:

API Key: $OPENAI_API_KEY

📞 Support & Resources

Getting Help

Documentation: This README file
Issues: GitHub Issues
Email Support: support@madebybramble.co.uk

Useful Resources

Developer Info

Developer: Made By Bramble
Author: Phill Morgan
License: Proprietary

🎉 You're All Set!

Your Craft CMS site is now equipped with AI-powered alternative text generation. Your images will automatically become more accessible, improving user experience for everyone.

Next Steps:

Monitor the dashboard widget for completion progress
Run bulk operations on existing images
Customize settings based on your needs
Enjoy automatic alt text generation on new uploads!

Made with ❤️ by Made By Bramble

madebybramble / craft-openai-alt-generator

Maintainers

Details