AI Image Alt Text
Generates alt text for image fields using AI vision models, supporting both manual and automatic generation with language-aware output.
ai_image_alt_text
Install
composer require 'drupal/ai_image_alt_text:^1.0'
Overview
The AI Image Alt Text module is part of the AI module ecosystem and enables automatic generation of accessibility-compliant alt text for image fields using AI vision models. The module integrates seamlessly with Drupal's image field widget, adding a "Generate with AI" button that allows content editors to generate descriptive alt text with a single click.
The module supports a human-in-the-loop workflow where generated alt text can be reviewed and edited before saving. It automatically detects the entity's language and generates alt text in the corresponding language, making it ideal for multilingual sites. The customizable prompt uses Twig templating for flexibility, and images can be preprocessed using image styles to optimize costs and compatibility with AI providers.
An optional submodule (AI Image Bulk Alt Text) provides a bulk interface for finding and fixing all images with missing alt text across the entire site, making it easy to improve accessibility compliance for existing content.
Features
- Generates descriptive alt text for image fields using AI vision models (OpenAI, Anthropic, Fireworks AI, etc.)
- Human-in-the-loop workflow with "Generate with AI" button on image field widgets for manual review before saving
- Automatic alt text generation on image upload with optional hidden button mode
- Language-aware generation that produces alt text in the entity's language for multilingual support
- Customizable AI prompt using Twig templating with tokens for entity language name and filename
- Configurable image style preprocessing to optimize image resolution and format before sending to AI (reduces costs)
- Support for selecting specific AI provider/model or using the default vision model
- Bulk alt text generation submodule for finding and fixing all images with missing alt text site-wide
Use Cases
Content editor workflow for new images
When a content editor uploads an image to an article, they see a 'Generate with AI' button next to the alt text field. Clicking it sends the image to the configured AI provider and populates the alt text field with a descriptive, accessibility-compliant description. The editor can review and modify the text before saving the content.
Automated alt text for high-volume sites
For sites with many images being uploaded, administrators can enable 'Autogenerate on upload' in settings. This automatically generates alt text when images are uploaded, optionally hiding the generation button. Editors only need to review the generated text.
Multilingual alt text generation
When editing content in different languages (e.g., German or French translations), the module automatically detects the entity's language and instructs the AI to generate alt text in that language, ensuring proper localization of accessibility content.
Bulk accessibility remediation
For existing sites with many images missing alt text, administrators can enable the AI Image Bulk Alt Text submodule, navigate to /admin/config/media/ai_image_bulk_alt_text, and use the 'Bulk Generate Alt Text with AI' button to generate suggestions for up to 50 images at once. They can review each suggestion, make edits, and save all changes together.
Custom prompt for brand consistency
Organizations with specific alt text guidelines can customize the AI prompt in settings to enforce brand voice, include specific terminology, or follow accessibility standards beyond the defaults. The Twig templating allows dynamic content like the image filename to be included in prompts.
Tips
- Use an image style (like the default 'AI Image Alt Text') to reduce image resolution before sending to AI - this significantly reduces API costs while maintaining good alt text quality
- Customize the default prompt to match your organization's accessibility guidelines or brand voice
- For multilingual sites, the module automatically generates alt text in the entity's language - ensure your AI provider supports the languages you need
- Review generated alt text before saving, as AI may occasionally misinterpret complex or ambiguous images
- The bulk generation submodule processes images sequentially to avoid overwhelming the AI provider - allow time for large batches
- Consider enabling autogenerate for user roles that frequently upload images but may forget to add alt text
Technical Details
Admin Pages 2
/admin/config/ai/ai_image_alt_text
Configure how alt text is generated for images using AI. This page allows you to customize the prompt sent to the AI, select image preprocessing options, choose which AI model to use, and configure automatic generation behavior.
/admin/config/media/ai_image_bulk_alt_text
Find and fix all images across the site that are missing alt text. Displays a table of up to 50 images without alt text, allowing you to generate alt text individually or in bulk, review the suggestions, and save changes.
Permissions 2
Hooks 1
hook_field_widget_single_element_form_alter
Modifies image field widgets to add the 'Generate with AI' button and attach necessary JavaScript. Only applies to ImageWidget instances with alt field enabled.
Troubleshooting 5
Verify the user has the 'Generate AI Alt Tags' permission, the alt field is enabled for the image field configuration, and a working AI provider with image vision capability is configured (either in AI Image Alt Text settings or as default in AI module).
Navigate to /admin/config/ai/ai_image_alt_text and select a specific AI provider/model, or configure a default 'Chat with Image Vision' provider in the AI module settings at /admin/config/ai.
Check that the selected AI provider supports image vision and is properly configured with valid API credentials. Some providers have size or format limitations; try using an image style to reduce resolution.
The module uses the entity's language for generation. Ensure the content is being edited in the correct language variant. The language is passed to the AI prompt via the {{ entity_lang_name }} token.
This means all image fields with alt text enabled across all content already have alt text populated. The page only shows images where the alt field is empty.
Security Notes 3
- Image files are sent to external AI providers for analysis - ensure this is acceptable for your content and privacy requirements
- The generation endpoint (/admin/config/ai/ai_image_alt_text/generate/{file}/{lang_code}) is protected by the 'generate ai alt tags' permission
- File access is verified before processing - users can only generate alt text for files they have permission to view