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

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 <img> 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

But let's be honest — 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

bash
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
This is the feature I'm most excited about. You can pass a full HTML string and it will find every <img> tag missing an alt attribute and generate one:

const html = `
  <div>
    <img src="hero.jpg">
    <img src="team.jpg" alt="">
    <img src="logo.png" alt="Company logo">
  </div>
`;

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
Here are some ways you could use it:

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: github.com/kreent/alt-images-ai
npm: npmjs.com/package/alt-images-ai

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

Comments

[Kai Alder]

This is super useful. Accessibility is one of those things most devs know they should care about but rarely prioritize. Tools like this lower the barrier a lot. How accurate have you found the generated text to be?

[Enrique Uribe]

Buenoooo