How do I generate alt text for thousands of images?
Sort the images by what they do on the page, then send only the ones that carry meaning to a vision model, and give the model the surrounding page along with the image. Run the drafts through a few automatic checks, have a person review the images where a wrong description would do harm, and write the result back to your CMS with a record of which image version it describes.
The step most teams skip is the first one. A model will happily write a sentence for a decorative divider, and a screen reader will then read that sentence aloud on every page. Knowing which images need no description at all removes work and improves the result.
The problem is common. The WebAIM Million 2026 report found missing alternative text on 53.1% of the top million home pages, with 16.2% of all home page images having none. Another 10.8% of images that did have alt text had questionable text, such as "image", "graphic" or a file name.
What does alt text have to do, according to WCAG?
WCAG success criterion 1.1.1 requires a text alternative that serves the same purpose as the image. The word that matters is purpose: the right text depends on why the image is there, so the same photo can need different alt text on two pages. The W3C's alt decision tree sorts images into roles, and that gives you the first step of a bulk workflow:
| Image role | What the alt text should do | Send to a model? |
|---|---|---|
| Decorative (dividers, background flourishes) | Empty alt="", so screen readers skip it | No |
| Informative (product photos, article photos) | Say what the image contributes, in a sentence or two | Yes |
| Functional (linked logos, icon buttons) | Say what happens when you use it, such as "Search" | Usually no, take it from the link target |
| Image of text (banners, quotes) | Repeat the text in the image | Yes, an OCR model does this well |
| Complex (charts, diagrams) | A short summary, with the data on the page or linked | Yes, and always review it |
Which way of generating alt text should I use?
| Approach | Uses the page around the image | Good for | Main limit |
|---|---|---|---|
| People writing it | Yes | Small sets, legal and medical images | Does not reach thousands of images on a budget |
| A generic captioning API, such as Azure AI Vision | No | Catalogs where the image stands alone | Describes the picture, whatever the reason it is on the page |
| A vision language model with page context | Yes | Editorial sites and mixed content | You own the prompt, the checks and the retries |
| A pipeline over your image bucket | Partly | Large archives that also need search or classification | The prompt covers a whole collection of images |
How do I run the workflow?
1. Build the inventory. List every image reference with its URL, page, surrounding heading and nearby paragraph. Count references, since one image file used on 40 pages is 40 places where context can differ. 2. Remove duplicates. Hash each file and generate once per file and context pair. Near-duplicate detection catches resized copies a hash misses. 3. Assign a role. Rules cover much of this: images inside links are functional, images in theme folders are usually decorative. Ask the model to classify the rest, and let it answer "decorative". 4. Draft with context. Send the image, the page title and the nearby text. 5. Check every draft. Run the rules in the next section. 6. Review by risk. Route charts, people, medical images, products with regulated claims and anything the rules flagged to a person. Sample the rest. 7. Write back with provenance. Store the alt text, the model, the prompt version, the image hash and the reviewer. A changed hash marks the alt text stale, and a changed prompt tells you which images to redo.
A prompt that works as a starting point:
You are writing alt text for an image on a web page.
Page title: {title}
Text near the image: {nearby_text}
Return JSON with two fields:
- role: decorative, informative, functional, text or complex
- alt: one or two sentences saying what this image adds to the page
Rules: do not start with "image of" or "picture of". Do not repeat the nearby
text. Copy any text in the image exactly. Do not guess a person's name, age,
race or health. If the image adds nothing to the page, use role decorative and
leave alt empty.How do I catch bad alt text automatically?
Most failures can be caught without a second model:
Where does AI alt text go wrong?
Vision models describe what is visible, and they can miss why it matters. A photo of a CEO at a podium may come back as "a man speaking at a conference", which is true and useless on an announcement page. Page context fixes most of those.
The other failures are worse. A model can state a wrong number from a chart with full confidence, misread text in a logo, or guess at a person's identity. This is the same pattern as agents reasoning over secondhand summaries of files they cannot perceive: the description reads well, and nobody checks it against the image. That is why charts and people go to a reviewer.
An automated tool also cannot tell you the site is accessible. Alt text is one criterion among many, and the W3C guidance asks for a judgment about purpose that a check can only approximate.
How does Mixpeek fit?
Mixpeek reads your files where they already live, in S3, GCS or any bucket, and turns what's in them into data your software can search, classify and moderate. For alt text, that fits step 4 on large image archives. The multimodal extractor runs Gemini vision over images with a
description_prompt, and response_shape returns structured fields such as a role and an alt string, stored on each document. The same documents can then be searched and filtered, so you can find every image with no alt text or every chart awaiting review.The prompt is set on the collection, so this suits sets where the image stands on its own, such as a product catalog or a media archive. For editorial pages where meaning depends on the article around the image, draft in your own pipeline with page context. Description is a usage-based add-on; see pricing.
Who it is not for: if you have a few hundred images on a CMS, a plugin or a short script calling a vision model is simpler than adopting a platform.
Frequently Asked Questions
Can AI write alt text well enough to replace a person?
For plain informative images with page context, drafts are often usable with sampled review. For charts, people, medical images and anything legally sensitive, keep a person in the loop. WCAG asks whether the text serves the image's purpose, and a person is still the best judge of that.
How long should alt text be?
WCAG sets no character limit. Aim for a sentence or two, and move anything longer into the page itself, which is what the W3C recommends for complex images.
Should every image have alt text?
Every image needs an alt attribute, and decorative images should have an empty one (
alt="") so screen readers skip them. Leaving the attribute out is different: some screen readers then read the file name.Does alt text help SEO?
Google's image SEO guidance recommends descriptive alt text, and it is one of the signals that tells search engines what an image shows. Write it for people first. Keyword lists in alt text make the page worse for screen reader users.
How do I add alt text to images already in my CMS?
Export the image references with their pages, generate and check drafts outside the CMS, then write back through the CMS API. Keep the old value, so a bad batch can be reverted.
Can a model read text inside an image for alt text?
Yes, and an OCR model usually does this better than a general caption model. Xiaomi-OCR-0 and MiniCPM-OCR-1.0 are small open models for this. Copy the text exactly and do not paraphrase it.