Guides
OCR PDF API
Make scanned PDFs searchable and selectable. Tool id ocr-pdf; runs on our servers through POST /tasks.
At a glance#
| Property | Value |
|---|---|
| Tool id | ocr-pdf |
| Accepts | |
| Files per task | At least 1; at most 50 on Pro, 200 on Business |
| Largest file | 500 MB on Pro, 500 MB on Business |
| Plan | Every plan with API access |
| Result |
Accepted MIME types: application/pdf.
Options#
Put options in data.options. Missing options take their defaults; a value outside the allowed range answers 400 (see Errors).
| Option | Type | Default | Allowed values | Required |
|---|---|---|---|---|
languages | array of strings | ["eng"] | any of: eng, fra, deu, spa, por, ita, nld, ara, hin, jpn, chi_sim, rus, tur, vie, ind, ben, tel, tam, mar, urd, swa, fil, chi_tra, kor, pol, ukr, heb, msa, bul, cat, ell, swe | No |
pdfa | boolean | false | — | No |
textFile | boolean | false | — | No |
autoRotate | boolean | true | — | No |
deskew | boolean | true | — | No |
clean | boolean | false | — | No |
dewarp | boolean | false | — | No |
existingText | string | "skipText" | one of: skipText, redoOcr | No |
pages | string (page ranges) | "" | — | No |
removeBlankPages | boolean | false | — | No |
blankThreshold | number | 0.5 | 0.05 to 5 | No |
blankList | string (page ranges) | "" | — | No |
Allowances and credits#
- Each page counts against your monthly cloud OCR pages; beyond the allowance each page costs 1 credit.
Build a request#
Upload the file as files[] and the tool and options as a JSON string in data. Change the options below and the request follows; only values that differ from the defaults are sent. Set MACAAW_API_KEY to a sandbox key while you build (see Quickstart).
curl https://macaaw.com/public/v1/tasks \
-H "Authorization: API-Key $MACAAW_API_KEY" \
-F "files[]=@report.pdf;type=application/pdf" \
-F 'data={"tool":"ocr-pdf","options":{}}'201 Created
{
"id": "3f0c9a52-6d1e-4c8b-a1f4-0e7d2b9c8a11",
"tool": "ocr-pdf",
"status": "task.queued",
"state": "queued",
"error": null,
"input_size": 4831022,
"output_size": null,
"output_files": null,
"stats": null,
"sandbox": false,
"date_created": "2026-10-30T11:35:00.000000Z",
"date_completed": null,
"expires_at": null
}Then poll the task or wait for the task_completed webhook, and download the result. When a task produces several files, the download is a ZIP.
Sandbox tasks are free and never counted: they process at most 5 pages and their output is stamped. Live tasks count against your plan like tasks on the website.
Try it without code on the website: OCR PDF.