# Alt Text Batch Generator (`ntriqpro/alt-text-batch`) Actor Batch-process multiple images to generate AI-powered alt text descriptions for accessibility. Supports up to 500 images per run. - **URL**: https://apify.com/ntriqpro/alt-text-batch.md - **Developed by:** [daehwan kim](https://apify.com/ntriqpro) (community) - **Categories:** AI, Developer tools, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $10.00 / 1,000 alt text generateds 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 ## 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 - **$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 # Actor input Schema ## `urls` (type: `array`): Array of publicly accessible image URLs to process (max 500) ## `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 '' with your token const client = new ApifyClient({ 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 '' with your token. client = ApifyClient("") # 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("💾 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 '{ "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": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=ntriqpro/alt-text-batch", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Alt Text Batch Generator", "description": "Batch-process multiple images to generate AI-powered alt text descriptions for accessibility. Supports up to 500 images per run.", "version": "1.0", "x-build-id": "iI3suJZ67mKBEeZlz" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ntriqpro~alt-text-batch/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ntriqpro-alt-text-batch", "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/ntriqpro~alt-text-batch/runs": { "post": { "operationId": "runs-sync-ntriqpro-alt-text-batch", "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/ntriqpro~alt-text-batch/run-sync": { "post": { "operationId": "run-sync-ntriqpro-alt-text-batch", "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", "required": [ "urls" ], "properties": { "urls": { "title": "Image URLs", "minItems": 1, "maxItems": 500, "type": "array", "description": "Array of publicly accessible image URLs to process (max 500)", "items": { "type": "string", "pattern": "^https?://" } }, "language": { "title": "Language", "enum": [ "en", "ko", "ja", "zh", "es", "fr", "de", "it", "pt", "ru" ], "type": "string", "description": "Language code for alt text generation (en, ko, ja, zh, etc.)", "default": "en" }, "style": { "title": "Description Style", "enum": [ "concise", "detailed" ], "type": "string", "description": "Type of alt text to generate: concise (max 125 chars) or detailed (2-3 sentences)", "default": "concise" }, "maxUrls": { "title": "Maximum URLs", "minimum": 1, "maximum": 500, "type": "integer", "description": "Safety limit for number of URLs to process (prevents accidental overconsumption)", "default": 500 } } }, "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 } } } } } } } } } } ```