The shape of the solution
Adding alt text with a vision model looks trivial: send the image, get a sentence, save it. The difficulty is everything surrounding that sentence. Uploads are synchronous, so a two-second API round trip inside wp_generate_attachment_metadata will stall the media modal and, on shared hosting, blow past max_execution_time. Model output is unpredictable, so it cannot go straight to the front end. And an unbounded loop over a 4,000-image library will quietly cost real money.
So the build has four parts:
- A queue: hook the upload, write a status flag, schedule a single event.
- A worker: a cron job that picks a resized file, calls the API, and stores the suggestion as
pending. - A budget: a per-site monthly token cap that fails closed.
- A review queue: a Media Library column plus a bulk-approve screen, so nothing reaches the front end until a human has read it.
Nothing here writes to _wp_attachment_image_alt until approval. That key is what core reads when it renders <img alt="...">, so leaving it untouched is the entire safety mechanism. The suggestion lives in a separate meta key and is inert until promoted.
What you need before you start
- WordPress 6.4 or later (the code below was run on WordPress 7.1.3). You will want registered post meta if you plan to expose the suggestion over REST later.
- PHP 8.1+. Typed parameters and
voidreturns keep the worker readable. - An OpenAI API key with access to a vision-capable model.
gpt-4o-miniis the sensible default: cheap, fast, good enough for one-sentence descriptions. - Working WP-Cron, or better, a real system cron hitting
wp-cron.php. IfDISABLE_WP_CRONis set and nothing calls it, your queue fills silently and never drains. - WP-CLI, so you can trigger the worker without uploading files by hand.
Keep the key out of the database. Define it in wp-config.php:
define( 'WPTH_OPENAI_KEY', 'sk-...' );
Step 1 Queue the job instead of calling the API
wp_generate_attachment_metadata fires inside the upload request, immediately after the resized versions are written. Anything slow here is felt directly by the person uploading: the spinner hangs, the modal sits there, and on a slow host the request dies halfway through. Scheduling a single event moves the work to a separate request entirely.
<?php
// A filter, not an action: whatever this returns becomes the attachment's metadata.
add_filter( 'wp_generate_attachment_metadata', 'wpth_queue_alt_suggestion', 20, 2 );
function wpth_queue_alt_suggestion( array $metadata, int $attachment_id ) : array {
if ( ! wp_attachment_is_image( $attachment_id ) ) {
return $metadata;
}
if ( apply_filters( 'wpth_skip_alt_suggestion', false, $attachment_id ) ) {
return $metadata;
}
if ( get_post_meta( $attachment_id, '_wpth_alt_status', true ) ) {
return $metadata; // already queued, pending or approved
}
update_post_meta( $attachment_id, '_wpth_alt_status', 'queued' );
wp_schedule_single_event(
time() + 30,
'wpth_generate_alt_suggestion',
array( $attachment_id )
);
return $metadata;
}
The 30-second delay is deliberate. It lets the upload request finish, lets the metadata settle, and avoids competing with other cron work in the same window. The status flag is the idempotency guard: if the hook fires twice for the same attachment, which happens with some offload plugins, the second call returns early.
The function is attached with add_filter() and returns $metadata on every path, because wp_generate_attachment_metadata is a filter: whatever the last callback returns is saved as the attachment’s metadata. An earlier version of this tutorial used add_action() and returned nothing, which erased the metadata of every image uploaded after the plugin was activated. No dimensions and no sizes means no srcset, no thumbnails in the media grid, and a worker that can never find medium_large:
Three uploads (a 2400×1600 photo twice and a small divider) with the earlier add_action() version (test site: WordPress 7.1.3, PHP 8.2):
#5 desk-photo.png metadata: false status: queued suggestion: -
#6 divider-01.png metadata: false status: (none) suggestion: -
#7 desk-photo-1.png metadata: false status: queued suggestion: -
The same uploads with the filter above (same test site):
#5 desk-photo.png metadata: 2400x1600, 6 sizes status: queued suggestion: -
#6 divider-01.png metadata: 600x20, 2 sizes status: (none) suggestion: -
#7 desk-photo-1.png metadata: 2400x1600, 6 sizes status: queued suggestion: -
Note the priority of 20. Core registers its own callbacks on this hook, and running after them means the intermediate sizes definitely exist when the worker looks for them.
Step 2 The background worker
The worker does five things in order: confirm the job is still wanted, check the budget, pick a resized file, call the API, sanitise and store. Any failure writes a terminal status so the same attachment is not retried forever.
<?php
add_action( 'wpth_generate_alt_suggestion', 'wpth_run_alt_suggestion' );
function wpth_run_alt_suggestion( int $attachment_id ) : void {
if ( 'queued' !== get_post_meta( $attachment_id, '_wpth_alt_status', true ) ) {
return;
}
if ( wpth_monthly_spend_exceeded() ) {
update_post_meta( $attachment_id, '_wpth_alt_status', 'skipped_budget' );
return;
}
$original = get_attached_file( $attachment_id );
$sized = image_get_intermediate_size( $attachment_id, 'medium_large' );
$path = $sized
? trailingslashit( wp_get_upload_dir()['basedir'] ) . $sized['path']
: $original;
if ( ! $path || ! is_readable( $path ) ) {
update_post_meta( $attachment_id, '_wpth_alt_status', 'error' );
return;
}
$payload = array(
'model' => 'gpt-4o-mini',
'max_tokens' => 80,
'messages' => array(
array(
'role' => 'system',
'content' => 'Write one sentence of alt text, under 125 characters. Describe what the image shows and why it matters here. Never begin with "Image of" or "Picture of". No quotation marks.',
),
array(
'role' => 'user',
'content' => array(
array( 'type' => 'text', 'text' => 'Describe this image for a screen reader.' ),
array(
'type' => 'image_url',
'image_url' => array(
'url' => 'data:' . wp_get_image_mime( $path ) . ';base64,' . base64_encode( (string) file_get_contents( $path ) ),
),
),
),
),
),
);
$response = wp_remote_post(
'https://api.openai.com/v1/chat/completions',
array(
'timeout' => 45,
'headers' => array(
'Authorization' => 'Bearer ' . wpth_openai_key(),
'Content-Type' => 'application/json',
),
'body' => wp_json_encode( $payload ),
)
);
if ( is_wp_error( $response ) || 200 !== wp_remote_retrieve_response_code( $response ) ) {
update_post_meta( $attachment_id, '_wpth_alt_status', 'error' );
return;
}
$body = json_decode( wp_remote_retrieve_body( $response ), true );
$text = sanitize_text_field(
trim( (string) ( $body['choices'][0]['message']['content'] ?? '' ), " \t\n\r\0\x0B\"'" )
);
if ( '' === $text ) {
update_post_meta( $attachment_id, '_wpth_alt_status', 'error' );
return;
}
update_post_meta( $attachment_id, '_wpth_alt_suggestion', $text );
update_post_meta( $attachment_id, '_wpth_alt_status', 'pending' );
wpth_record_spend( (int) ( $body['usage']['total_tokens'] ?? 0 ) );
}
Three details are worth pausing on. First, medium_large is used rather than the original: a 6000px JPEG base64-encoded is roughly 8MB of request body, and the model downsamples it anyway. Second, the prompt forbids “image of” because vision models default to it and it is pure noise for a screen reader. Third, the response is passed through sanitize_text_field with surrounding quotes stripped: models frequently wrap the sentence in quotation marks.
The data URL also carries the file’s real type from wp_get_image_mime(). Labelling every image as image/jpeg works by luck for some PNG and WebP files and fails for others.
The worker run on both photos: earlier version (metadata gone, PNG sent as JPEG), then the fixed version (test site: WordPress 7.1.3, PHP 8.2; the OpenAI endpoint is stubbed because the test site has no internet, so the suggestion is canned):
sent image/jpeg, 58,977 bytes
sent image/jpeg, 58,977 bytes
#5 desk-photo.png metadata: false status: pending suggestion: Laptop on a desk showing the WordPress dashboard.
#6 divider-01.png metadata: false status: (none) suggestion: -
#7 desk-photo-1.png metadata: false status: pending suggestion: Laptop on a desk showing the WordPress dashboard.
sent image/png, 57,699 bytes
sent image/png, 57,699 bytes
#5 desk-photo.png metadata: 2400x1600, 6 sizes status: pending suggestion: Laptop on a desk showing the WordPress dashboard.
#6 divider-01.png metadata: 600x20, 2 sizes status: (none) suggestion: -
#7 desk-photo-1.png metadata: 2400x1600, 6 sizes status: pending suggestion: Laptop on a desk showing the WordPress dashboard.
If your site is public and you would rather send a URL than a payload, swap the image_url value for wp_get_attachment_image_url( $attachment_id, 'medium_large' ). Remember that OpenAI’s servers must be able to fetch it, which rules out local development and most password-protected staging sites.
Step 3 Budget cap and the skip filter
The cap is expressed in tokens rather than pounds or dollars, because token pricing changes and you do not want a hard-coded price table rotting in your plugin. Everything fails closed: if the cap is reached, the job is marked skipped_budget and the attachment stays in the queue for a human to handle manually.
<?php
function wpth_openai_key() : string {
return (string) apply_filters(
'wpth_openai_api_key',
defined( 'WPTH_OPENAI_KEY' ) ? WPTH_OPENAI_KEY : ''
);
}
function wpth_current_month_tokens() : int {
return (int) get_option( 'wpth_tokens_' . gmdate( 'Ym' ), 0 );
}
function wpth_monthly_spend_exceeded() : bool {
$cap = (int) apply_filters( 'wpth_monthly_token_cap', 250000 );
return wpth_current_month_tokens() >= $cap;
}
function wpth_record_spend( int $tokens ) : void {
if ( $tokens < 1 ) {
return;
}
update_option( 'wpth_tokens_' . gmdate( 'Ym' ), wpth_current_month_tokens() + $tokens, false );
}
add_filter( 'wpth_skip_alt_suggestion', function ( bool $skip, int $attachment_id ) : bool {
if ( $skip ) {
return true;
}
$mime = (string) get_post_mime_type( $attachment_id );
if ( ! in_array( $mime, array( 'image/jpeg', 'image/png', 'image/webp' ), true ) ) {
return true; // SVG, GIF, PDF previews — out of scope
}
if ( get_post_meta( $attachment_id, '_wpth_decorative', true ) ) {
return true;
}
$file = basename( (string) get_attached_file( $attachment_id ) );
return (bool) preg_match( '/^(icon|divider|spacer|bg|pattern|swatch)[-_]/i', $file );
}, 10, 2 );
250,000 tokens is roughly 300–400 images at medium_large resolution with a short completion: adjust with the filter. The counter is a non-autoloaded option keyed by month, so it never loads on a front-end request and old months roll off naturally.
Caveat: get_option followed by update_option is not atomic. Two workers finishing at the same instant can lose a few tokens. For a media library that is acceptable; if you need exact accounting, write to a custom table with INSERT ... ON DUPLICATE KEY UPDATE.
The skip filter runs at queue time, not worker time, so decorative images never consume a slot. Filename matching is crude but effective: most theme assets are named divider-01.png or icon-search.svg. Add a checkbox on the attachment edit screen writing _wpth_decorative for the cases the filename misses.
Step 4 Surface the queue in the Media Library
A queue nobody looks at is a queue that never drains. A column in list mode is the cheapest possible interface: it shows the status, a preview of the suggestion, and whether anything has actually been published.
<?php
add_filter( 'manage_media_columns', function ( array $columns ) : array {
$columns['wpth_alt'] = __( 'Alt text', 'wpth' );
return $columns;
} );
add_action( 'manage_media_custom_column', function ( string $column, int $attachment_id ) : void {
if ( 'wpth_alt' !== $column ) {
return;
}
$status = (string) get_post_meta( $attachment_id, '_wpth_alt_status', true );
$suggestion = (string) get_post_meta( $attachment_id, '_wpth_alt_suggestion', true );
$published = (string) get_post_meta( $attachment_id, '_wp_attachment_image_alt', true );
if ( 'pending' === $status && '' !== $suggestion ) {
printf(
'<span class="wpth-badge wpth-badge--pending">%s</span><br><em>%s</em>',
esc_html__( 'Pending review', 'wpth' ),
esc_html( wp_trim_words( $suggestion, 12 ) )
);
return;
}
if ( '' !== $published ) {
printf(
'<span class="wpth-badge wpth-badge--ok">%s</span>',
esc_html__( 'Published', 'wpth' )
);
return;
}
printf(
'<span class="wpth-badge">%s</span>',
esc_html( '' !== $status ? $status : __( 'None', 'wpth' ) )
);
}, 10, 2 );
Everything is escaped with esc_html on output. The suggestion is model-generated text and should be treated as untrusted input, exactly like a comment body: it has been through sanitize_text_field on the way in, and it is escaped again on the way out.

