AI Auto Alt Text Generator

By Connor Bulmer

★ 5.0/5 (1 ratings)100+ active installationsVersion 2.0.1

Generate accessible alt text and image titles with OpenAI, Claude or DeepSeek, using page and product context.

Description

AI Auto Alt Text Generator writes meaningful, screen-reader-friendly alt text and SEO-friendly titles for your images. It works on upload, one image at a time from the Media Library, or in bulk.

Bring your own API key from OpenAI, Anthropic (Claude) or DeepSeek. You pay the provider directly, which is far cheaper than per-image subscription services.

✨ Key features

  • Automatic alt text on upload: set-and-forget accessibility.
  • Choice of provider and model:
    • OpenAI GPT-6 Luna (default, the fastest and cheapest), GPT-6.1 Sol, GPT-5.6 Luna and GPT-5.6 Terra.
    • Claude Haiku 5.5, Sonnet 5.5 and Opus 5.5.
    • DeepSeek V4.1 Flash.
  • Context-aware descriptions: the plugin finds where an image is used and passes on the page title, the nearest heading, the text around the image and its caption. For WooCommerce products it sends the product name, categories and short description, so alt text uses the right terms.
  • Alt text and a title from one request: roughly half the cost and the wait of generating them separately.
  • One-click generation: a “Generate Alt Text & Title” button in the Media Library.
  • Bulk update tool: processes existing images in batches and replaces missing or filename-style alt text, while never overwriting genuine descriptions.
  • Works on local, staging and private sites: images are embedded in the request by default, so they don’t need to be publicly reachable.
  • Keys kept out of sight: API keys are masked once saved, or can be defined in wp-config.php.
  • Multilingual output: English (US/UK) and more than 20 other languages.
  • Developer-friendly: filters, actions, outgoing webhooks and a WordPress Abilities API ability.

🧭 Where to find things

  • Settings → Alt Text Generator: provider, model, keys and options.
  • Tools → Bulk Alt Text Update (also under Media): the bulk updater.
  • Media Library: the “Generate Alt Text & Title” button on each image.

🧠 How it works

  1. When an image is uploaded, or you click generate, the plugin takes the image at your chosen size. Images over 2048 px or 4 MB are scaled down or compressed, and formats like AVIF are converted to WebP when your server can do it.
  2. It gathers short context. This is where the image is used and any WooCommerce product it belongs to, plus your site name, your optional site context and, if enabled, the file name.
  3. It sends the image and context to your chosen model in a single request. The model describes only what is visible, using the context to pick relevant terms.
  4. The alt text is saved to WordPress’ native _wp_attachment_image_alt field. The title, when enabled, is saved as the attachment title.

Settings overview

  • AI provider & Model: OpenAI, Anthropic (Claude) or DeepSeek, and one of that provider’s vision models.
  • API keys: one per provider. Saved keys are never shown again. Leave a field blank to keep the saved key, or tick “Remove saved key” to delete it. (From WP-CLI, wp option update stores exactly what you give it.)
  • Output language: English (US) by default. Choose English (UK) for British spellings, or another language.
  • Automatically generate image title: writes a title in the same request as the alt text.
  • Use page context: sends a short summary of where the image is used, and of its WooCommerce product. On by default, and capped at about 600 characters.
  • Site context: optional notes about your site, audience or brand voice.
  • Send image file name: adds the file name as extra context. On by default for new installs; camera-style names such as IMG_1234 are never sent. Sites upgrading from 1.x keep their previous choice.
  • Image size to send: Thumbnail, Medium, Large (default) or Full.
  • Image delivery: embed the image in the request (default), or send its public URL.
  • Image detail quality: Low or High. This applies to OpenAI and DeepSeek only.
  • Bulk batch size / delay: controls rate limits during bulk runs.
  • Request timeout: 10–120 seconds. A timeout is retried once with a longer wait, and rate-limit or overload errors are retried once.
  • Webhook URL & signing secret: optionally POST each result to your own endpoint.

Developers

The plugin is extensible via standard WordPress hooks, an outgoing webhook, and the WordPress Abilities API.

