How to Automate Image Alt Text With n8n and a Vision Model (Audit First, Generate Second)
Alt text is one of the last SEO chores teams still do by hand, so it is a tempting target for automation: point a vision model at every image, write whatever it returns back to the CMS, done. That approach is a trap. Bulk auto-captioning produces generic, sometimes keyword-stuffed descriptions, adds alt text to decorative images that should stay empty, and quietly degrades accessibility for the screen-reader users the attribute exists to serve. The workflow that actually pays off is audit first, generate second: find the images that genuinely lack usable alt text, skip the ones that should be empty, generate context-aware descriptions only where they help, and route anything important through a human before it ships.
This guide builds that pipeline in n8n, using the WordPress REST API to read images and write approved alt text back, and a vision model to draft descriptions. It is aimed at content teams managing hundreds or thousands of images. If your site has fifty images total, close this tab and write them by hand — automation is not worth the setup.
Why “alt text for every image” is the wrong goal
Alt text has two jobs, and only one of them is SEO. It gives assistive technology a spoken equivalent of the image, and it gives search engines context for image search and the surrounding page. Neither job is served by volume. A product photo needs a precise description; a decorative divider, a background gradient, or an icon that repeats a nearby text label needs empty alt (alt="") so screen readers skip it. Auto-generating text for those images is not a neutral act — it makes pages noisier for the exact users the attribute protects.
The SEO upside of good alt text is real but bounded: it is a contextual signal, a ranking factor for Google Images, and a fallback when images fail to load. It is not a place to stuff target keywords. Google has said for years that alt text should describe the image; a model told to “write SEO alt text” tends to produce keyword salad that reads worse and can look manipulative at scale. So the goal is not coverage. The goal is correct alt text on the images that need it, and empty alt on the ones that do not.
Step 1 — Audit before you generate
The cheapest, highest-leverage part of the whole project is the audit. Before any model runs, crawl your published pages and classify every image. In n8n, a scheduled trigger fans out over your sitemap URLs, an HTTP Request node fetches each page, and an HTML/code node extracts every <img> with its src, current alt, dimensions, and surrounding heading or paragraph text.
Classify each image into one of four buckets, because each gets a different action:
The four-bucket triage
| Bucket | How to detect it | Action |
|---|---|---|
| Missing | No alt attribute at all, or alt equals the filename (e.g. IMG_4021.jpg) |
Candidate for generation |
| Weak | Very short, duplicated across many images, or clearly keyword-stuffed | Flag for review, optionally regenerate |
| Decorative | Small dimensions, icon/spacer path, or inside a link/button that already has text | Set alt="", never generate |
| Good | Descriptive, unique, human-written | Leave untouched |
Most sites discover that only a fraction of their images fall in “Missing” — the audit alone tells you whether this project is worth continuing. It also protects you from the most common failure mode: a model happily writing three sentences of alt text for a 16×16 pixel chevron icon.
Step 2 — Generate context-aware alt text with a vision model
Only the “Missing” bucket (and optionally “Weak”) reaches the model. For each image, send the vision model two things: the image itself and the context you scraped in Step 1 — the page title, the nearest heading, and the caption or paragraph the image sits in. Context is what separates useful alt text from a generic caption. A model looking at a bare photo might write “a laptop on a desk”; the same model told the page is about n8n error alerts and the image sits under “Slack notification node” will write “n8n Slack node configuration showing an error-alert message” — which is both accurate and useful for image search.
A prompt that behaves
The instruction to the model matters more than the model you pick. A prompt that works in production looks roughly like this:
- Describe what is visible in the image in one sentence, under 125 characters.
- Use the page context only to disambiguate, never to inject keywords that are not in the image.
- Do not start with “image of” or “picture of” — screen readers already announce it as an image.
- If the image is a logo, chart, or screenshot, name the type and its subject.
- Return an empty string if the image appears decorative.
That last rule gives the model a second chance to catch a decorative image your audit misclassified. Keep the character cap tight; alt text over ~125 characters gets truncated by some screen readers and rarely adds value.
Step 3 — Human review is the guardrail, not an afterthought
Do not write model output straight to the live site. Route it through a review queue — a Google Sheet or Airtable row per image with the thumbnail, the proposed alt, the page URL, and an Approve/Edit/Reject column. This is the same human-in-the-loop pattern that keeps an autonomous AI agent from making confident mistakes at scale: the model does the tedious 90%, a person spends seconds confirming or fixing the 10% that matters.
In practice you can tier the review. Images on high-traffic or commercial pages get eyes on every suggestion; images on low-priority archive pages can auto-approve if the model returns a non-empty description and your confidence checks pass. The point is that the decision to skip review is one you make deliberately, per page tier — not a default you back into because reviewing everything felt slow.
Step 4 — Write approved alt text back via the WordPress REST API
WordPress stores an image’s alt text as post meta on the attachment: the _wp_attachment_image_alt meta key on the media object. Once a row is approved, an n8n HTTP Request node sends an authenticated POST to /wp-json/wp/v2/media/<id> with the alt_text field. Use an application password for auth and form-urlencoded bodies, the same write pattern behind a self-hosted n8n monitor that edits the CMS.
Two production details save you pain. First, updating the attachment’s alt updates it everywhere that image is used, but images hard-coded into post content with an inline alt attribute need a separate content update — decide which layer is your source of truth. Second, throttle the write-back. A vision model plus a media write per image is easy to run into API rate limits and per-image model costs, so batch the writes and add a delay node; there is no prize for finishing the backfill in one minute.
When to automate this — and when not to
Automate alt text when you have a genuine backlog (hundreds of images with missing or filename alt), a steady inflow of new images, and page context a model can actually use. Do it by hand when your image count is small, when images are highly technical or ambiguous (medical, legal, engineering diagrams) where a wrong description is worse than none, or when you cannot commit to any human review. The pipeline earns its keep on scale and repetition; on a small or high-stakes library, the setup cost and the risk of confidently wrong captions outweigh the time saved.
Frequently asked questions
Does AI-generated alt text help or hurt SEO?
It helps when the description is accurate and specific, because it gives Google Images context and improves accessibility. It hurts when it is generic, duplicated across many images, or keyword-stuffed. The deciding factor is not that a model wrote it, but whether the text truthfully describes the image. Audit-first pipelines with human review help; blind bulk generation tends to hurt.
Should every image have alt text?
No. Decorative images — spacers, background gradients, icons that merely repeat adjacent text — should have empty alt (alt="") so screen readers skip them. Adding descriptions to decorative images makes pages noisier for assistive-technology users. Aim for correct alt on meaningful images, not maximum coverage.
How long should alt text be?
Roughly one sentence, under about 125 characters. Some screen readers truncate longer text, and extra length rarely adds value. Describe what is visible and stop; if an image needs a long explanation, put that in a caption or the surrounding text instead.
Which is better for this, n8n or a Python script?
Either works. n8n is convenient because it wires the crawl, the model call, the review-queue write, and the CMS write-back together with retries and scheduling and little code. A Python script gives you more control over crawling and batching. The important part is the audit-and-review logic, not the tool.
