# alt-images-ai

[![npm version](https://img.shields.io/npm/v/alt-images-ai)](https://www.npmjs.com/package/alt-images-ai)
[![npm downloads](https://img.shields.io/npm/dm/alt-images-ai)](https://www.npmjs.com/package/alt-images-ai)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)

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

```bash
npm install alt-images-ai
```

```bash
yarn add alt-images-ai
```

```bash
pnpm add alt-images-ai
```

## Quick Start

```typescript
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

```typescript
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

```typescript
// 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.

```typescript
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:

```typescript
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

```typescript
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:

```typescript
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](https://platform.openai.com/docs/guides/vision)  |
| `gemini` | `gemini-2.0-flash` | Speed and cost-effectiveness | [Google Gemini](https://ai.google.dev/docs)                     |

## 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:

```typescript
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](https://platform.openai.com/api-keys) or [Google AI Studio](https://aistudio.google.com/apikey)

## Contributing

Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/kreent/alt-images-ai).

## License

MIT