Filters

  • aatg_generate_on_upload ( $generate, $attachment_id ): return false to stop automatic generation on upload.
  • aatg_models ( $models ): add or change the models offered. Each entry is id => array( 'provider' => 'openai'|'anthropic'|'deepseek', 'label' => …, 'tuning' => … ).
  • aatg_alt_text_prompt ( $instruction, $post_ID, $context ): customise the alt-text instruction.
  • aatg_image_title_prompt ( $instruction, $post_ID, $context ): customise the title instruction.
  • aatg_image_context ( $lines, $post_ID, $phase ): customise the context lines sent with an image.
  • aatg_request_payload ( $payload, $provider, $context ): customise the request body for any provider.
  • aatg_openai_request_payload ( $payload, $context, $messages ): customise the Chat Completions body for OpenAI and DeepSeek. Kept from 1.x.
  • aatg_api_key ( $key, $provider ): supply an API key from elsewhere.
  • aatg_provider_endpoint ( $url, $provider, $path ): route requests through a proxy or gateway.
  • aatg_generated_alt_text ( $alt_text, $post_ID ): filter alt text before it is saved.
  • aatg_generated_title ( $title, $post_ID ): filter the title before it is saved.
  • aatg_is_low_quality_alt ( $is_low, $alt, $post_ID ): control which existing alt text the bulk tool regenerates.
  • aatg_webhook_payload ( $payload, $post_ID, $result ): customise the outgoing webhook body.
  • aatg_supported_image_extensions ( $extensions ): formats sent as-is. The default is PNG, JPEG, GIF and WebP.
  • aatg_max_image_bytes ( $bytes ): the largest image sent to the provider (default 4 MB). Bigger images are compressed, then scaled down, until they fit.

Actions

  • aatg_after_alt_text_generated ( $post_ID, $alt_text )
  • aatg_after_title_generated ( $post_ID, $title )
  • aatg_after_generation ( $post_ID, $result )

Outgoing webhook

Set a Webhook URL under Settings → Integrations & Webhooks to receive a non-blocking JSON POST after each generation. If a signing secret is set, requests include an X-AATG-Signature: sha256=… header (an HMAC-SHA256 of the body) so your endpoint can verify authenticity.

WordPress Abilities API

On WordPress 6.9+ the plugin registers the ability ai-auto-alt-text/generate-alt-text (input: attachment_id), so WordPress core AI, agents, MCP servers and automation tools can generate alt text. The caller must be allowed to edit that image. Run it with wp_get_ability( 'ai-auto-alt-text/generate-alt-text' )->execute( array( 'attachment_id' => 123 ) ).

External services

This plugin sends images to one AI provider, the one you select under Settings → Alt Text Generator, to generate alt text and (optionally) image titles. Nothing is sent until you add that provider’s API key.

When requests are made: when an image is uploaded, when you click “Generate Alt Text & Title” in the Media Library, when you run Tools → Bulk Alt Text Update, and when another tool calls the plugin’s Abilities API ability.

Data sent: the image (an embedded copy at your chosen size, or its public URL if you choose URL delivery) and short text context. The context is the site name, your optional site context, the image file name (if enabled), and, with “Use page context” on, the title, nearest heading, surrounding text and caption of where the image is used, plus WooCommerce product name, categories and short description. Page context can come from draft, pending, scheduled and private posts as well as published ones, so turn “Use page context” off if that text must not leave your site.

OpenAI

Anthropic (Claude)

DeepSeek

If you configure a Webhook URL, generated alt text, titles and the image URL are also sent to that endpoint, which you control.

Installation

  1. Upload the plugin folder to /wp-content/plugins/ai-auto-alt-text-generator, or install it via Plugins → Add New.
  2. Activate the plugin.
  3. Go to Settings → Alt Text Generator.
  4. Choose a provider and model, paste that provider’s API key, and save.

To keep a key out of the database, add it to wp-config.php instead. Any of the three keys can be set this way:

define( 'AATG_OPENAI_API_KEY', 'sk-…' );
define( 'AATG_ANTHROPIC_API_KEY', 'sk-ant-…' );
define( 'AATG_DEEPSEEK_API_KEY', 'sk-…' );

FAQ

Which provider and model should I pick?

GPT-6 Luna (OpenAI) and Claude Haiku 5.5 are both fast and cost a fraction of a cent per image. DeepSeek V4.1 Flash is similarly low-cost. Use GPT-6.1 Sol, Claude Sonnet 5.5 or Claude Opus 5.5 when you want the most detailed descriptions and don’t mind paying more.

I was using GPT-4o mini, GPT-5 mini/nano or GPT-5.4 mini/nano. What happens?

OpenAI is shutting those models down. Version 2.0 automatically moves your site to GPT-6 Luna, which costs less, and shows a one-time notice. Your API key and other settings are kept.

What data is sent to the AI provider?

