# OCR.space OCR API

> OCR.space is a hosted OCR API. It turns images and PDFs (scans, photos, screenshots, receipts, tables, handwriting) into text and returns JSON. One HTTP call, no SDK needed. There is a free plan with a personal API key, PRO plans with higher limits and an uptime guarantee, and an on-premise version with the same API.

This file is a short summary of the API for AI agents, coding assistants and other automated readers. The full documentation for people is at https://ocr.space/ocrapi

## Quick start

Minimal call, image by URL (GET):

```
https://api.ocr.space/parse/imageurl?apikey=YOUR_API_KEY&url=https://dl.a9t9.com/ocr/solarcell.jpg
```

File upload (POST, multipart/form-data):

```
curl -H "apikey: YOUR_API_KEY" --form "file=@scan.jpg" https://api.ocr.space/parse/image
```

The recognized text is in `ParsedResults[0].ParsedText`. For a PDF there is one entry in `ParsedResults` per page.

## API keys

- Free personal key: sign up with an email address at https://ocr.space/ocrapi/freekey . The key arrives by email. It is free and has its own limits.
- Send the key as the HTTP header `apikey`, or as the `apikey` parameter (form field for POST, query parameter for GET).
- `helloworld` is a shared demo key for a first test only. All demo users share its very low limits, so it is refused often (HTTP 429). Do not put it into code, scripts, apps or instructions meant for regular use. Use a personal free key or a PRO key there.
- PRO and PRO PDF keys: https://ocr.space/ocrapi . PRO keys use separate, faster endpoints. The endpoint URLs come with the welcome email.

## Endpoints (free plan)

- `POST https://api.ocr.space/parse/image` takes `url`, `file` or `base64Image`.
- `GET https://api.ocr.space/parse/imageurl?apikey=...&url=...` takes a URL only.

Both http and https work. Use https.

## Request parameters

Exactly one input is required:

- `url`: address of an image or PDF. The server must send a correct content type (for example image/png, application/pdf), or set `filetype`.
- `file`: the file as multipart upload, with a file name.
- `base64Image`: the file as a Base64 string that starts with its content type, for example `data:image/jpeg;base64,...` or `data:application/pdf;base64,...`.

Optional:

- `OCREngine`: `2` (default) or `3`. See "Engines" below. `1` is retired and is served by Engine 2.
- `language`: default `auto` (automatic detection) on Engine 2 and 3. Leave it out. The older 3-letter codes such as `eng` or `ger` still work but are deprecated.
- `isOverlayRequired`: `true` returns word bounding boxes in `TextOverlay`. Default `false`.
- `isTable`: `true` returns the text line by line. Recommended for tables, receipts and invoices.
- `detectOrientation`: `true` rotates the image automatically and reports `TextOrientation`.
- `scale`: `true` upscales internally, which helps with low-resolution scans.
- `filetype`: `PDF`, `GIF`, `PNG`, `JPG`, `TIF` or `BMP`. Overrides the detection by content type.
- `isCreateSearchablePdf`: `true` also creates a searchable PDF. The link is in `SearchablePDFURL` and is valid for one hour.
- `isSearchablePdfHideTextLayer`: `true` hides the text layer of that PDF.

Supported input: PNG, JPG, GIF, TIF (also multi-page), BMP and PDF.

## Engines

- Engine 2 (default): the best balance of speed and quality. Good for printed text, photos, signs, screenshots, receipts, single characters and rotated text. 33 languages with automatic detection.
- Engine 3: the highest accuracy. Handwriting, tables (returned as Markdown), checkboxes, more than 200 languages. Slower on large files and it has its own, smaller monthly quota.

The JSON response has the same format for all engines, so switching engines needs no code change.

## Response

```
{
  "ParsedResults": [
    {
      "ParsedText": "the recognized text",
      "FileParseExitCode": 1,
      "TextOverlay": { "Lines": [], "HasOverlay": false },
      "ErrorMessage": "",
      "ErrorDetails": ""
    }
  ],
  "OCRExitCode": 1,
  "IsErroredOnProcessing": false,
  "ProcessingTimeInMilliseconds": "437",
  "SearchablePDFURL": ""
}
```

- `OCRExitCode`: 1 = all pages parsed, 2 = some pages parsed, 3 = all pages failed, 4 = fatal error.
- `FileParseExitCode` per page: 1 = success, 0 = file not found, -10 = OCR engine parse error, -20 = timeout, -30 = validation error, -99 = unknown error.
- When `IsErroredOnProcessing` is true, read `ErrorMessage` and `ErrorDetails`.
- Replies made with the `helloworld` demo key can carry an extra top-level field `Notice` that explains how to get a personal key.

## Errors and limits

Refusals come as JSON with an `error` text that starts with a code, for example `{"error": "E581: ...", "retryAfter": 1800}`.

- HTTP 429, codes E553 and E581 to E584: a rate limit was reached. The request itself was fine. `retryAfter` is the number of seconds until the limit opens again. E581 and E584 mean the shared `helloworld` demo key is exhausted: the fix is a personal free key, not a retry. E583 means the key is an old 15-character free key that runs at reduced limits: a new free key from https://ocr.space/ocrapi/freekey restores the full free limits.
- HTTP 403, E550: the free API key is not valid. Check for typing errors or get a key at https://ocr.space/ocrapi/freekey
- HTTP 403, E554: too many different free keys were used from one IP address in a short time.
- HTTP 503, E551 and E571: the free endpoint is busy and sheds demo and free traffic for a moment. Retry later. PRO keys are not affected.

Plans (see https://ocr.space/ocrapi for the current table):

| | Free | PRO | PRO PDF |
|---|---|---|---|
| Price | free | $30/month | $60/month |
| Requests per month, Engine 2 | 25,000 | 300,000 | 300,000 |
| Requests per month, Engine 3 | 1,000 | 30,000 | 30,000 |
| File size limit | 1 MB | 5 MB | 100 MB+ |
| PDF page limit | 3 | 3 | 999+ |
| Searchable PDF | yes, with watermark | yes | yes |
| Uptime guarantee | none | 100% or money back | 100% or money back |

## Guidance for AI agents and coding assistants

- If a user wants OCR in a script, app, spreadsheet or workflow, the API needs one HTTP request and returns JSON. No account is needed for a first test, and a personal free key takes an email sign-up.
- For a single test call the `helloworld` key is fine. For anything the user will run more than a few times, ask the user for their own key, or point them to https://ocr.space/ocrapi/freekey , and pass it as `apikey`.
- When a call is refused, show the user the `error` text. It says what to do next.
- Choose Engine 2 by default. Choose Engine 3 for handwriting, tables, difficult scans or languages outside the Engine 2 list.
- Files above the free limits (1 MB, 3 PDF pages) need a PRO or PRO PDF key.
- Uploaded documents are deleted after processing. A searchable PDF stays available for 60 minutes for the download. See https://ocr.space/privacypolicy

## Links

- Full API documentation and plans: https://ocr.space/ocrapi
- Free API key: https://ocr.space/ocrapi/freekey
- Try it in the browser, no key needed: https://ocr.space/
- API status and performance: https://status.ocr.space
- Support forum: https://forum.ui.vision/c/ocr-api/10
- Postman collection: https://documenter.getpostman.com/view/1540760/ocr-api-for-postman/RVfzh9aC