Download the PHP package madebybramble/craft-openai-alt-generator without Composer

OpenAI Alternative Text Generator for Craft CMS

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)

1. 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
2. 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

1. Install via Composer

2. 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

1. Go to Dashboard
2. Click + New Widget
3. Select Alternative Text Status
4. 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:

Then in settings, use:

• API Key: $OPENAI_API_KEY

📞 Support & Resources

Getting Help

• Documentation: This README file
• Issues: GitHub Issues
• Email Support: [email protected]

Useful Resources

• OpenAI API Documentation
• WCAG Guidelines
• Craft CMS Documentation

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:

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

Made with ❤️ by Made By Bramble