Tutorial · Accessibility

Image alt text API: accessibility at scale

Alt text is not a caption and not a description of what the model sees. It is the text that replaces the image for someone who cannot see it, in the language of the page.

Short answer. Classify each image as informative, decorative, functional or complex, generate a short alternative that serves the same purpose, write an empty alt for decorative images, and batch the result into the CMS with a checksum, a dry run and a human QA sample.

WCAG 1.1.1 in practice

WCAG 2.2 Success Criterion 1.1.1 requires a text alternative for non-text content that serves the equivalent purpose, with specific exceptions. The alt text should let a reader do what the image lets a sighted reader do: understand the chart, recognize the product or know where a link goes.

Imagine the image removed and the alt read in its place: does the page still make sense? For decorative images, use alt="" so assistive technology ignores them. alt="spacer" or alt="image" is a known failure.

Context matters: the same photo can be “a woman using a laptop” on a product page and “the dashboard after setup” in a tutorial. Pass the heading and caption.

Classify the image

TypeRuleExample alt
InformativeConvey the information the image adds“Revenue rose from $2M to $3.4M between 2024 and 2026.”
DecorativeEmpty alt, no title; hide from assistive technologyalt=""
FunctionalName the destination or action“Search” for a magnifying-glass button
ComplexShort alt plus a long description or data table“Sales by region, 2026. Data in the table below.”
Text in imageAvoid; if unavoidable, include the text“Sale ends 30 November.”

Decorative is the classification teams get wrong most often. A stock photo usually adds no information; describing it adds noise. A logo that links home is functional: the alt should be the organization's name, not “logo.”

The prompt contract

Ask for a structured record, not a sentence. It should include the classification, alt text, language, confidence and reason. For decorative images, return an empty alt and a reason such as “background texture.” For complex images, return a short alt plus a separate long description.

  • No “image of” or “picture of”: screen readers already announce an image. Start with the information.
  • No filenames: IMG_2043.jpg is not an alternative. A filename in alt is a documented failure.
  • No invented detail: if a label is unreadable or a person cannot be identified, say what is visible, not a guess.
  • Keep it short where short works: a link or simple photo needs a phrase. Put detail in a long description for complex images.

Ten-language output

Multilingual alt text is a description problem first. Generate in the target language when the model is fluent, then have a native speaker review a sample. Machine translation can turn a product name into a generic noun or change the register of a button label.

Keep a glossary of product names, people, places and regulated terms that must not be translated. Store the BCP 47 language tag with every string and write to the correct locale field. Do not reuse an English alt string on a Spanish page because the image is the same; the page language determines the alternative.

For right-to-left languages, check punctuation and mixed-direction text. A ten-language rollout needs ten reviewed descriptions, not ten machine translations.

CMS batch pipeline

Run the job as a pipeline: fetch the asset and context, checksum it, skip unchanged images, generate and validate the record, then write to a draft field. A live write can publish a bad description to every page that uses the image.

import base64, hashlib, json
from openai import OpenAI

client = OpenAI(api_key="YOUR_KEY", base_url="https://api.plugsky.com/v1")
def alt_record(image_path, page_heading, page_language):
    raw = open(image_path, "rb").read()
    digest = hashlib.sha256(raw).hexdigest()
    image_b64 = base64.b64encode(raw).decode("ascii")
    schema = {"kind": "informative|decorative|functional|complex",
              "alt": "string, empty only when decorative", "long_description": "string or null",
              "language": "BCP 47 tag", "confidence": "number", "reason": "string"}
    response = client.chat.completions.create(
        model="plugsky-vision-fast", response_format={"type": "json_object"},
        messages=[{"role": "system", "content": "Write alt text that serves the same purpose as the "
                   "image. Do not start with 'image of' or use the filename. Use an empty alt for "
                   "decorative images. Add a long description for complex images. Do not invent "
                   "labels or identities. Return JSON."},
                  {"role": "user", "content": [
                      {"type": "text", "text": json.dumps({"schema": schema,
                          "heading": page_heading, "language": page_language})},
                      {"type": "image_url", "image_url": {
                          "url": f"data:image/jpeg;base64,{image_b64}"}}]}])
    record = json.loads(response.choices[0].message.content)
    record["source_hash"] = digest
    assert record["kind"] != "decorative" or record["alt"] == ""
    assert "image of" not in record["alt"].lower()
    return record

Store the hash, model, prompt version, record and reviewer decision with the asset. When the image changes, the hash changes and the job regenerates. Bump the prompt version and re-run a sample before a full batch.

QA at scale

Automated checks catch obvious failures; people catch contextual ones. Run both.

  • Missing alt: every <img> has an alt attribute, even if empty. A missing attribute is not decorative.
  • Bad patterns: filename, “image of,” “photo of,” a duplicate of the caption or an overly long string.
  • Decorative consistency: decorative images use alt="" and no title; informative images do not use an empty alt.
  • Language: the string's language matches the page locale. Flag mixed-language output.
  • Human sample: review by page type. Product, documentation, news and checkout pages fail differently.
  • Screen reader test: navigate sample pages with VoiceOver, NVDA or TalkBack.

Cost

Vision requests are priced by tokens, and image tokens depend on size and the model's tiling. Measure a representative sample, then multiply.

images = 10_000
input_tokens = images * (image_tokens + prompt_tokens) * (1 + retry_rate)
output_tokens = images * output_per_image * (1 + retry_rate)
token_cost = input_tokens * input_rate + output_tokens * output_rate
review_cost = images * sample_rate * minutes_per_review / 60 * hourly_rate
cost_per_1k = (token_cost + review_cost) / images * 1_000

Resize to the detail you need, skip unchanged assets and batch. Do not downscale a chart until labels are unreadable. On Plugsky, plugsky-vision-fast is the high-volume option and plugsky-parse is the larger vision model. See pricing.

This workflow supports SC 1.1.1 but does not establish WCAG conformance, which depends on the whole page and an audit. Keep a human reviewer accountable.

FAQ

What is WCAG 1.1.1?

It is the Level A success criterion for non-text content. It requires a text alternative that serves the equivalent purpose, with exceptions for controls, time-based media, tests, sensory content, CAPTCHA and decoration. Decorative images should be ignored by assistive technology.

How do I write alt text for a decorative image?

Use an empty alt attribute, alt="", and no title, so assistive technology skips the image. Do not use “spacer,” “image” or a description of the decoration.

Can AI generate alt text in multiple languages?

Yes, but review it with a native speaker. Generate in the page language where the model is fluent, keep a glossary for product names and proper nouns, and store the BCP 47 language tag with each string.

How do I batch alt text into a CMS?

Checksum each asset, skip unchanged images, write to a draft field, and keep the model, prompt version and reviewer with the record. Make the write idempotent so a retry updates one field instead of creating a new media item.

Does generated alt text make my site WCAG compliant?

No. It can support SC 1.1.1, but conformance depends on the full page, correct HTML, keyboard access and an audit with assistive technology. Treat the generated text as a draft and keep a human reviewer accountable.

Sources: W3C WAI, “Understanding SC 1.1.1: Non-text Content” (WCAG 2.2), and the WAI Images Tutorial decision tree. Both checked 20 November 2026. Reviewed 20 November 2026. This page describes an engineering workflow, not a certification of WCAG conformance.