Documentation
Everything you need to install, configure, and get the most out of Image Alt Text Pro WordPress Plugin.
Introduction
Image Alt Text Pro is a powerful WordPress plugin designed to help you add, update, and optimize alt text for all your images. It improves your website's SEO and accessibility through advanced features including AI-powered generation, bulk editing, SEO validation, and real-time missing alt text highlighting.
Why Alt Text Matters
Key Benefits
Getting Started
First Steps After Installation
Features Overview
Core Features
| # | Feature | Description |
|---|---|---|
| 1 | Image Management Dashboard | View all images with or without alt text. Data table with Title, Filename, Alt Text, SEO Score, Date columns. Thumbnail preview and full-size viewing. |
| 2 | 4 AI Generation Methods | Smart Auto-Fill (free, no API key), OpenAI GPT-4o, Google Gemini, Claude AI, Hugging Face, Azure Computer Vision. |
| 3 | Bulk Processing | Process multiple selected images. Actions include alt text and caption copy from title/filename, plus all AI providers. Real-time progress tracking. |
| 4 | One-Shot Actions | Process your entire media library with one click. No image selection needed — runs in server-side batches until complete. |
| 5 | SEO Validation | 100-point scoring system. Real-time validation feedback with actionable suggestions. Color-coded quality indicators. |
| 6 | Auto-Add on Upload | Automatically generate alt text for every new uploaded image. Choose from 8 methods. Set and forget. |
| 7 | Advanced Filtering | Filter images by date range. Quick presets (Today, Last 7 Days, etc.) plus custom range picker. Search across all image metadata. |
| 8 | Missing Alt Text Highlighter | Visual red-border overlay on your live site for images missing alt text. Admin-only, customizable color. |
Installation
The free version is available on the WordPress plugin directory. You can install it the same way — no license key required.
Licensing, Sites & WordPress Multisite
Managing Images
Image Table Views
Editing Alt Text on a Single Image
Row-Level Quick Actions
| Action | What it does |
|---|---|
| Copy Title | Copies the image's WordPress title to alt text instantly. Skips if alt text already matches the title. |
| Copy Filename | Uses the filename without extension. Skips if already matching. |
| Generate (AI) | Calls the configured AI provider for this single image. Shows result immediately in the editor for review before saving. |
Search & Pagination
Use the search box (top-right of table) to search by image title. Choose 10 / 25 / 50 / 100 rows per page from the dropdown at the bottom-left. Navigation controls are shown bottom-right.
OpenAI Setup
Setting Up OpenAI (GPT-4o Vision)
OpenAI's GPT-4o Vision model produces detailed, context-aware alt text descriptions. It is particularly effective for complex product images, lifestyle photography, and images where context matters. API usage is billed directly by OpenAI — approximately $0.002–$0.005 per image at standard usage.
How to get an API Key — Steps
Keep your API key private. Anyone with your key can make API calls charged to your account. Never share it publicly or commit it to version control.
Prompt customisation note
You can customise the prompt sent to OpenAI in Settings → OpenAI Settings → Custom Prompt. The default prompt is optimised for SEO-friendly alt text. Advanced users can tailor it for their specific image style or brand voice.
Google Gemini Setup
Setting Up Google Gemini Vision
Google Gemini Vision is a capable and cost-effective option. The free tier includes a generous number of requests per minute, making it suitable for medium-sized sites. Rate-limited requests are automatically retried by the plugin — no manual intervention needed.
How to get an API Key — Steps
Free tier limits: Gemini 1.5 Flash allows up to 15 requests per minute and 1,500 requests per day on the free tier. For larger sites, consider upgrading to a paid Google Cloud plan.
Claude AI (Anthropic) Setup
Setting Up Claude AI (Anthropic)
Anthropic's Claude Haiku Vision model is fast, accurate, and cost-efficient. It produces clear, descriptive alt text well-suited for e-commerce and editorial images. Overloaded API responses are retried automatically — the plugin will not silently skip images during busy periods.
How to get an API Key — Steps
Azure Computer Vision Setup
Setting Up Azure Computer Vision
Microsoft Azure Computer Vision generates accurate image captions using enterprise-grade computer vision. The free tier offers 5,000 calls per month — enough for most small to medium sites at zero cost. Azure requires both an API key and an endpoint URL.
How to get an API Key + Endpoint — Steps
Both fields are required. The plugin will not attempt Azure generation if either the key or endpoint is missing.
Free tier: 5,000 calls/month at no cost. Beyond that, pricing is approximately $1.00 per 1,000 calls on the standard tier.
Hugging Face Setup
Setting Up Hugging Face (Vision AI)
Hugging Face lets you run open-source vision language models (VLMs) through their Inference Providers platform. This is the most flexible option — you can choose from hundreds of supported models. The plugin defaults to Qwen/Qwen2.5-VL-7B-Instruct, but you can change this to any VLM available on your Hugging Face account. A paid Hugging Face plan is required.
Requirements before you start
Paid plan required. Hugging Face Inference Providers require a paid subscription with available credits. The old free BLIP captioning endpoint is no longer available.
How to get an API Token — Steps
Model cold start: If using a model for the first time it may take 20–30 seconds to warm up. The plugin will wait and retry automatically.
Bulk Actions
Bulk Actions let you process a selected group of images in one go. Use them when you want to update specific images rather than your entire library.
How to Use
- Alt Text group:
- Copy Title to Alt Text — uses the image’s WordPress title Free
- Copy Filename to Alt Text — uses the filename without extension Free
- Caption group:
- Copy Title to Caption — copies the WordPress title to the image caption field Free
- Copy Filename to Caption — copies the filename (no extension) to the image caption field Free
- AI group (only shown when the matching API key is configured):
- Generate by OpenAI Pro
- Generate by Google Gemini Pro
- Generate by Claude AI Pro
- Generate by Hugging Face Pro
- Generate by Azure Vision Pro
Images already with alt text are not overwritten. Alt text (or captions) that already match the source (title or filename) are skipped automatically.
One-Shot Actions
One-Shot Action processes your entire media library with a single click — no image selection needed. The plugin works through all images in batches automatically until every image is processed. Perfect for a first-time setup or a full library refresh.
How to Use
AI provider batch limit: AI-based one shot actions are capped at the batch size configured in Settings → AI Parameters → One Shot (default: 5 images). This prevents API timeouts and rate-limit errors.
Do not close or navigate away while a One-Shot operation is running. The process runs client-side and will stop if the page is closed.
Auto-Add Alt Text on Upload
Once enabled, every new image uploaded to WordPress automatically receives alt text — no manual action required. Choose your preferred method once and the plugin handles the rest for every future upload.
How to Setup
- Post Title — Uses the title of the post/page the image is uploaded to. Falls back to filename if no title is found.
- File Name — Uses the image filename (without extension). Works for all uploads regardless of context.
- OpenAI — Calls GPT-4o Vision on upload. Requires OpenAI API key.
- Google Gemini — Calls Gemini Vision on upload. Requires Gemini API key.
- Claude AI — Calls Claude Vision on upload. Requires Anthropic API key.
- Hugging Face — Calls Inference Providers on upload. Requires HF API token with Inference permission.
- Azure Computer Vision — Calls Azure on upload. Requires Azure API key and endpoint.
Images that already have alt text are never overwritten by Auto-Add. Images marked as decorative are also skipped.
Where Auto-Add Works
Advanced Filters
Use the Filter by Date Range dropdown at the top of both the With Alt Text and Without Alt Text pages to narrow images by upload date. Useful for processing images in manageable time-period chunks.
| Preset | Use case |
|---|---|
| Today | Daily upload checks. Good for reviewing Auto-Add results each morning. |
| Yesterday | Reviewing the previous day's uploads. |
| Last 7 Days | Weekly batch review before publishing. |
| Last 30 Days | Monthly cleanup pass. |
| Custom Range | Pick a specific start and end date. Useful for processing images from a specific campaign or content push. |
Note: One-Shot Actions ignore the active date filter and process all images in your library for the selected page (With or Without Alt Text). Use Bulk Actions if you want to process only the filtered set.
SEO Validation & Scoring
Every alt text in your media library is automatically scored out of 100 based on search engine best practices. The score gives you an at-a-glance view of your image SEO health and highlights exactly what to improve.
What the score checks:
| Check | Details |
|---|---|
| Length | Alt text should be 5–15 words. Too short = not descriptive. Too long = over-stuffed. |
| Not empty | Missing alt text scores 0. |
| Not a filename | Alt text that looks like a raw filename (e.g., IMG_1234.jpg) scores poorly. |
| No keyword stuffing | Repeating the same word multiple times is flagged. |
| Descriptive language | Generic phrases like "image of" or "photo of" lower the score. |
| No special characters | Alt text should not contain HTML or excessive punctuation. |
Scores are shown in the media table and can be used to filter or sort images that need improvement.
Score Ranges:
| Score | Rating | Meaning |
|---|---|---|
| 90–100 | 🟢 Excellent | Perfect length, natural language, descriptive and specific, SEO optimised. |
| 70–89 | 🟡 Good | Acceptable length. Minor improvements possible but mostly optimised. |
| Below 70 | 🔴 Needs Work | Too short or too long, generic language, keyword issues, or empty. |
Improving Your Scores:
Send Image Context To AI
This option lets the plugin send two extra pieces of information to the AI along with your image: the image filename, and the title of the post or page the image is attached to. With this context, the AI can write alt text that names the real subject, such as a venue, product or location, instead of only describing what is visible.
How to enable it:
Privacy note: This feature is off by default. When you switch it on, the filename and, when available, the post title are sent to your chosen AI provider with the image. If you would rather not share page information, leave it off.
A limitation to know about: the post title can only be sent when the image is actually attached to a post. WordPress records that link when you upload an image from inside the post editor. Images uploaded straight to the Media Library, or placed through a page builder, may not carry a post title. The filename is always sent, so keep your filenames meaningful.
Context Strength (Strict, Balanced, SEO)
Context strength controls how boldly the AI uses the context you send it.
There are three levels:
Important note for Claude users: if your AI provider is Claude, the SEO level can be refused by Claude's own anti keyword-stuffing behavior. The reliable setting on Claude is Strict, combined with a clear prompt that tells the AI to use your location or product name. SEO mode works well with OpenAI and Gemini.A limitation to know about: the post title can only be sent when the image is actually attached to a post. WordPress records that link when you upload an image from inside the post editor. Images uploaded straight to the Media Library, or placed through a page builder, may not carry a post title. The filename is always sent, so keep your filenames meaningful.
Guarantee Keywords in Alt Text
Guarantee keywords forces a required word or phrase into the final alt text, even if the AI leaves it out. This is useful when a term must appear, such as a person's name or a model number that the AI cannot confirm from a photo.
How it works:
Alt Text Prefix and Postfix
A prefix is text added in front of your alt text. A postfix is text added after it. Set them once and the plugin wraps every alt text it writes with both, automatically. For example a prefix of "G3 Fishing Boats" and a postfix of "Aluminum fishing boats" turns "19 GX OVH" into "G3 Fishing Boats 19 GX OVH Aluminum fishing boats."
You control where it applies with four Apply-to toggles:
A live preview in the settings shows exactly how a sample alt text will look before you commit.
Why AI-generated is off by default: AI output is already a full sentence, so wrapping a brand around it can read repetitively or like keyword stuffing. If you want your brand inside AI descriptions, use one method only. Feed it through the prompt and image context, or use a prefix and postfix, but not both at once for the same brand string.
If both fields are empty, nothing changes, so it is safe to leave on.
Output Consistency (AI Temperature)
AI models include a small amount of randomness, which is why the same image can produce slightly different alt text on different runs. The output consistency slider controls how much variation the AI is allowed.
Lower settings make the AI more consistent and predictable, so your whole library reads in a similar style. Higher settings allow more variety in wording. For most sites, a lower, more consistent setting is the safer choice. Adjust it in the AI settings and regenerate a few images to find the balance you like.
Alt Text Coverage Widget
The alt text coverage widget appears on your WordPress dashboard. It shows at a glance how many of your images already have alt text and how many are still missing it, so you always know where your library stands. You will find it on the main Dashboard screen after activating the plugin.
Troubleshooting
Plugin not appearing in the WordPress menu
AI generation not working (stuck on "Generating…" or returns an error)
Bulk actions timing out or not completing
Images not showing in the table ("No data available")
Auto-Add not generating alt text on upload
License activation failing
Frequently Asked Questions
- Do I need an API key to use the plugin?
No. The free version and all Pro plans include Copy Title to Alt Text and Copy Filename to Alt Text — these work without any API key or external account. API keys are only needed if you want to use AI-generated descriptions (OpenAI, Gemini, Claude, Azure, or Hugging Face).
- Which AI provider gives the best results?
It depends on your images and budget. OpenAI GPT-4o consistently produces the most detailed descriptions. Google Gemini is a strong free-tier option. Claude AI is excellent value for money. Azure Vision gives 5,000 free calls/month — ideal for small to medium sites. All providers are supported equally — you can switch anytime.
- Will my existing alt text be overwritten?
No. By default the plugin skips images that already have alt text. This applies to Bulk Actions, One-Shot Actions, and Auto-Add on Upload. You will never lose existing alt text unless you explicitly choose to overwrite it.
- Does the plugin send my images to external servers?
Only when you use an AI provider. When you choose OpenAI, Gemini, Claude, Azure, or Hugging Face, your images are sent to that provider’s API for processing. This is standard practice and each provider has its own privacy and data retention policy. The Copy Title and Copy Filename methods are entirely local — no image data leaves your server.
- Why is my Hugging Face API returning an error?
The most common causes are:
- “Invalid username or password” — Your token is missing the “Make calls to Inference Providers” permission. Go to your HF token settings and enable it.
- “Model not supported by any provider you have enabled” — The model you entered is not available through your enabled Inference Providers. Try the default model
Qwen/Qwen2.5-VL-7B-Instructor check the HF Inference Providers documentation for supported models. - Slow first response — Some models take 20–30 seconds to warm up on their first call (cold start). This is normal. The plugin retries automatically.
- Is the plugin compatible with WooCommerce?
Yes. The plugin works with all WordPress media including WooCommerce product images. You can filter by upload date to target recently added product images and run bulk actions on them.
- What is the "Missing Alt Highlighter"?
It is a frontend tool visible only to logged-in admins. When enabled it draws a visible red outline around every image on your live site that is missing alt text. This lets you quickly identify gaps by browsing your site normally — without running a report or opening the admin panel.
- Can I use multiple AI providers?
Yes. You can save API keys for as many providers as you like. Each Bulk Action, One-Shot, or Row Action lets you choose which provider to use for that specific run. This means you can, for example, use Gemini for product images and OpenAI for editorial images.