How Do I Add Alt Text to Shopify Images in a Block? (1,600 Images in 3 Hours)

Build-in-public post — a real client workflow, the exact prompt, the token cost. Part of our AI workflows pillar.

The customer pain point

The client had 1,600 product images with empty alt text. This is a quiet, compounding problem:

SEO: Google Image search can't rank what it can't read. Missing alt text = missing image traffic.
Accessibility: screen-reader users get nothing. It's also a legal exposure in some jurisdictions (ADA/WCAG).
On-page relevance: alt text is a real on-page SEO signal for the product page itself, not just image search.

The reason it never got fixed: writing 1,600 unique, descriptive, non-spammy alt texts by hand is days of mind-numbing work. So it sat there for two years.

The Approach
The Prompt
Cost & Time
Why Not Just Use the Product Title?
What to Watch For

Key Takeaways

Point	Details
The fix	Custom Shopify app that pulls every image, sends the product title (+ context) to the Claude API, generates SEO-friendly alt text, and writes it back via the Admin API.
Scale	1,600 images, ~3 hours wall-clock (API rate limits + write-back, not compute).
Cost	Under $5 total at typical 2026 model pricing — short input, short output, fast model.
Result	Every image has unique, descriptive, accessibility-compliant alt text. Re-runnable for new images.

The Approach

Enumerate every product image via the Admin GraphQL API.
Skip images that already have alt text (idempotent — safe to re-run).
Generate alt text by sending the product title + product type + variant context to the Claude API.
Write back the generated alt text to the image via the Admin API.
Log every image handle + generated alt for a human spot-check.

3 hours of wall-clock time wasn't compute — it was API rate limits on the write-back side plus polite throttling. The generation itself is fast.

The Prompt

The actual prompt template (one call per image):

You are writing alt text for an ecommerce product image.

Product: {product_title}
Product type: {product_type}
Variant (if any): {variant_title}

Write ONE line of alt text that:
- Describes what is visually in the image (the product, its key visible
  attributes — color, material, form factor)
- Naturally includes the product type for SEO, without keyword stuffing
- Is under 125 characters
- Does NOT start with "image of", "picture of", or "photo of"
- Is a plain descriptive phrase, no quotes, no trailing period

Return only the alt text. Nothing else.

Why title-driven and not vision-model-driven? See the next section — for a catalog with consistent product photography, the title + type is enough context and ~10x cheaper than running every image through a vision model.

Cost & Time

Item	Estimate
App build	~2 hours, one-time
Per-image API call	~120 input tokens (prompt + title context) + ~25 output tokens (the alt text) ≈ 145 tokens
1,600 images total	~232,000 tokens
Cost at fast-model 2026 pricing	Under $5 total (a fast/cheap model like the Haiku tier handles classification-style generation at a fraction of frontier-model cost)
Wall-clock time	~3 hours — dominated by API rate limits + Admin API write-back throttling, not generation speed
Re-running for new images	Minutes, only processes images missing alt text

The honest number: this cost less than a coffee and replaced ~2 days of human work. That's the typical economics of these workflows — the value isn't "AI is magic," it's "a re-runnable system replaces a job nobody wanted to do."

Why Not Just Use the Product Title?

You can — and for some catalogs that's fine. But raw product title as alt text is weak: titles are often Brand Name — SKU-1234 — Variant, which is not descriptive and reads as spam to Google. The Claude pass turns Acme Stainless Tumbler — 20oz — Matte Black into Matte black 20oz stainless steel insulated tumbler with press-fit lid — describes the visible product, includes the type naturally, stays under 125 chars.

For catalogs with inconsistent or non-descriptive titles, the AI rewrite is worth the few dollars. For catalogs with already-descriptive titles, a templated approach might be enough — test both on 20 images and compare.

What to Watch For

Idempotency. Skip images that already have alt text or a re-run wastes calls and may overwrite human-written alt text. Make the skip check explicit.
Rate limits. Shopify's Admin API has a cost-based rate limit. Batch the write-backs and back off on THROTTLED responses — this is most of the 3 hours.
Don't over-optimize. Alt text is for describing the image to someone who can't see it. Stuffing keywords hurts both accessibility and (since Google got smarter) SEO. The prompt explicitly forbids keyword stuffing.
Spot-check the output. We logged every generated alt and the client skimmed ~50 random ones before the write-back ran. AI is good at this but you want a human gate before writing 1,600 records (see what AI-run means when the AI screws up).
Theme blocks read alt automatically. Once alt text is on the image object, OS 2.0 image blocks and the image_tag filter render it automatically — no theme changes needed.

Talk to Branva

We run image SEO, alt-text generation, and custom Shopify app builds as part of our managed operations. Book a free call — we'll audit your image SEO gap in the first 30 minutes.

Frequently Asked Questions

Does Shopify have a built-in bulk alt-text tool?

No. The bulk editor can edit alt text if you type it, but there's no built-in generation. That generation step is what the custom app provides.

Should I use a vision model to "look at" each image instead?

For most ecommerce catalogs with consistent product photography, title + type context is enough and ~10x cheaper. Use a vision model only if your images are highly varied or lifestyle-heavy where the title doesn't describe the frame.

Will this overwrite alt text I already wrote by hand?

Only if you don't add the skip check. The workflow we built explicitly skips any image that already has alt text, so human-written alt is never overwritten.

How often should I re-run it?

Whenever you add a meaningful batch of new products. Because it skips images that already have alt text, a re-run only processes the new ones and takes minutes.