Step 5 The bulk approve screen
Editing fifty suggestions one attachment at a time is miserable. A single screen with a text input per row, a nonce, and a capability check turns a chore into a two-minute job.
<?php
add_action( 'admin_menu', function () : void {
add_media_page(
__( 'Alt Text Review', 'wpth' ),
__( 'Alt Text Review', 'wpth' ),
'edit_others_posts',
'wpth-alt-review',
'wpth_render_alt_review_page'
);
} );
function wpth_render_alt_review_page() : void {
if ( ! current_user_can( 'edit_others_posts' ) ) {
wp_die( esc_html__( 'You cannot review alt text.', 'wpth' ) );
}
if ( isset( $_POST['wpth_alt_review'] ) ) {
check_admin_referer( 'wpth_alt_review' );
$approve = array_map( 'absint', (array) ( $_POST['wpth_approve'] ?? array() ) );
foreach ( (array) ( $_POST['wpth_alt'] ?? array() ) as $id => $alt ) {
$id = absint( $id );
if ( ! $id || ! in_array( $id, $approve, true ) || ! current_user_can( 'edit_post', $id ) ) {
continue; // only the rows the reviewer ticked
}
update_post_meta( $id, '_wp_attachment_image_alt', sanitize_text_field( wp_unslash( $alt ) ) );
update_post_meta( $id, '_wpth_alt_status', 'approved' );
}
echo '<div class="notice notice-success is-dismissible"><p>'
. esc_html__( 'Alt text saved.', 'wpth' )
. '</p></div>';
}
$pending = get_posts( array(
'post_type' => 'attachment',
'post_mime_type' => 'image',
'post_status' => 'inherit',
'posts_per_page' => 50,
'meta_key' => '_wpth_alt_status',
'meta_value' => 'pending',
'orderby' => 'date',
'order' => 'DESC',
) );
echo '<div class="wrap"><h1>' . esc_html__( 'Alt Text Review', 'wpth' ) . '</h1>';
if ( ! $pending ) {
echo '<p>' . esc_html__( 'Nothing waiting for review.', 'wpth' ) . '</p></div>';
return;
}
echo '<form method="post">';
wp_nonce_field( 'wpth_alt_review' );
echo '<table class="widefat striped"><thead><tr><th>'
. esc_html__( 'Approve', 'wpth' ) . '</th><th>'
. esc_html__( 'Image', 'wpth' ) . '</th><th>'
. esc_html__( 'Suggested alt text', 'wpth' )
. '</th></tr></thead><tbody>';
foreach ( $pending as $item ) {
printf(
'<tr><td><input type="checkbox" name="wpth_approve[]" value="%d"></td><td>%s</td><td><input type="text" class="large-text" name="wpth_alt[%d]" value="%s"></td></tr>',
(int) $item->ID,
wp_get_attachment_image( $item->ID, 'thumbnail' ),
(int) $item->ID,
esc_attr( (string) get_post_meta( $item->ID, '_wpth_alt_suggestion', true ) )
);
}
echo '</tbody></table>';
submit_button( __( 'Approve selected', 'wpth' ), 'primary', 'wpth_alt_review' );
echo '</form></div>';
}
Each row has its own Approve box, and the handler only publishes the ticked rows. Without the boxes, “Approve selected” would approve every row on the page, including the ones the reviewer never read:
The form submitted with one of two rows ticked: earlier version, then with the Approve boxes (test site: WordPress 7.1.3, PHP 8.2):
Earlier version: 2 rows on the screen, 1 ticked. Published alt text now on: 2 image(s)
With the boxes: 2 rows on the screen, 1 ticked. Published alt text now on: 1 image(s)

