# Image OCR: Bulgarian, Cyrillic, Greek & Latin (`praised_tumbler/image-ocr-bulgarian-cyrillic`) Actor

Image to text: extract text from images and phone photos with OCR that runs inside the Actor. Tilted, sideways and upside-down pictures are straightened automatically. Bulgarian, Russian, Ukrainian, Serbian, Greek, English and more. No external API.

- **URL**: https://apify.com/praised_tumbler/image-ocr-bulgarian-cyrillic.md
- **Developed by:** [Maine Wayne](https://apify.com/praised_tumbler) (community)
- **Categories:** AI, Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 image with recognised texts

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Image OCR: Bulgarian, Cyrillic, Greek & Latin Text Extraction

Image to text: extract text from **images** (PNG, JPEG, GIF, BMP, TIFF, WebP) with an OCR engine that runs **inside the Actor**: no Google/Azure/AWS API, no API key, nothing is sent to a third party. Strong support for **Bulgarian and other Cyrillic languages** (Russian, Ukrainian, Serbian, Macedonian), plus Greek, English, Romanian, Croatian, German, French, Spanish and Italian.

Typical uses: digitising scanned letters, screenshots, receipts and invoices; reading text from photos for search; preparing images for AI agents and RAG pipelines; extracting Bulgarian text that general-purpose OCR tools often get wrong.

### Input

| Field | Description |
|---|---|
| `urls` | Public http(s) links to images (up to 100): PNG, JPEG, WebP, GIF, BMP, TIFF. robots.txt is respected. HEIC photos are not supported: export them as JPEG. |
| `inlineImages` | Small images as base64 `[{"filename": "a.png", "contentBase64": "..."}]` (max 20, 10 MB total). |
| `languages` | 1 to 3 languages: `eng`, `bul`, `ell`, `rus`, `ron`, `srp`, `srp_latn`, `hrv`, `deu`, `fra`, `spa`, `ita`, `ukr`, `mkd`. |
| `pageSegmentationMode` | `auto`, `singleBlock`, `singleLine` or `sparse`. |
| `includeLines` / `includeWords` | Add lines/words with confidence and bounding boxes. |
| `maxFileSizeMb` | Skip larger files (default 15, max 30). |

#### Example input

```json
{
    "urls": ["https://example.com/scan.png"],
    "languages": ["bul", "eng"],
    "includeLines": true
}
```

### Output (one item per image)

```json
{
    "source": "https://example.com/scan.png",
    "status": "ok",
    "format": "png",
    "width": 900,
    "height": 360,
    "languages": ["bul", "eng"],
    "text": "Столицата на България е София.\nТази поща е написана на кирилица: 1234 лева.",
    "confidence": 95,
    "wordCount": 12,
    "preprocessing": { "rotationDegrees": 0, "scale": 1 },
    "warnings": [],
    "lines": [{ "text": "Столицата на България е София.", "confidence": 96, "bbox": { "x0": 30, "y0": 30, "x1": 700, "y1": 75 } }]
}
```

`status` is `ok`, `no-text` (nothing recognised) or `error` (see `error`). Only `ok` results are billed.

### Ready-made examples

Saved examples you can open, run and copy:

- [Bulgarian text from an image](https://apify.com/praised_tumbler/image-ocr-bulgarian-cyrillic/examples/bulgarian-image-to-text-ocr)

### Pricing

Pay per event: a small fee for each **image with recognised text** (`image-processed`), plus Apify's standard start fee. Images with no text and failed downloads are free. Set **Max cost per run** to cap spending; the Actor never processes or charges more than your limit allows. See the pricing panel on this page for current prices.

### Tips for accurate results

- Sharp images with text at least ~12 pixels tall work best (smaller text is enlarged automatically, blur cannot be repaired). The result carries a warning when confidence is low.
- **Pick the right language.** Selecting `bul` for Bulgarian text is much better than `eng`. Combine languages only when both really appear (for example `bul` + `eng`).
- **Phone photos are fine.** Pictures are straightened (tilt up to about 20 degrees), turned upright when they lie on their side or stand upside down, and enlarged when the text is small. `preprocessing` in the result says what was done; line and word boxes refer to the straightened picture.
- Use `singleLine` for one line of text (captions, labels) and `sparse` for scattered words.
- High-contrast, flat scans work best. Handwriting, stylised fonts, heavy backgrounds and curved text are weak spots of every OCR engine.

### Limits

- Up to 25 megapixels and 30 MB per image, 100 images per run. One image is stopped after 90 seconds.
- Text recognition only: no translation, no handwriting model, no table or form understanding. PDFs are not accepted here: the [PDF & DOCX to Markdown](https://apify.com/praised_tumbler/pdf-docx-to-markdown) Actor reads PDFs, including scanned ones, with the same OCR engine.
- Recognition is statistical: always spot-check important numbers and names.
- You are responsible for having the right to process the images you submit.

### FAQ

**Is my image sent to Google or another service?** No. The OCR engine (Tesseract compiled to WebAssembly) and the language data are bundled in the Actor.

**How good is Bulgarian recognition?** On clean, printed text it is typically very accurate; on noisy or low-resolution scans accuracy drops. Check `confidence` and `warnings`.

**Can I read text from several languages in one image?** Yes, select up to three languages, for example `["bul", "eng"]`.

**Can an AI agent call it?** Yes, through the Apify API or MCP server; use `inlineImages` for small images or `urls` for public ones.

**Why was my URL refused?** The site's robots.txt disallows automated access, the host is not public, or the file is too large. The error message says which.

### Related Actors

- [PDF & DOCX to Markdown](https://apify.com/praised_tumbler/pdf-docx-to-markdown): PDF, DOCX and HTML to Markdown, with OCR for scanned pages.
- [Invoice Data Extractor](https://apify.com/praised_tumbler/invoice-data-extractor-bulgaria-eu): invoices to structured JSON.
- [PII Redactor](https://apify.com/praised_tumbler/pii-redactor-eu-gdpr): mask personal data and secrets before sharing a text or sending it to an LLM.

# Actor input Schema

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

Public http(s) links to PNG, JPEG, GIF, BMP, TIFF or WebP images (up to 100 per run). The site's robots.txt is respected.

## `inlineImages` (type: `array`):

Small images passed directly, e.g. \[{"filename": "a.png", "contentBase64": "iVBORw0..."}]. Maximum 20 images and 10 MB in total.

## `languages` (type: `array`):

Language(s) of the text in the images. Choose up to 3. Combine only languages that really occur together (for example Bulgarian + English); more languages reduce accuracy and speed.

## `pageSegmentationMode` (type: `string`):

How the text is laid out in the image.

## `includeLines` (type: `boolean`):

Adds a `lines` array with text, confidence and bounding box per line.

## `includeWords` (type: `boolean`):

Adds words (text, confidence, bounding box) inside each line. Implies lines.

## `maxFileSizeMb` (type: `integer`):

Larger files are skipped with an error (not billed).

## Actor input object example

```json
{
  "urls": [
    "https://raw.githubusercontent.com/naptha/tesseract.js/master/tests/assets/images/simple.png"
  ],
  "inlineImages": [],
  "languages": [
    "eng"
  ],
  "pageSegmentationMode": "auto",
  "includeLines": false,
  "includeWords": false,
  "maxFileSizeMb": 15
}
```

# Actor output Schema

## `results` (type: `string`):

All results of the run (JSON items of the default dataset).

# 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://raw.githubusercontent.com/naptha/tesseract.js/master/tests/assets/images/simple.png"
    ],
    "languages": [
        "eng"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("praised_tumbler/image-ocr-bulgarian-cyrillic").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://raw.githubusercontent.com/naptha/tesseract.js/master/tests/assets/images/simple.png"],
    "languages": ["eng"],
}

# Run the Actor and wait for it to finish
run = client.actor("praised_tumbler/image-ocr-bulgarian-cyrillic").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://raw.githubusercontent.com/naptha/tesseract.js/master/tests/assets/images/simple.png"
  ],
  "languages": [
    "eng"
  ]
}' |
apify call praised_tumbler/image-ocr-bulgarian-cyrillic --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,praised_tumbler/image-ocr-bulgarian-cyrillic"
        }
    }
}
```

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/EMCIobcqFiQLFbE7N/builds/OLLesAzdf3fhy66rW/openapi.json
