Backfilling alt text with AI: a single afternoon for thousands of WordPress images.

Most WordPress sites that have been around for years have the same accessibility debt: thousands of images in the media library uploaded without alt text. Writing the alt text by hand is a job the team will never get to — it's tedious, low-prestige, and the value compounds invisibly. Backfilling the same images with a current-generation AI model is a single afternoon's work that closes the accessibility gap, improves image SEO, and removes a recurring liability without burning anyone's calendar. Here's what the process actually looks like, and where the AI gets it wrong.

The accessibility debt is real and predictable. A typical 5-year-old WordPress site has somewhere between 1,000 and 10,000 images in the media library. Best case, maybe 10% have meaningful alt text, usually the ones uploaded in the last six months when someone read an accessibility article and started caring. The other 90% are uploaded with empty alt text or, worse, alt text that’s just the filename (“IMG_3829.jpg” makes a terrible screen-reader experience).

Manually writing alt text for the backlog is the job nobody will do. It’s slow (a careful description takes 30-60 seconds per image), low-value-feeling (each individual fix is invisible to the team), and the team’s time is always better spent on the next deliverable. The backlog sits.

The 2026-era fix is bulk processing with a vision-capable AI model. The current generation (GPT-4o, Claude 4 Sonnet, Gemini 2 Pro with vision) can analyze an image and produce a useful descriptive alt text in a few seconds. Run the entire backlog through it overnight, review the output, push it to production. The job that would have taken six months of editorial labor takes an afternoon of engineering plus a day of review.

What “useful alt text” actually means.

Before automating, it’s worth being clear about what good alt text is, because the model’s output is only as good as the prompt that asks for the right thing.

Good alt text:

• Describes what’s in the image and why it matters in context. Not “person standing in front of building” but “Jane Smith presenting at the 2024 industry conference, the photo accompanies the announcement of her appointment as CEO.”
• Is concise. Aim for 50-125 characters. Screen reader users hear the entire alt text; long alt text is fatigue.
• Doesn’t start with “image of” or “picture of.” Screen readers already announce that the element is an image. Redundant prefixes waste the user’s time.
• Is empty for purely decorative images. A hairline divider, a background gradient, a stock photo of “office plants” used as visual filler. These should have alt="", signaling to screen readers to skip them.

The same standards apply to AI-generated alt text. The prompt has to ask for it specifically, or the model produces verbose, “image of”-prefixed descriptions that are technically correct but bad alt text.

The pipeline that works.

The realistic processing pipeline for a backlog:

1. Pull the media library inventory. You can use WP-CLI’s post command (wp post list –post_type=attachment –fields=ID,url) coupled with a database query for the existing _wp_attachment_image_alt post meta.. Output: a CSV of every attachment, its current alt text (often empty), and its URL.
2. Filter to images that need work. Anything with empty alt text or alt text matching a “looks like a filename” pattern goes into the queue.
3. Process in batches. For each image: send the URL to the AI model with a structured prompt asking for alt text per the conventions above. The model returns a candidate description.
4. Persist the candidates to a staging table or a custom post meta field. Don’t write directly to _wp_attachment_image_alt yet. The next step is human review.
5. Editor review interface. A simple admin screen that shows each image alongside its AI-generated candidate alt text, with an “approve,” “edit,” or “mark decorative” action. The editor can rip through 100 images in 15 minutes.
6. Promote approved candidates to production. Approved alt text gets written to _wp_attachment_image_alt. Decorative-marked images get explicit alt="". Rejected ones stay flagged for manual rewrite.

The processing step is the time-consuming part if the library is large; the review step is the human-judgment part. Properly structured, the review pace is roughly 5-10 images per minute, which means a 5,000-image library is genuinely a day of review work (not weeks).

The prompt matters.

The single biggest variable in output quality is the prompt. A vague prompt (“describe this image”) produces verbose, generic descriptions. A specific prompt (“write a concise alt-text description, 50-125 characters, no ‘image of’ prefix, that captures what’s in the image and why it matters; if the image is purely decorative, respond with just [decorative]“) produces useful results most of the time.

Adding context helps further:

• Site context. “This is a WordPress site for [business type]; the image will accompany an article about [topic].” Helps the model write context-appropriate descriptions.
• Page context. Where in the post body does the image appear? Is it a featured image, an inline content image, or a decorative section divider? The right alt text differs.
• Output format. Structured JSON (“alt_text”, “is_decorative”, “confidence”) makes the downstream pipeline simpler than freeform text.

A well-structured prompt plus the right model produces 70-85% of outputs that are usable as-is, 10-20% that need light editing, and 5-10% that need rejection (the model misidentified the image, missed the context, or produced something inappropriate). The review interface is what turns that 70-85% into 100% with minimal human time.

Where the AI gets it wrong.

The honest failure modes:

• Charts, diagrams, and infographics. The model usually describes the visual style (“a bar chart with bars in blue and orange”) instead of the actual data the chart conveys. A real alt text for a chart needs to communicate the data point or trend. AI tends to fail here.
• People identification. The model won’t name people (rightly so — it’s not a face-recognition tool). Generic descriptions like “a woman speaking” work but miss the context.
• Brand-specific or domain-specific imagery. A product photo of a specific SKU, a screenshot of a specific tool, an industry-specific diagram. The model produces generic descriptions that miss the specific meaning.
• Sensitive content. Medical imagery, legal documents, anything where the alt text might need legal review. The model produces plausible-looking text; the team needs to verify.

For all of these, the review step catches the issue. The model produces a candidate; the editor adjusts. The point of automation isn’t perfection; it’s getting from “no alt text on 9,000 images” to “approved alt text on 9,000 images” in a week instead of never.

The compound payoff.

The accessibility benefit is the obvious one. The less-obvious payoffs:

• Image SEO improves. Google reads alt text as a strong signal for image search; well-described images surface for image queries they previously didn’t.
• The CMS becomes more searchable. If you add a small snippet to force the media library search to query the wp_postmeta table (which it doesn’t do natively), editors looking for a specific image can finally find it based on its contents.
• Future image uploads inherit the discipline. Once the backlog is cleared and an “auto-suggest alt text on upload” pattern is in place, the team never accumulates the same backlog again.

For sites where accessibility actually matters — government, healthcare, education, financial services, anywhere subject to compliance review — backfilling the alt text is one of the cheapest ways to close a major accessibility gap. It also turns the “we’ve been meaning to do this” item that’s been on the editorial backlog for years into a closed ticket.

See auto-generated alt text for WordPress: where it works, where it fails for the publish-side angle on the same tooling.