The reviewer edits the text in place, so a bad suggestion costs a few keystrokes rather than a rejection workflow. wp_get_attachment_image() is used for the thumbnail because it returns a fully-formed, escaped <img>: do not hand-build the markup.
Fifty rows per page is a deliberate limit. Larger pages make the query slow and the screen unwieldy; if you have hundreds pending, add pagination with paginate_links() rather than raising the number.
Step 6 Keep the front end clean
Because the worker writes to _wpth_alt_suggestion and never to _wp_attachment_image_alt, nothing unapproved can reach the front end. Core reads the latter key when it builds the alt attribute, so the separation is the guarantee.
One safety net is still worth adding: if a reviewer approves an image but clears the text, fall back to the original suggestion rather than shipping an empty alt on a content image. The flip side is that clearing the field no longer marks an image as decorative, so use the _wpth_decorative flag for that.
<?php
add_filter( 'wp_get_attachment_image_attributes', function ( array $attr, $attachment ) : array {
if ( ! empty( $attr['alt'] ) ) {
return $attr;
}
if ( 'approved' === get_post_meta( $attachment->ID, '_wpth_alt_status', true ) ) {
$attr['alt'] = (string) get_post_meta( $attachment->ID, '_wpth_alt_suggestion', true );
}
return $attr;
}, 10, 2 );
If you later expose the suggestion in the block editor, register the meta with show_in_rest and a sanitize_callback, then read it through the data layer: never by injecting raw REST HTML into the DOM.
When the queue stalls
- Nothing ever leaves
queued. WP-Cron is not running. Check forDISABLE_WP_CRONinwp-config.php, then confirm your system cron hitswp-cron.phpevery five minutes. Test manually withwp cron event run wpth_generate_alt_suggestion. - Every job ends in
error. Logwp_remote_retrieve_response_code()and the body. A 401 means the key is missing or the constant is defined after the plugin loads; a 429 means rate limiting and you should add a backoff before rescheduling. - Timeouts on large PNGs. The
medium_largesize may not exist for very small uploads: the fallback to the original then sends a big file. Cap the source withwp_get_image_editor()and a 1024px resize before encoding. - Duplicate suggestions. Another plugin is firing
wp_generate_attachment_metadatamore than once. The status guard handles it, but check that nothing is deleting_wpth_alt_statuson save. - Alt text missing in the block editor. The editor reads
_wp_attachment_image_alt; refresh the media modal after approving. If it still shows nothing, confirm the meta was written with a string, not an array. - Budget cap hit on day two. Your library probably contains many decorative assets. Tighten the filename regex and add the
_wpth_decorativecheckbox to the attachment edit screen.
Where to take it next
- Keep the key out of the browser and the database: encrypting AI API keys at rest with Sodium fits the
wpth_openai_api_keyfilter in step 3, and a Needs Review status for AI drafts applies the same review-first idea to posts. - Add a WP-CLI command,
wp wpth backfill --limit=200, that queues existing attachments in batches so you can process a legacy library without touching the upload flow. - Register the suggestion meta with block bindings so a custom block can display the pending text in the editor as a hint, while the rendered output still uses the approved value.
- Log every call to a custom table with attachment ID, token count, model, and timestamp. The monthly option is fine for a cap; a table is what you want when someone asks where the money went.
- Extend the review screen with a “reject” action that clears the suggestion and sets
_wpth_decorative, so genuinely decorative images never re-enter the queue. - Wire the same worker to a caption suggestion, stored under a different meta key and reviewed on the same screen.
Leave a Reply