The image itself: a copy at your chosen size, or its public URL if you choose URL delivery. It is sent with short context: your site name, your optional site context, the file name (if enabled) and, with page context on, the title, nearby heading, text and caption of where the image is used (including unpublished drafts and private posts), plus WooCommerce product details. Only the provider you selected receives anything.

Can I stop alt text being generated on upload?

Yes. Add add_filter( 'aatg_generate_on_upload', '__return_false' ); to a small plugin or your theme. You can still use the Media Library button and the bulk tool. In 1.x this was done with remove_action( 'add_attachment', 'aatg_generate_text_and_title' ); in 2.0 use the filter above or remove_filter( 'wp_generate_attachment_metadata', 'aatg_on_generate_metadata', 20 ).

Does the provider keep my images?

Each provider handles API data under its own terms and retention policy. See the links under “External services”. The plugin itself stores only the generated alt text and title in your WordPress database.

What if I see a 429 rate limit error?

The plugin retries once automatically. If it keeps happening, lower the bulk batch size, increase the bulk delay, or set Image detail quality to Low.

Can I customise the prompt?

Yes. Add site context in the settings, and turn page context and file names on or off. Developers can change the instructions and context with the aatg_alt_text_prompt, aatg_image_title_prompt and aatg_image_context filters.

Will the bulk tool overwrite alt text I already wrote?

No. The bulk tool regenerates alt text that is missing or clearly filename-based (for example IMG_1234, or alt text equal to the file name). Genuine human- or AI-written descriptions are left untouched. You can fine-tune the detection with the aatg_is_low_quality_alt filter.

Who can use the generator?

Anyone who can edit an image can use the Media Library button on that image. The bulk updater spends API credit across the whole library, so it requires the manage_options capability (Administrators).

Screenshots

Changelog

2.0.1

2026-11-09
* Fixed: A model reply with extra text containing } after its JSON, or using a key such as alt instead of alt_text, could be saved raw as the alt attribute. A JSON reply without alt text is now never saved.
* Fixed: Images over the size cap are now re-encoded at lower quality and then scaled down until they fit, instead of being sent oversize. Lossless PNG and GIF images (and formats like AVIF) are compressed to WebP, which keeps transparency. New aatg_max_image_bytes filter (default 4 MB).
* Fixed: Invalid UTF-8 in page text or site context no longer empties that context or raises PHP 8.1+ deprecation notices.
* Changed: Leaving an API key field blank keeps the saved key only when saving the settings page. wp option update aatg_openai_api_key '' and code now store exactly the value given.

2.0

2026-10-21
* New providers: Claude (Anthropic) and DeepSeek, alongside OpenAI. Choose Claude Haiku 5.5, Sonnet 5.5 or Opus 5.5, or DeepSeek V4.1 Flash.
* New OpenAI models: GPT-6 Luna (the new default), GPT-6.1 Sol, GPT-5.6 Luna and GPT-5.6 Terra.
* Retired models replaced: sites using GPT-4o mini, GPT-5 mini/nano or GPT-5.4 mini/nano, which OpenAI is shutting down, are moved to the cheaper GPT-6 Luna automatically, with a one-time notice.
* New: page context. The model now sees where an image is used: the page title, nearest heading, surrounding text and caption, or the featured or parent post. WooCommerce product images include the product name, categories and short description.
* New: Images are embedded in the request by default, so generation works on local, staging and password-protected sites. Public URL delivery is still available.
* Improved: Alt text and title now come from a single request, roughly halving cost and wait time.
* Improved: Tighter instructions keep descriptions to what the image shows. Place and person names are only used when a caption or product says the image shows them, the page or caption is never mentioned, and alt text stays under 125 characters.
* Changed: New installs send descriptive image file names as extra context by default. Camera-style names (IMG_1234, PXL_…, screenshots) are skipped, and sites upgrading from 1.x keep their current setting.
* Improved: Images over 2048 px are scaled down before sending. AVIF, HEIC and similar formats are converted (to WebP, or JPEG where WebP isn’t available) when the server supports it. SVGs are still skipped.
* Improved: One automatic retry on rate-limit (429) and overload (5xx) errors, respecting the provider’s retry-after header.
* Fixed: The “Image size to send” setting was ignored on upload, so the full-size original was always sent. Generation now runs after WordPress creates the image sizes.
* Security: API keys and the webhook secret are masked once saved, and keys can be defined in wp-config.php.
* Security: The bulk updater now requires administrator rights. Single-image generation and the Abilities API check permission to edit that image.
* Security: Bulk-log messages are always shown as plain text. Webhooks use wp_safe_remote_post.
* Security: Removed the bulk debug log that 1.x wrote to the public uploads folder. Any existing file is deleted on upgrade.
* Improved: Every setting is validated against its allowed values, and Site context keeps its line breaks.
* Changed: “Use full context for image titles” is gone, because titles and alt text now share the same context.
* Changed: Upload generation now runs on wp_generate_attachment_metadata (after the image sizes exist) and only for new uploads without real alt text, so regenerating thumbnails never overwrites alt text. If you turned off upload generation with remove_action( 'add_attachment', 'aatg_generate_text_and_title' ), use add_filter( 'aatg_generate_on_upload', '__return_false' ) instead.
* Developers: New filters aatg_generate_on_upload, aatg_models, aatg_request_payload, aatg_image_context, aatg_api_key and aatg_provider_endpoint. All 1.x public functions, filters and actions still work. The internal OpenAI-only helpers (aatg_openai_chat_completion_request, aatg_handle_openai_error_response, aatg_extract_openai_error_message, aatg_log_api_error, aatg_log_unexpected_response) were replaced by provider classes.
* Code: The plugin is now split into focused files under includes/ and assets/. Uninstalling the plugin removes its options.
* Tested up to WordPress 7.1.

