alt-images-ai

Generate accessible alt text for images using AI. Supports OpenAI GPT-4o Vision and Google Gemini.

Automatically add alt attributes to <img> tags in HTML, generate image descriptions in any language, and process images in batch — all with zero runtime dependencies.

Why alt-images-ai?

• Accessibility compliance — Meet WCAG 2.1 requirements by ensuring every image has descriptive alt text for screen readers
• SEO optimization — Search engines use alt text to understand images. AI-generated descriptions improve your image SEO ranking
• Save time — Stop writing alt text manually for hundreds of images. Let AI do it in seconds
• Multiple AI providers — Choose between OpenAI (GPT-4o, GPT-4o-mini) and Google Gemini (gemini-2.0-flash) based on your needs
• Lightweight — Zero runtime dependencies, uses only Node.js built-in modules
• TypeScript first — Full type definitions included out of the box

Features

• AI-powered image descriptions — Uses computer vision models to understand image content
• Flexible image input — URLs, local file paths, base64 data URIs, or Buffers
• HTML processing — Automatically scan and add alt attributes to <img> tags
• Batch processing — Generate alt text for multiple images in parallel
• Multi-language support — Generate descriptions in English, Spanish, French, German, and any other language
• Configurable — Custom prompts, max length, model selection
• TypeScript support — Full type definitions included

Installation

npm install alt-images-ai

yarn add alt-images-ai

pnpm add alt-images-ai

Quick Start

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

const client = new AltImageClient({
  provider: "openai", // or "gemini"
  apiKey: "your-api-key",
});

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

Usage

Create a Client

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

const client = new AltImageClient({
  provider: "openai",    // "openai" | "gemini"
  apiKey: "sk-...",
  language: "es",         // optional — default: "en"
  maxLength: 125,         // optional — max characters for alt text
  model: "gpt-4o",       // optional — override default model
  customPrompt: "...",    // optional — fully custom AI prompt
});

Generate Alt Text for a Single Image

// From a URL
const alt = await client.generateAlt("https://example.com/photo.jpg");

// From a local file
const alt = await client.generateAlt("./images/hero.png");

// From a Buffer
import fs from "fs";
const buffer = fs.readFileSync("photo.jpg");
const alt = await client.generateAlt(buffer);

// With per-call overrides
const alt = await client.generateAlt("photo.jpg", {
  language: "fr",
  maxLength: 100,
});

Batch Processing

Process multiple images in parallel. Failed images are collected in the errors array without stopping the rest.

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

for (const { src, alt } of results) {
  console.log(`${src} → ${alt}`);
}

for (const { src, error } of errors) {
  console.error(`${src} failed: ${error.message}`);
}

Process HTML

Scan an HTML string, find <img> tags missing alt text, and automatically generate accessible descriptions:

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);
// hero.jpg  → gets AI-generated alt
// team.jpg  → gets AI-generated alt (empty alt counts as missing)
// logo.png  → left unchanged (already has alt text)

HTML Processing Options

const result = await client.processHTML(html, {
  onlyMissing: true,        // only process images without alt (default: true)
  overrideExisting: false,   // replace existing alt values (default: false)
  language: "es",            // override language for this call
});

One-liner

Generate alt text without creating a client first:

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

const alt = await generateAlt("photo.jpg", {
  provider: "openai",
  apiKey: "sk-...",
});

Supported Providers

Provider	Default Model	Best For	Documentation
openai	gpt-4o-mini	Accuracy and detail	OpenAI Vision
gemini	gemini-2.0-flash	Speed and cost-effectiveness	Google Gemini

Use Cases

• Web accessibility audits — Scan your website HTML and auto-generate missing alt text to pass WCAG compliance checks
• Content management systems — Integrate into your CMS pipeline to generate alt text on image upload
• E-commerce — Automatically describe product images for better accessibility and SEO
• Blog platforms — Ensure every blog post image has a meaningful description
• Static site generators — Process HTML output and add alt text as a build step
• Migration tools — Bulk-add alt text to legacy HTML pages

API Reference

new AltImageClient(options)

Option	Type	Required	Default	Description
provider	"openai" | "gemini"	Yes	—	AI provider to use
apiKey	string	Yes	—	API key for the provider
model	string	No	Provider default	Override the default model
language	string	No	"en"	Language for generated alt text
maxLength	number	No	—	Maximum character length
customPrompt	string	No	—	Fully custom prompt for the AI

client.generateAlt(image, options?): Promise<string>

Generate alt text for a single image. Accepts a URL, file path, data URI, or Buffer.

client.generateAltBatch(images, options?): Promise<BatchResult>

Generate alt text for multiple images in parallel. Returns { results, errors }.

client.processHTML(html, options?): Promise<string>

Parse HTML, find <img> tags, and add AI-generated alt attributes. Returns the modified HTML string.

generateAlt(image, options): Promise<string>

Standalone convenience function that creates a client internally — useful for one-off calls.

Frequently Asked Questions

What image formats are supported?

JPEG, PNG, GIF, WebP, and BMP. Images are automatically detected by file extension or binary header.

Can I use my own prompt?

Yes. Pass a customPrompt option to fully control what the AI generates:

const client = new AltImageClient({
  provider: "gemini",
  apiKey: "...",
  customPrompt: "Describe this image in one short sentence for an e-commerce product listing.",
});

Does it work with Next.js / React / Vue?

This is a server-side package (Node.js). Use it in API routes, server components, build scripts, or any Node.js environment.

How much does it cost?

The package itself is free and open source. You only pay for the AI API calls to OpenAI or Google Gemini based on their pricing.

Requirements

• Node.js >= 18
• An API key from OpenAI or Google AI Studio

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

MIT