# Alt Text Generator - Batch Image Descriptions (`ntriqpro/alt-text-batch`) Actor

Generate descriptive alt text for hundreds of images at once with AI vision. Output is JSON ready for CMS bulk-update and covers both SEO ranking and WCAG accessibility compliance — built for product catalogs, media libraries and social captions.

- **URL**: https://apify.com/ntriqpro/alt-text-batch.md
- **Developed by:** [daehwan kim](https://apify.com/ntriqpro) (community)
- **Categories:** AI, Developer tools, Automation
- **Stats:** 6 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 alt text generateds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Alt Text Batch Generator

Batch-process multiple images to generate AI-powered alt text descriptions for web accessibility using Qwen2.5-VL vision model.

### Overview

This Actor processes up to 500 images in a single run and generates alt text descriptions suitable for screen readers and accessibility compliance. Each successfully processed image is charged at $0.01 (pay-per-event pricing).

#### Key Features

- **Batch Processing**: Process up to 500 images per run
- **AI-Powered**: Uses Qwen2.5-VL vision model via ntriq AI service
- **Flexible Output**: Choose between concise (WCAG-compliant max 125 chars) or detailed (2-3 sentence) descriptions
- **Multi-Language**: Supports 10 languages (English, Korean, Japanese, Chinese, Spanish, French, German, Italian, Portuguese, Russian)
- **Pay-Per-Event**: Only pay $0.01 for successfully processed images
- **Error Resilience**: Continues processing even if individual images fail
- **Detailed Logging**: Track processing time and confidence scores per image

### Input

Provide an array of publicly accessible image URLs:

```json
{
  "urls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.png",
    "https://example.com/image3.webp"
  ],
  "language": "en",
  "style": "concise",
  "maxUrls": 500
}
```

#### Input Parameters

| Parameter | Type | Default | Required | Description |
|-----------|------|---------|----------|-------------|
| `urls` | array | — | ✓ | Array of image URLs (1-500 items) |
| `language` | string | `en` | — | Language code: en, ko, ja, zh, es, fr, de, it, pt, ru |
| `style` | string | `concise` | — | Output style: `concise` (≤125 chars) or `detailed` (2-3 sentences) |
| `maxUrls` | integer | `500` | — | Safety limit on processing count (1-500) |

### Output

Each image produces one dataset record:

```json
{
  "url": "https://example.com/image1.jpg",
  "status": "success",
  "altText": "A fluffy orange tabby cat sitting on a wooden windowsill",
  "detailedDescription": null,
  "language": "en",
  "model": "Qwen2.5-VL",
  "processingTimeMs": 2450,
  "confidence": 0.85,
  "error": null,
  "code": null
}
```

#### Output Fields

| Field | Type | Description |
|-------|------|-------------|
| `url` | string | Original image URL |
| `status` | string | `success` or `error` |
| `altText` | string | Generated alt text (concise style) |
| `detailedDescription` | string|null | Detailed description (detailed style only) |
| `language` | string | Output language code |
| `model` | string | AI model name (Qwen2.5-VL) |
| `processingTimeMs` | integer | Processing time in milliseconds |
| `confidence` | number | AI confidence score (0-1) |
| `error` | string|null | Error message if failed |
| `code` | string|null | Error code: `INVALID_URL`, `TIMEOUT`, `API_ERROR`, etc. |

### Usage Examples

#### Example 1: Basic Batch Processing (English, Concise)

```json
{
  "urls": [
    "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/1200px-Cat03.jpg",
    "https://upload.wikimedia.org/wikipedia/commons/thumb/1/18/Dog_Breeds.jpg/1200px-Dog_Breeds.jpg"
  ],
  "language": "en",
  "style": "concise"
}
```

**Cost**: $0.02 (2 images × $0.01)

#### Example 2: Large Batch with Detailed Descriptions (Korean)

```json
{
  "urls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg",
    "https://example.com/image3.jpg",
    "...up to 500 images..."
  ],
  "language": "ko",
  "style": "detailed",
  "maxUrls": 500
}
```

**Cost**: $0.03 - $5.00 depending on successes (1-500 images × $0.01)

### Pricing

Free plan: each run returns up to 25 results (the first 3 inputs). Paid Apify plans receive the full result set.

- **$0.01 per successfully generated alt text**
- Only charged on success (errors don't incur charges)
- No upfront cost for batch size
- Apify platform fee applies (20% of generation cost)

#### Cost Examples

| Images | Success | Cost |
|--------|---------|------|
| 10 | 10 | $0.10 |
| 50 | 48 (2 failed) | $0.48 |
| 100 | 95 (5 failed) | $0.95 |
| 500 | 500 | $5.00 |

### Timeout & Rate Limiting

- **Per-image timeout**: 30 seconds
- **Batch timeout**: Apify default (6 hours for standard run)
- **Rate limit**: 100ms delay between requests (built-in throttling)

### Error Codes

| Code | Meaning | Recovery |
|------|---------|----------|
| `INVALID_INPUT` | Missing/invalid URL parameter | Check URL format |
| `INVALID_URL` | URL not HTTP(S) or malformed | Verify URL is valid and public |
| `TIMEOUT` | Request exceeded 30 seconds | Image too large or service overloaded |
| `API_ERROR` | AI service returned error | Check service status |
| `PROCESSING_ERROR` | Other processing failure | Check image format/size |
| `EXCEPTION` | Unhandled exception | Contact support |

### Legal Notice

#### Image Source Responsibility

- You must only submit images that you own or have explicit permission to analyze.
- You are responsible for complying with the source website's Terms of Service and robots.txt.
- Do not use this tool to analyze images from stock photo sites (Getty, Shutterstock) without a valid license.

#### Copyright

- Generated alt text descriptions are not derivative works of the original images.
- However, fetching images from third-party URLs may violate the source site's Terms of Service.
- We assume no liability for third-party intellectual property claims arising from your use.

#### WCAG Compliance

- AI-generated alt text is a starting point, NOT a guarantee of WCAG 2.1 or ADA compliance.
- All generated descriptions must be reviewed by a human before production use.
- This tool assists accessibility efforts but does not replace professional accessibility auditing.

#### AI Limitations

- Descriptions may contain inaccuracies or miss important context.
- Specialized images (medical, technical, charts) require professional review.

#### Data Processing

- Images are fetched temporarily for analysis and immediately discarded.
- No images are stored, cached, or redistributed by our service.

### Technical Details

#### AI Service Integration

- **Endpoint**: `https://ai.ntriq.co.kr/analyze/image` (Qwen2.5-VL)
- **Request Timeout**: 30 seconds per image
- **Supported Formats**: JPEG, PNG, WebP, GIF, BMP
- **Max Image Size**: Depends on AI service (typically 100MB)

#### Environment Variables (Optional)

```bash
AI_API_ENDPOINT=https://ai.ntriq.co.kr/analyze/image
AI_REQUEST_TIMEOUT=30000
```

#### Processing Pipeline

1. Validate input array and language/style parameters
2. For each URL:
   - Validate URL format
   - Call AI service with optimized prompt
   - Collect response (alt text or error)
   - Push to dataset
   - Charge on success
3. Log summary (success/error counts, total cost)

### Limitations

| Limitation | Value |
|-----------|-------|
| Max images per run | 500 |
| Timeout per image | 30 seconds |
| Total batch timeout | 6 hours (Apify default) |
| Concurrent requests | Sequential (100ms between) |
| Supported formats | JPEG, PNG, WebP, GIF, BMP |

### Support

For issues or questions:

1. Check error codes and logs in run output
2. Verify all image URLs are publicly accessible
3. Confirm language code is supported
4. Review AI service status

### Version History

- **v1.0.0** (2026-03-30): Initial release
  - Batch processing (up to 500 images)
  - Concise and detailed styles
  - Multi-language support
  - Pay-per-event billing

***

**Last Updated**: 2026-03-30
**Maintainer**: ntriq Engineering
**License**: Apache 2.0

***

### 🔗 Related Actors by ntriqpro

Build your data pipeline with the ntriqpro Actor suite:

- [**image-batch-optimizer**](https://apify.com/ntriqpro/image-batch-optimizer) — Image Compressor — TinyPNG Alternative
- [**image-upscale-mcp**](https://apify.com/ntriqpro/image-upscale-mcp) — AI Image Upscaler 2x/4x
- [**vehicle-damage-assessment**](https://apify.com/ntriqpro/vehicle-damage-assessment) — AI Vehicle Damage Inspector

### ⭐ Love it? Leave a Review

Your rating helps other professionals discover this actor. [Rate it here](https://apify.com/ntriqpro/alt-text-batch/reviews).

# Actor input Schema

## `urls` (type: `array`):

Array of publicly accessible image URLs to process (max 500). Free plan: each run returns up to 25 results (the first 3 inputs). Paid Apify plans receive the full result set.

## `language` (type: `string`):

Language code for alt text generation (en, ko, ja, zh, etc.)

## `style` (type: `string`):

Type of alt text to generate: concise (max 125 chars) or detailed (2-3 sentences)

## `maxUrls` (type: `integer`):

Safety limit for number of URLs to process (prevents accidental overconsumption)

## Actor input object example

```json
{
  "urls": [
    "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/1200px-Cat03.jpg"
  ],
  "language": "en",
  "style": "concise",
  "maxUrls": 500
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "urls": [
        "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/1200px-Cat03.jpg"
    ],
    "language": "en",
    "style": "concise"
};

// Run the Actor and wait for it to finish
const run = await client.actor("ntriqpro/alt-text-batch").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "urls": ["https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/1200px-Cat03.jpg"],
    "language": "en",
    "style": "concise",
}

# Run the Actor and wait for it to finish
run = client.actor("ntriqpro/alt-text-batch").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "urls": [
    "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/1200px-Cat03.jpg"
  ],
  "language": "en",
  "style": "concise"
}' |
apify call ntriqpro/alt-text-batch --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ntriqpro/alt-text-batch"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/eFcJRSfLVupVJuSFh/builds/3W6iLLv8xaGlL6uc0/openapi.json