1.22

2026-06-10
* Fixed: Images in formats OpenAI cannot read (SVG, BMP, TIFF, AVIF, HEIC, ICO, …) are now skipped before any request is made — this avoids failed HTTP 400 responses and error-log noise, and reports a clear “unsupported format” notice instead. Only PNG, JPEG, GIF and WebP are sent. Added the aatg_supported_image_extensions filter to customise the allowed list.

1.21

2026-06-09
* New: Default model is now GPT-5.4 nano (fastest & cheapest, vision-capable), with GPT-5.4 mini for higher quality. Existing installs keep their current model; legacy GPT-4o mini and GPT-5 mini/nano remain available.
* New: WordPress 7.0 compatibility (tested up to 7.0).
* New: WordPress Abilities API integration – registers an ai-auto-alt-text/generate-alt-text ability (WordPress 6.9+) so core AI, agents and automation tools can generate alt text.
* New: Outgoing webhooks – optionally POST generated alt text/titles to your own endpoint, with an optional HMAC-SHA256 signature.
* New: Developer hooks – filters (aatg_alt_text_prompt, aatg_image_title_prompt, aatg_openai_request_payload, aatg_generated_alt_text, aatg_generated_title, aatg_webhook_payload, aatg_is_low_quality_alt) and actions (aatg_after_alt_text_generated, aatg_after_title_generated, aatg_after_generation).
* Improved: Bulk updater now also regenerates filename-based / low-quality alt text, while never overwriting genuine descriptions.
* Improved: Prompts rewritten for stronger accessibility (WCAG) and SEO; alt text tightened to ~125 characters and now transcribes meaningful in-image text.
* Improved: GPT-5-family models run with low reasoning effort to keep cost and latency down.
* Improved: The Media Library “Generate Alt Text & Title” button now updates the Alt Text and Title fields instantly — no page refresh required.

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
* New: Added configurable OpenAI request timeout setting (10–120 seconds, default 30).
* Improved: OpenAI calls now retry once after timeout with a longer wait window.
* Improved: Better resilience to 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.
* New: Bulk updater log for per-image warnings/errors in the UI.
* Improved: Clearer OpenAI error handling surfaced to users.
* Improved: Rate-limit controls (batch size + delay) and low detail default.
* Fixed: Bulk counter no longer double-counts missing/blank alt text.
* Fixed: Trim stray leading quotes from generated alt text and titles.

1.17

  • New: OpenAI model selector with GPT-4o mini default and GPT 5 Mini/Nano (BETA) options.

1.16

  • New: Output Language selector – generate alt text and titles in English (UK) or other popular languages; defaults to English (US).
  • Improved discoverability: Added Media → Bulk Alt Text Update submenu (redirects to Tools page).
  • Improved workflow: Added a “Go to Bulk Alt Text Update” button on the settings page.
  • Quality of life: Added Settings and Bulk Update quick links on the Plugins screen.
  • Reliability: Bulk submenu now redirects via the page load-hook for consistent behaviour across environments.
  • No breaking changes.

1.15

  • New options: Send image file name in the prompt; optional “full context” for titles (includes site context and file name).
  • Bulk runs: Added delay control between five-image batches.
  • Diagnostics: Lightweight file logger for bulk runs.
  • General polish and copy tweaks.