# AI Alt Text Generator & Checker: Fix Missing Alt Text (`raional/ai-alt-text-generator`) Actor
Generate accessibility- and SEO-ready alt text for a list of image URLs, or scan a whole website and write alt text for every image that's missing it. Powered by AI vision.
- **URL**: https://apify.com/raional/ai-alt-text-generator.md
- **Developed by:** [Raion Al](https://apify.com/raional) (community)
- **Categories:** SEO tools, E-commerce, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet
## Pricing
from $5.00 / 1,000 image processeds
This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event
## What's an Apify Actor?
Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".
## How to integrate an Actor?
If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).
If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).
For usage examples, see the [API](#api) section below.
For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).
# README
## AI Alt Text Generator — Bulk Image Alt Text for SEO & Accessibility
Generate **accessibility- and SEO-ready alt text** for images at scale using AI vision. Feed it a **list of image URLs**, or point it at a **website** and it will find every image that's missing alt text and write it for you — then hand back a clean report you can export to CSV, JSON, or Excel.
Great for: **image alt text**, **bulk alt text generation**, **AI image captioning**, **WCAG / accessibility** compliance, **SEO images**, e-commerce product catalogs, CMS migrations, and accessibility audits.
---
### What it does
- **Mode A — Image URLs:** give it a list of image URLs → get alt text for each.
- **Mode B — Website audit:** give it a page (or several) → it scans the HTML, finds `![]()
` tags, and generates alt text for the images that are **missing or have empty alt** (`onlyMissingAlt`). Ideal for auditing a site's accessibility gaps.
- Multilingual output, a length cap tuned for WCAG (~125 characters), an optional **SEO keyword hint**, and **decorative-image detection** (recommends empty `alt=""` for purely ornamental images instead of a bogus description).
### Output
One dataset row per image, with a table view built in:
| Field | Description |
|---|---|
| `imageUrl` | The image that was described |
| `altText` | The generated alt text (empty for decorative images) |
| `flaggedDecorative` | `true` if the image was judged purely decorative |
| `charCount` | Length of the alt text |
| `pageUrl` | The page it was found on (website mode) |
| `existingAlt` | The alt text already present, if any |
| `status` | `ok`, `error`, or `mocked` |
A run **summary** (counts + estimated cost) is stored in the key-value store under `SUMMARY`.
### Example input
**Website audit (only images missing alt):**
```json
{
"startUrls": [{ "url": "https://example.com" }],
"onlyMissingAlt": true,
"language": "English",
"style": "concise",
"maxLength": 125,
"maxImages": 200
}
````
**A list of image URLs, Spanish, with an SEO hint:**
```json
{
"imageUrls": [
"https://example.com/products/mug-01.jpg",
"https://example.com/products/mug-02.jpg"
],
"language": "Spanish",
"keywordHint": "handmade ceramic mug, product page",
"style": "descriptive"
}
```
### Key options
| Option | Default | Notes |
|---|---|---|
| `imageUrls` | `[]` | Mode A — direct image URLs |
| `startUrls` | `[]` | Mode B — website pages to scan |
| `onlyMissingAlt` | `true` | Website mode: skip images that already have alt text |
| `language` | `English` | Any language |
| `style` | `concise` | `concise` (WCAG-friendly) or `descriptive` |
| `maxLength` | `125` | Hard character cap |
| `keywordHint` | — | Woven in naturally; no keyword stuffing |
| `detectDecorative` | `true` | Recommends `alt=""` for ornamental images |
| `maxImages` | `200` | Per-run safety cap (controls cost) |
| `model` | `google/gemini-2.5-flash-lite` | Any OpenRouter vision model (e.g. `openai/gpt-5-nano`, `amazon/nova-lite-v1`) |
| `apiBaseUrl` | OpenRouter | OpenAI-compatible base URL — swap for OpenAI/Groq/Together/local |
| `renderJs` | `false` | Use a browser for JS-heavy sites (slower) |
| `maxPagesPerCrawl` | `1` | Pages to crawl per start URL (same domain) |
| `concurrency` | `5` | Parallel image requests |
### Pricing
Billed **per image processed** (pay-per-event). Failed images are **not** charged. On cheap OpenRouter vision models the underlying cost is roughly **$0.0001–0.0003 per image**. Supported image formats: JPEG, PNG, GIF, WebP (SVG/ICO are skipped in website mode).
### Please note (fair use & accuracy)
- **Only scan websites you own or have permission to analyze.** You supply the target; you're responsible for it.
- Alt text is **AI-generated** — review it before publishing, especially in legally-sensitive or compliance-critical contexts.
- Images are processed transiently and are **not stored** beyond the run; your results live in your dataset.
***
### Running / self-hosting
The hosted actor provides the AI backend — you just pay per image. To self-host or run locally:
1. `npm install`
2. Set `OPENROUTER_API_KEY` (env var) or pass `openrouterApiKey` in the input. Get a key at https://openrouter.ai/keys
3. `npx apify-cli run` (or `npm start`). Without a key it runs in **mock mode** (placeholder alt text) so you can test the pipeline.
To use a different provider, set the `apiBaseUrl` input to any OpenAI-compatible endpoint (OpenAI, Groq, Together, a local server) and supply that provider's key.
#### Configure monetization (maintainer)
On the Apify platform, set `OPENROUTER_API_KEY` as an Actor environment secret, and configure a **pay-per-event** price for the event `image-processed` in the Actor's monetization settings. The code calls `Actor.charge({ eventName: 'image-processed' })` once per successfully processed image.
Built with [Apify SDK](https://docs.apify.com/sdk/js/) + [Crawlee](https://crawlee.dev/) + OpenRouter vision models.
# Actor input Schema
## `imageUrls` (type: `array`):
Mode A — a list of direct image URLs to generate alt text for. Leave empty if you only want to scan websites.
## `startUrls` (type: `array`):
Mode B — website pages to scan for images. Only scan sites you own or have permission to analyze. The actor finds ![]()
tags and writes alt text for images that are missing it.
## `onlyMissingAlt` (type: `boolean`):
In website mode, only generate alt text for images whose alt attribute is empty or missing. Turn off to (re)generate alt text for every image.
## `language` (type: `string`):
Language for the generated alt text (e.g. English, Spanish, French, German).
## `style` (type: `string`):
Concise = short, functional alt text (recommended for accessibility). Descriptive = a richer description.
## `maxLength` (type: `integer`):
Hard cap on alt text length. WCAG guidance favors ~125 characters or fewer.
## `keywordHint` (type: `string`):
Optional context or target keyword to weave in naturally (no keyword stuffing). E.g. 'handmade ceramic mug, product page'.
## `detectDecorative` (type: `boolean`):
Flag purely decorative images (spacers, ornaments) and recommend empty alt text (alt="") instead of a description.
## `maxImages` (type: `integer`):
Safety cap on how many images to process in one run (controls cost).
## `model` (type: `string`):
Any OpenRouter (or OpenAI-compatible) vision model ID. Cheap, reliable defaults: google/gemini-2.5-flash-lite, openai/gpt-5-nano, amazon/nova-lite-v1. Browse all vision models at https://openrouter.ai/models?modality=text+image-%3Etext
## `renderJs` (type: `boolean`):
Website mode only. Use a full browser to render JavaScript-heavy pages before extracting images. Recommended on: most modern sites load images via JavaScript. Turn off for faster scans of static HTML sites.
## `maxPagesPerCrawl` (type: `integer`):
Website mode only. How many pages to crawl per start URL (same domain). 1 = just the given page.
## `concurrency` (type: `integer`):
How many images to describe in parallel. Higher is faster but may hit model rate limits.
## `apiBaseUrl` (type: `string`):
OpenAI-compatible chat-completions base URL. Defaults to OpenRouter. Change to use OpenAI, Groq, Together, or a local server (e.g. https://api.openai.com/v1).
## `openrouterApiKey` (type: `string`):
Optional. Only needed if you self-host this actor. On the hosted actor this is provided for you and you simply pay per image processed. Get one at https://openrouter.ai/keys
## Actor input object example
```json
{
"imageUrls": [
"https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg"
],
"startUrls": [],
"onlyMissingAlt": true,
"language": "English",
"style": "concise",
"maxLength": 125,
"detectDecorative": true,
"maxImages": 200,
"model": "google/gemini-2.5-flash-lite",
"renderJs": true,
"maxPagesPerCrawl": 1,
"concurrency": 5,
"apiBaseUrl": "https://openrouter.ai/api/v1"
}
```
# Actor output Schema
## `altText` (type: `string`):
One dataset row per image: imageUrl, altText, flaggedDecorative, charCount, pageUrl, existingAlt, status.
## `summary` (type: `string`):
Counts (processed, decorative, errors) and estimated model cost for the run.
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"imageUrls": [
"https://picsum.photos/id/237/400/300",
"https://picsum.photos/id/1015/400/300"
],
"startUrls": []
};
// Run the Actor and wait for it to finish
const run = await client.actor("raional/ai-alt-text-generator").call(input);
// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.dir(item);
});
// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs
```
## Python example
```python
from apify_client import ApifyClient
# Initialize the ApifyClient with your Apify API token
# Replace '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {
"imageUrls": [
"https://picsum.photos/id/237/400/300",
"https://picsum.photos/id/1015/400/300",
],
"startUrls": [],
}
# Run the Actor and wait for it to finish
run = client.actor("raional/ai-alt-text-generator").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(item)
# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start
```
## CLI example
```bash
echo '{
"imageUrls": [
"https://picsum.photos/id/237/400/300",
"https://picsum.photos/id/1015/400/300"
],
"startUrls": []
}' |
apify call raional/ai-alt-text-generator --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=raional/ai-alt-text-generator",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "AI Alt Text Generator & Checker: Fix Missing Alt Text",
"description": "Generate accessibility- and SEO-ready alt text for a list of image URLs, or scan a whole website and write alt text for every image that's missing it. Powered by AI vision.",
"version": "0.1",
"x-build-id": "ad7mZROVcOhTrLOsE"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/raional~ai-alt-text-generator/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-raional-ai-alt-text-generator",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/raional~ai-alt-text-generator/runs": {
"post": {
"operationId": "runs-sync-raional-ai-alt-text-generator",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/raional~ai-alt-text-generator/run-sync": {
"post": {
"operationId": "run-sync-raional-ai-alt-text-generator",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"properties": {
"imageUrls": {
"title": "Image URLs",
"type": "array",
"description": "Mode A — a list of direct image URLs to generate alt text for. Leave empty if you only want to scan websites.",
"items": {
"type": "string"
}
},
"startUrls": {
"title": "Website URLs to scan",
"type": "array",
"description": "Mode B — website pages to scan for images. Only scan sites you own or have permission to analyze. The actor finds ![]()
tags and writes alt text for images that are missing it.",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"title": "URL of a web page",
"format": "uri"
}
}
}
},
"onlyMissingAlt": {
"title": "Only images missing alt text",
"type": "boolean",
"description": "In website mode, only generate alt text for images whose alt attribute is empty or missing. Turn off to (re)generate alt text for every image.",
"default": true
},
"language": {
"title": "Alt text language",
"type": "string",
"description": "Language for the generated alt text (e.g. English, Spanish, French, German).",
"default": "English"
},
"style": {
"title": "Style",
"enum": [
"concise",
"descriptive"
],
"type": "string",
"description": "Concise = short, functional alt text (recommended for accessibility). Descriptive = a richer description.",
"default": "concise"
},
"maxLength": {
"title": "Max length (characters)",
"minimum": 20,
"maximum": 500,
"type": "integer",
"description": "Hard cap on alt text length. WCAG guidance favors ~125 characters or fewer.",
"default": 125
},
"keywordHint": {
"title": "SEO keyword / context hint",
"type": "string",
"description": "Optional context or target keyword to weave in naturally (no keyword stuffing). E.g. 'handmade ceramic mug, product page'."
},
"detectDecorative": {
"title": "Detect decorative images",
"type": "boolean",
"description": "Flag purely decorative images (spacers, ornaments) and recommend empty alt text (alt=\"\") instead of a description.",
"default": true
},
"maxImages": {
"title": "Max images per run",
"minimum": 1,
"maximum": 5000,
"type": "integer",
"description": "Safety cap on how many images to process in one run (controls cost).",
"default": 200
},
"model": {
"title": "Vision model",
"type": "string",
"description": "Any OpenRouter (or OpenAI-compatible) vision model ID. Cheap, reliable defaults: google/gemini-2.5-flash-lite, openai/gpt-5-nano, amazon/nova-lite-v1. Browse all vision models at https://openrouter.ai/models?modality=text+image-%3Etext",
"default": "google/gemini-2.5-flash-lite"
},
"renderJs": {
"title": "Render JavaScript (slower)",
"type": "boolean",
"description": "Website mode only. Use a full browser to render JavaScript-heavy pages before extracting images. Recommended on: most modern sites load images via JavaScript. Turn off for faster scans of static HTML sites.",
"default": true
},
"maxPagesPerCrawl": {
"title": "Max pages per site",
"minimum": 1,
"maximum": 200,
"type": "integer",
"description": "Website mode only. How many pages to crawl per start URL (same domain). 1 = just the given page.",
"default": 1
},
"concurrency": {
"title": "Parallel image requests",
"minimum": 1,
"maximum": 20,
"type": "integer",
"description": "How many images to describe in parallel. Higher is faster but may hit model rate limits.",
"default": 5
},
"apiBaseUrl": {
"title": "API base URL (advanced)",
"type": "string",
"description": "OpenAI-compatible chat-completions base URL. Defaults to OpenRouter. Change to use OpenAI, Groq, Together, or a local server (e.g. https://api.openai.com/v1).",
"default": "https://openrouter.ai/api/v1"
},
"openrouterApiKey": {
"title": "OpenRouter API key (optional)",
"type": "string",
"description": "Optional. Only needed if you self-host this actor. On the hosted actor this is provided for you and you simply pay per image processed. Get one at https://openrouter.ai/keys"
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```