# Image To Text (`calm_necessity/image-to-text`) Actor
Image to Text Actor analyzes images and generates detailed text descriptions of scenes, objects, and visual context. Upload an image and receive a human-readable explanation of what the image contains. Ideal for accessibility, content understanding, and automation workflows.
- **URL**: https://apify.com/calm\_necessity/image-to-text.md
- **Developed by:** [Taher Ali Badnawarwala](https://apify.com/calm_necessity) (community)
- **Categories:** AI, Developer tools, Automation
- **Stats:** 3 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
from $40.00 / 1,000 results
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
---
### TL;DR
- **Input:** Image URL or file (prefill uses a default image URL so runs complete within 5 minutes)
- **Output:** Extracted text + image URL in the default dataset
- **Use it for:** OCR, document digitization, automation, testing
- **Result time:** Usually under 1 minute
---
### Table of contents
- [Try it now](#try-it-now)
- [Overview](#overview)
- [Usage examples](#usage-examples)
- [Features](#features)
- [Configuration](#configuration)
- [Usage](#usage)
- [Output](#output)
- [For bloggers & tutorial writers](#for-bloggers--tutorial-writers)
- [Grow your user base](#grow-your-user-base)
- [Integration](#integration)
- [Technical details](#technical-details)
- [Actor health](#actor-health)
- [Testing](#testing)
- [FAQ](#faq)
- [Resources](#resources)
---
### Try it now
| Action | Link |
|--------|------|
| **Run in Apify Console** | Open Actor → Start (use default input or paste an image URL) |
| **API (sync)** | `POST https://api.apify.com/v2/acts/YOUR_USERNAME~image-to-text/run-sync` |
Replace YOUR_USERNAME with your Apify username.
---
### Overview
The **Image to Text** Actor extracts text from images using the MultipleWords API. You provide an image (via URL, file upload, or base64), and the Actor returns the extracted text and the processed image URL in the default dataset.
This Actor is useful when you need OCR on demand, document digitization, or image-to-text in workflows.
#### Common use cases
| Category | Examples |
|----------|----------|
| Documents | Receipts, forms, screenshots |
| Automation | Pipelines that need text from images |
| Development | Mock data, demos, testing |
| Content | Captions, alt text, accessibility |
> **Note:** Usage rights depend on the upstream API and your Apify plan. Review terms before commercial use.
---
### Usage examples
Use these in the **Image URL** field or API input.
| Scenario | Input |
|----------|--------|
| Default test image | Leave **Image URL** as prefilled (Wikipedia PNG) |
| Your image | `https://example.com/your-image.jpg` |
| With file | Use **File** upload instead of URL |
#### Example input (API)
```json
{
"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"
}
````
***
### Features
- **Text extraction** from images via MultipleWords API
- **Multiple input formats:** URL, file upload, file path, base64
- **Run-once-and-exit:** Processes one image per run and exits (passes [automated testing](https://docs.apify.com/platform/actors/development/automated-tests) within 5 minutes)
- **Default input:** Prefill and fallback image URL so runs succeed with one click or empty input
- **Retries:** Exponential backoff on API failures (5xx, 429, network errors)
- **Output schema:** Results shown in organized tables in the Apify Console
***
### Configuration
All settings are provided via the Actor input.
#### Input schema
The Actor uses an [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema) with:
- **image\_url** — Prefill and default set to a public test image so the Actor runs successfully with one click and passes [automated health checks](https://docs.apify.com/platform/actors/development/automated-tests) (succeed within 5 minutes, non-empty dataset).
- **file** — Optional file upload; you can provide a URL, path, or base64 string instead of image\_url.
When input is empty, null, or omits both fields, the Actor uses the default image URL so the run always completes with a non-empty dataset (required for [automated health checks](https://docs.apify.com/platform/actors/development/automated-tests)).
#### Input parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| image\_url | string | No\* | Prefilled test image URL | Public URL of the image to process |
| file | string | No\* | — | File upload, path, URL, or base64 image |
*Either image\_url or file must be provided (or use the default/prefill).*
#### Example input (full)
```json
{
"image_url": "https://example.com/document.png"
}
```
Or with file upload (Console): use the **File** field and leave **Image URL** empty if you prefer.
***
### Usage
#### Apify Console
1. Open the Actor in [Apify Console](https://console.apify.com).
2. Use the prefilled **Image URL** (or replace with your image URL) or upload a **File**.
3. Click **Start** and check the **Output** tab for extracted text and image URL.
#### API (run-sync)
Replace YOUR\_USERNAME with your Apify username and YOUR\_API\_TOKEN with your [Apify API token](https://console.apify.com/account/integrations).
```bash
curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~image-to-text/run-sync?token=YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"}'
```
Response includes run metadata and dataset items with extracted\_text and image\_url.
For multiple images or automation, call run-sync (or /run) in a loop with different image\_url or file inputs.
***
### Output
Each run writes one or more items to the default dataset. The **Output** tab shows results in an organized table (see [Output schema](https://docs.apify.com/platform/actors/development/actor-definition/output-schema)).
| Field | Description |
|-------|-------------|
| status | API response status (1 = success) |
| image\_url | URL of the processed image on the CDN |
| extracted\_text | Text extracted from the image |
#### Example output (dataset item)
```json
{
"status": 1,
"image_url": "https://multiplewords.nyc3.cdn.digitaloceanspaces.com/image_to_text/...",
"extracted_text": "The image showcases a landscape..."
}
```
***
### For bloggers & tutorial writers
You can use this Actor in tutorials, blog posts, or videos without running it first:
- **Input:** Use the [Example input](#example-input-api) or [Usage examples](#usage-examples) table.
- **Output:** Use the [Example output](#example-output-dataset-item) above to show what users get.
- **API:** Use the [API (run-sync)](#api-run-sync) curl example; remind readers to replace YOUR\_USERNAME and YOUR\_API\_TOKEN.
***
### Grow your user base
Promote your Actor to reach more users:
- **Share** in relevant communities, forums, and social media where your target audience is active (e.g. OCR, automation, no-code tools).
- **Content:** Consider blog posts, tutorials, or short videos showing use cases (receipts, forms, screenshots).
- **Integrations:** Highlight use with [Make](https://apify.com/integrations), Zapier, n8n, or custom APIs.
- **Apify Store:** Keep the README and input/output schemas clear so your Actor is easy to discover and run.
***
### Integration
- **Make (Integromat)** — Use the Apify module and select this Actor; map your image URL or file to the input.
- **Zapier** — Use the Apify Zapier app and choose "Run Actor"; select this Actor and pass image\_url or file.
- **Custom apps** — Call the Apify API (/run or /run-sync) with the same input JSON.
***
### Technical details
- Runtime: Node.js (see Dockerfile).
- Input: Validated via input schema; either
image_url or file (default image URL when both missing or input is null).
- External API: MultipleWords image_to_text; 90s timeout, retries with exponential backoff on 5xx, 429, and network errors.
- Run mode: Run-once-and-exit (no standby server); always calls
Actor.exit() in finally so the run finishes within 5 minutes.
#### Actor health
The Actor is built to pass [Apify automated testing](https://docs.apify.com/platform/actors/development/automated-tests):
- **Run-once-and-exit:** No HTTP server; the Actor gets input (or uses default), processes one image, pushes to the dataset, and exits. The test expects **Succeeded** and a non-empty default dataset within 5 minutes.
- **Null or empty input:** When Actor.getInput() is null or input has no image\_url/file, the Actor uses a built-in default image URL so the run still completes with output.
- **Prefill in input schema:** prefill and default for image\_url so one-click and test runs have a valid image.
***
### Testing
The Actor is designed to pass [Apify automated testing](https://docs.apify.com/platform/actors/publishing/test): the test runs with default (prefill) input and expects **Succeeded** and a non-empty default dataset within 5 minutes.
**How to test locally:**
1. **Console:** Start the Actor with the prefilled **Image URL** (or leave default) and confirm the **Output** tab has dataset items.
2. **API:** POST .../run-sync with {"image\_url": "https://..."} or {} and check the response for dataset items.
3. **CLI:** apify run with INPUT.json containing {"image\_url": "..."} or {}.
***
### FAQ
**How long does a run take?**\
Usually under 1 minute for a single image. Batch runs with prefilled input complete within 5 minutes.
**Can I run multiple images in one go?**\
Each run processes one image by default. For multiple images, run the Actor multiple times (e.g. from a workflow or API loop).
**Do I need an API key for the image-to-text API?**\
The Actor uses its own integration; you only need your Apify account and (for API calls) your Apify API token.
**Why is there a default image URL in the input?**\
So automated tests and new users can run the Actor with one click; the run succeeds and produces non-empty output within 5 minutes.
***
### Resources
- [Apify Console](https://console.apify.com) — Run the Actor and view datasets
- [Apify API](https://docs.apify.com/api/v2) — Run actors programmatically
- [Actor output schema](https://docs.apify.com/platform/actors/development/actor-definition/output-schema) — Define how output is displayed
- [Apify SDK for JavaScript](https://docs.apify.com/sdk/js)
- [Join the Apify community on Discord](https://discord.com/invite/jyEM2PRvMU)
# Actor input Schema
## `image_url` (type: `string`):
Public URL of an image to extract text from. Used when you don't upload a file.
## `file` (type: `string`):
Upload an image file, or provide a file path, URL, or base64 string.
## Actor input object example
```json
{
"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"
}
```
# Actor output Schema
## `results` (type: `string`):
Dataset of extracted text and image URLs (overview view)
## `dataset` (type: `string`):
Complete dataset (all fields) as JSON
# 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 = {
"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"
};
// Run the Actor and wait for it to finish
const run = await client.actor("calm_necessity/image-to-text").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 = { "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png" }
# Run the Actor and wait for it to finish
run = client.actor("calm_necessity/image-to-text").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 '{
"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"
}' |
apify call calm_necessity/image-to-text --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=calm_necessity/image-to-text",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "Image To Text",
"description": "Image to Text Actor analyzes images and generates detailed text descriptions of scenes, objects, and visual context. Upload an image and receive a human-readable explanation of what the image contains. Ideal for accessibility, content understanding, and automation workflows.",
"version": "0.1",
"x-build-id": "T6wDrj052CF7p73el"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/calm_necessity~image-to-text/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-calm_necessity-image-to-text",
"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/calm_necessity~image-to-text/runs": {
"post": {
"operationId": "runs-sync-calm_necessity-image-to-text",
"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/calm_necessity~image-to-text/run-sync": {
"post": {
"operationId": "run-sync-calm_necessity-image-to-text",
"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": {
"image_url": {
"title": "Image URL",
"type": "string",
"description": "Public URL of an image to extract text from. Used when you don't upload a file.",
"default": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"
},
"file": {
"title": "File",
"type": "string",
"description": "Upload an image file, or provide a file path, URL, or base64 string."
}
}
},
"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
}
}
}
}
}
}
}
}
}
}
```