I built an npm package that auto-generates alt text for images using AI

Source: Dev.to

I got tired of writing alt text manually for hundreds of images, so I built alt-images-ai — an npm package that uses OpenAI or Google Gemini to generate accessible image descriptions automatically.

The Problem

Every “ tag should have an alt attribute. It’s essential for:

• Screen readers – visually impaired users depend on alt text to understand images
• SEO – search engines use alt text to index and rank your images
• WCAG compliance – missing alt text is one of the most common accessibility violations

Writing good alt text for every image is tedious, especially when you have dozens (or hundreds) of images across your site.

The Solution

alt-images-ai takes an image (URL, file path, or Buffer) and returns a concise, descriptive alt text using AI vision models.

Install

npm install alt-images-ai

Basic usage

import { AltImageClient } from "alt-images-ai";

const client = new AltImageClient({
  provider: "gemini", // or "openai"
  apiKey: process.env.AI_API_KEY,
});

const alt = await client.generateAlt("https://example.com/photo.jpg");
// "Golden retriever running across a sunlit meadow"

Process an entire HTML page

You can pass a full HTML string and it will find every “ tag missing an alt attribute and generate one:

const html = `
  
    
    
    [Image: Company logo]
  
`;

const result = await client.processHTML(html);

Result

• hero.jpg → gets AI‑generated alt text
• team.jpg → gets AI‑generated alt text (empty alt counts as missing)
• logo.png → left unchanged (already has meaningful alt)

Batch processing

Need to process multiple images at once? It runs them in parallel:

const { results, errors } = await client.generateAltBatch([
  "https://example.com/img1.jpg",
  "https://example.com/img2.jpg",
  "./local-image.png",
]);

Multi‑language

Generate alt text in any language:

const client = new AltImageClient({
  provider: "gemini",
  apiKey: process.env.AI_API_KEY,
  language: "es", // Spanish
});

What I used to build it

• TypeScript – full type definitions included
• Zero runtime dependencies – only uses Node.js built‑in modules (https, fs, path)
• Two AI providers – OpenAI (GPT‑4o‑mini) and Google Gemini (gemini‑2.0‑flash)

Use cases

• Accessibility audits – scan your site’s HTML and auto‑fix missing alt text
• CMS integration – generate alt text automatically when users upload images
• E‑commerce – describe product images for better accessibility and SEO
• Build step – add it to your static site generator pipeline
• Migration – bulk‑add alt text to legacy HTML pages

Try it out

npm install alt-images-ai

• GitHub: https://github.com/kreent/alt-images-ai
• npm: https://www.npmjs.com/package/alt-images-ai

Would love to hear your feedback! If you find it useful, a ⭐ on GitHub would mean a lot.