# AI Auto Alt Text Generator

Automatically generates alt text and image titles for uploaded images in WordPress using OpenAI models you can choose from (defaulting to GPT-5.4 nano). Improves accessibility and SEO with no manual effort.

**External service used:** OpenAI (see “External services” section in `readme.txt` for full details).

---

**Plugin Name:** AI Auto Alt Text Generator   
**Author:** [Connor Bulmer](https://connorbulmer.co.uk)   
**Version:** 1.23
**Stable tag:** 1.23
**Tested up to:** WordPress 7.0   
**Requires at least:** WordPress 5.5   
**License:** GPL v3 or later   
**Tags:** alt text, accessibility, SEO, image optimisation, GPT-4o, media, AI alt text   

---

## ✨ Features

- Automatically generates alt text on image upload
- Optional automatic image title generation
- One-click manual generation in the Media Library
- Bulk update tool for existing images with options to add delay to avoid rate limits
- Choose the image size and visual detail level to send
- Provide optional site-wide context to improve results
- Optionally include the image file name in the prompt
- Choose between GPT-5.4 nano (default), GPT-5.4 mini, and legacy GPT-4o mini / GPT-5 models
- Uses OpenAI vision-capable models (text + image input)
- Lightweight and privacy-conscious — no third-party servers involved except OpenAI
- Language selection provided to enable alt text in the appropriate language
- Developer hooks (filters & actions) and optional outgoing webhooks
- WordPress Abilities API integration (WordPress 6.9+/7.0) for AI agents and automation

---

## 🧠 How It Works

This plugin uses the OpenAI API to generate meaningful, screen-reader-friendly alt text and titles for your media uploads. It sends the image **via public URL** to OpenAI along with context like:

- The parent page title (if attached)
- Site context (from plugin settings)
- (Optional) The original image file name — e.g. `woman-on-a-bridge.jpg`

The response is used to fill the image’s `alt` attribute and (optionally) its WordPress title.

---

## 🛠 Installation

1. Upload the plugin to `/wp-content/plugins/ai-auto-alt-text-generator`  
   (or install via the Plugins screen in WordPress)
2. Activate it
3. Go to **Settings → Alt Text Generator**
4. Enter your OpenAI API key
5. Adjust your preferences and save

---

## ⚙️ Settings Overview

| Option                            | Description |
|----------------------------------|-------------|
| **OpenAI API Key**               | Required to connect to OpenAI |
| **OpenAI Model**                 | GPT-5.4 nano (default), GPT-5.4 mini, or legacy GPT-4o mini / GPT-5 mini / GPT-5 nano |
| **Image Size to Send**           | Thumbnail, Medium, Large, or Full |
| **Image Detail Quality**         | Send ‘low’ or ‘high’ image detail |
| **Bulk Batch Size**              | Number of images per bulk batch (lower to reduce rate-limit risk) |
| **Bulk Delay (seconds)**         | Pause between batches to avoid rate limits |
| **Site Context**                 | Optional (but recommended)  prompt hint (e.g. about your company/website, your brand voice or industry) |
| **Send Image File Name**         | Includes file name (e.g. `products-summer.jpg`) in prompt |
| **Automatically Generate Title** | Create SEO-friendly titles for images |
| **OpenAI Request Timeout (seconds)** | Max wait time for OpenAI responses (10–120s, default 30s) |
| **Webhook URL & secret**         | Optionally POST generated alt text/titles to an external endpoint (optional HMAC signature) |

---

## 🖱 Manual & Bulk Generation

- **Media Library:** Each image gains a “Generate Alt Text & Title” button
- **Bulk Tool:** Found under **Tools → Bulk Alt Text Update**  
  Scans your library in configurable batches and regenerates missing or filename-based alt text, with a progress bar

---

## 📦 Changelog

## 1.23 2026-06-30

- Improved bulk detection for cleaned filename and generic upload/gallery label alt text.
- Updated the OpenAI prompt to ignore file names, camera codes and gallery labels unless those words are genuinely visible in the image.
- Added a generated-output guard so filename-like or generic-label responses are not saved as completed alt text.
- Disabled bulk debug file logging by default; developers can re-enable it with `AATG_BULK_DEBUG`.

## 1.22 2026-06-10
- 🛡️ Skip unsupported image formats (SVG, BMP, TIFF, AVIF, HEIC, …) before sending to OpenAI — avoids failed HTTP 400 requests and error-log spam; only PNG, JPEG, GIF and WebP are sent. New `aatg_supported_image_extensions` filter

## 1.21 2026-06-09
- 🚀 New default model: GPT-5.4 nano (fastest & cheapest, vision-capable); GPT-5.4 mini available for higher quality. Existing installs keep their current model; legacy GPT-4o mini and GPT-5 models remain selectable
- ✅ WordPress 7.0 compatibility (tested up to 7.0)
- 🧩 WordPress Abilities API: registers `ai-auto-alt-text/generate-alt-text` (WordPress 6.9+) for core AI, agents and automation
- 🔔 Outgoing webhooks with optional HMAC-SHA256 signature
- 🪝 Developer filters & actions for prompts, payload, output and webhook
- 🔁 Bulk tool now also regenerates filename-based / low-quality alt text, never overwriting genuine descriptions
- ♿ Prompts rewritten for stronger accessibility (WCAG) and SEO; alt text tightened to ~125 characters
- ✨ Media Library “Generate Alt Text & Title” button now updates the fields instantly (no page refresh needed)

## 1.20 2026-03-25
- 🐛 Fixed: Resolved an uncommon issue where generated alt text could include the parent page/post title; prompt now explicitly instructs the model to omit it

## 1.19 2026-02-02
- ⏱️ Added configurable OpenAI request timeout setting (10–120 seconds, default 30)
- 🔁 OpenAI requests now retry once after timeout with an extended timeout window
- 🛟 Reduces transient `cURL error 28` timeout failures during alt text/title generation

## 1.18 2026-01-28
- 🎨 New branded tabbed dashboard with Settings, Bulk Updater, and Integrations panels
- 🧾 Bulk updater now includes a scrollable error/warning log per image
- 🧯 Improved OpenAI error handling surfaced in the UI
- 🚦 Added rate-limit controls (batch size + delay) and set image detail to Low by default
- 🧮 Fixed bulk counter to avoid double counting images without alt text
- ✂️ Trims stray leading quotes from generated alt text and titles

## 1.17 2025-09-09
- 🤖 Added OpenAI model selector with GPT-4o mini default and GPT 5 Mini/Nano (BETA) options

## 1.16 2025-09-09
- 📖 Added language selector to enable outputs in multiple languages, currently supporting the more mainstream languages, but with room to grow in the future
- Improved UX and findability of settings and bulk optimisation in a few places

## 1.15 - 2025-07-29
- 🌐 Various tweaks to help get the plugin listed in the WP repo

## 1.14 - 2025-05-07
- ⏲️ Added option to adjust delay and set the new default delay to 2 seconds (from 5 seconds), it would be worth checking your RPM/RPD [here](https://platform.openai.com/docs/models/gpt-4o-mini) to make sure you do not hit rate limits

### 1.13 – 2025-05-06
- ✅ Fixes for bulk update not working on some versions of MySQL

### 1.12 – 2025-05-01
- ✅ Tweaks to bulk update
- ✅ Various code cleanups and tweaks to work towards getting this on WP.org

### 1.11 – 2025-04-23
- ✅ Added checkbox for full site context for image title generations

### 1.10 – 2025-04-23
- 🛠️ Fixed: bulk update tool was prematurely ending after the first batch  
- ✅ `post_status = inherit` now included in remaining-image query  
- ✅ Improved meta-query to detect alt text that is empty **or** whitespace  
- 🧮 Remaining counter is now accurate across all batches  
- 🖱 Bulk update button now disables while the process is running and re-enables on completion

### 1.9 – 2025-04-21
- ✅ Added setting to include the image file name in the prompt
- ✅ Updated prompts to include filename context when enabled
- ✅ Improved plugin description and settings clarity

### 1.8 – 2025-04-21
- 🔐 Security hardening and internal code review
- ✅ Sanitised all option inputs with `sanitize_text_field()`
- ✅ Added nonce verification to all AJAX handlers
- ✅ Escaped all dynamic content in admin HTML output
- ⚙️ Refactored settings page for cleaner registration
- 🛡️ All options now use WordPress Settings API with proper defaults

### 1.7 – 2025-04-20
- 🆕 Real-time bulk update UI with progress bar and debug text
- ✅ AJAX response now includes per-image alt text preview
- 🔄 Bulk update now runs in batches of 5 with 5 5-second delay
- 🧠 Title prompt refined: “Output ONLY the title without extra labels”

### 1.6 – 2025-04-18
- ✅ Full-scan mode: finds all images with missing alt text
- ⚙️ Bulk processor now uses `sleep()` between chunks
- 🕒 Added `set_time_limit(0)` for longer runs
- 💡 Cleaned up AJAX handler logic

### 1.5 – 2025-04-14
- 🆕 Added “Automatically Generate Image Title” option (on by default)
- ✨ New `aatg_generate_image_title()` function
- 🔄 Title generation now integrated into upload and manual triggers

### 1.4 – 2025-04-10
- 📝 Added “Site Context” field (used in both alt and title prompts)
- ⚙️ Major settings refactor: API key, image size, detail level, context

### 1.3 – 2025-04-07
- 🔧 Default image size set to `large`
- 🖼 Added “Image Detail Quality” dropdown: `high` / `low`
- 🧩 Parent post title now included as contextual hint

### 1.2 – 2025-04-03
- 🖱 Added manual “Generate Alt Text” button to Media Library
- ⚙️ AJAX handler for on-demand generation

### 1.1 – 2025-03-28
- ⚙️ Settings page created under Settings → Alt Text Generator
- ✅ OpenAI API key and image size options added

### 1.0 – 2025-03-25
- 🎉 Initial release
- 🧠 Auto-generates alt text on upload using GPT-4o mini
- ✅ Stores output in `_wp_attachment_image_alt`

---

## ❓ FAQ

### What if I see a 429 rate limit error?
Try reducing the bulk batch size, increasing the bulk delay, switching Image Detail Quality to **Low**, and shortening any site context or prompts that are overly long.

### Does this store anything externally?
No — images are passed to OpenAI by URL only, and never stored. Your data remains private.

### What model does this use?
GPT-5.4 nano by default (cheapest, vision-capable), with GPT-5.4 mini for higher quality. Legacy GPT-4o mini and GPT-5 mini/nano remain selectable. Existing installs keep their previously selected model.

### Can I customise the prompt?
You can guide results using:
- Site context (freeform)
- Parent page title (automatic)
- Image file name (optional setting)

The prompt text itself is optimised for clear, accessible, SEO-friendly alt descriptions, and developers can override it via the `aatg_alt_text_prompt` and `aatg_image_title_prompt` filters.

---

## 📜 License

This plugin is licensed under the GNU General Public License v3.0 or later.  
See: [https://www.gnu.org/licenses/gpl-3.0.html](https://www.gnu.org/licenses/gpl-3.0.html)

---

> Developed with ❤️ by [Connor Bulmer](https://connorbulmer.co.uk)  
> Accessibility, SEO, and automation — all in one plugin.