FastOCR API

1. 1Create an API key

   Sign in and create a key in the developer console. You accept the API terms with your first key. The Free plan includes 20 free pages per month, shared with PDFs on the website. Paid plans share their Document OCR allowance with the API too. Every example reads the key from FASTOCR_API_KEY.

   TerminalbashCopy

   pip install fastocr-sdk
   export FASTOCR_API_KEY="your_api_key"

   The first line installs the Python SDK, fastocr-sdk. It is not related to the fastocr package on PyPI. Node.js 18+ and cURL need nothing extra.

2. 2Run the snippet

   Each tab extracts the text of scan.pdf and saves or prints it.

   PythonNode.jsHTTP

   PythonCopy

   from fastocr_sdk import FastOCR
   
   # Reads the key from the FASTOCR_API_KEY environment variable.
   with FastOCR() as client:
       text = client.extract_text("scan.pdf")
       print(text)

3. 3Read the result

   The Node.js and HTTP tabs poll GET /v1/documents/{id} until the document finishes. A completed document looks like this:

   200 OKJSONCopy

   {
     "id": "3f9c2b1e-7d54-4a8e-9b0a-5c1e8d2f6a47",
     "status": "completed",
     "external_id": "INV-1001",
     "pages_billed": 10,
     "pages_total": 10,
     "pages_processed": 10,
     "is_truncated": false,
     "outputs": {
       "text": { "available": true },
       "pdf": { "available": true }
     }
   }

   Then GET /v1/documents/{id}/output?format=text (or format=pdf) returns a download link that works for one hour. The Document OCR reference describes each request.

Prefer a package to raw HTTP? These call the same API with the same key.

Any signed-in FastOCR account can create an API key and start right away. The Free plan includes 20 free pages per month, shared with PDFs on the website. Paid plans share their Document OCR allowance with the API too.

1. 1Sign in and create an API key in the developer console. You accept the API terms with your first key.
2. 2Run the quickstart with your key in FASTOCR_API_KEY.
3. 3When you need more document pages, buy a Page Pack on the pricing page.

Pack sizes and rates are on the pricing page. A document that runs out of pages fails with buy_pages. After you buy pages, call /start again on the same document.

The Document OCR API has five steps. Create a document, upload the PDF or image, start processing, poll for completion, and download the result.

Every request sends your API key in the Authorization header as Bearer <key>. Create API keys in the developer console. Each API key starts with fok_live_.

from fastocr_sdk import FastOCR

client = FastOCR(api_key="fok_live_abc123...")

const response = await fetch('https://api.fastocr.org/v1/documents', {
  headers: { Authorization: 'Bearer fok_live_abc123...' },
});

curl https://api.fastocr.org/v1/documents \
  -H "Authorization: Bearer fok_live_abc123..."

The API gateway returns authentication failures before the request reaches the API.

• The body always has a message. On newer deployments it also has an error object with type: "gateway_error".
• A request with no Authorization header returns 401 (code unauthorized).
• A header with an unknown, malformed, or revoked API key returns 403, not 401 (code access_denied).
• If error is absent, use the HTTP status and message.
• The gateway caches API key checks for up to 60 seconds. A revoked API key can keep working for that time.

List endpoints return one page of results and an opaque cursor. Send the cursor back to get the next page.

from fastocr_sdk import FastOCR

with FastOCR() as client:
    cursor = None
    while True:
        page = client.documents.list(limit=100, cursor=cursor)
        for document in page.documents:
            print(document.id, document.status)
        cursor = page.next_cursor
        if cursor is None:
            break

const headers = { Authorization: `Bearer ${process.env.FASTOCR_API_KEY}` };
let cursor = null;
do {
  const params = new URLSearchParams({ limit: '100' });
  if (cursor) params.set('cursor', cursor);
  const response = await fetch(`https://api.fastocr.org/v1/documents?${params}`, { headers });
  const page = await response.json();
  for (const document of page.documents) console.log(document.id, document.status);
  cursor = page.next_cursor;
} while (cursor);

curl -s -G "https://api.fastocr.org/v1/documents" \
  -H "Authorization: Bearer $FASTOCR_API_KEY" \
  --data-urlencode "limit=100" \
  --data-urlencode "cursor=<next_cursor>"

The API lists documents newest first in the documents array. When next_cursor is null, there are no more pages.

Each page holds up to limit documents that match your filters. On a very long list, a page can be shorter while next_cursor is still set. Follow the cursor until it is null. A cursor expires 24 hours after the API issues it.

The updated_since filter

updated_since accepts an ISO 8601 date or datetime. The value can end in Z, have any offset, or have no offset. The API reads a value with no offset as UTC.

A document matches when its last status change is at or after the value. If the status never changed, the creation time applies. A date alone, such as 2026-10-01, works.

The API does not reject a value that is not a date. It compares that value as text.

Create endpoints need an Idempotency-Key header. The API matches the header name without regard to case.

A client can retry a request with the same key and body within about 24 hours. The API then returns the original 201. If the original upload_url expired while the document is still awaiting_upload, the response carries a fresh upload_url and expires_at.

The API compares the body on filename, size_bytes, sha256, and external_id. If the body is different, the API returns 409 idempotency_key_conflict.

from fastocr_sdk import FastOCR

with FastOCR() as client:
    created = client.documents.create(
        "scan.pdf", 1048576, idempotency_key="invoice-2026-10-001"
    )

const response = await fetch('https://api.fastocr.org/v1/documents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FASTOCR_API_KEY}`,
    'Idempotency-Key': 'invoice-2026-10-001',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ filename: 'scan.pdf', size_bytes: 1048576 }),
});

curl -X POST https://api.fastocr.org/v1/documents \
  -H "Authorization: Bearer $FASTOCR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filename":"scan.pdf","size_bytes":1048576}'

• Files: a PDF up to 1 GiB (1,073,741,824 bytes), or a PNG, JPG, JPEG, GIF, WebP or BMP image up to 20 MiB (20,971,520 bytes). An image counts as one page.
• Concurrency: an account can process 2 documents at the same time. An account with an API contract, or with 10,000 or more pages bought, can process 10. Very large documents may take longer to start.
  A /start request over the limit returns 429 concurrency_limit with a Retry-After header. The document stays awaiting_upload. Wait the Retry-After seconds, then call POST /start again.
• Request rate: each API key and each source address has its own request rate limit on /v1, in addition to the shared throttle of the API gateway. A request above a limit returns 429 with the same body shape as the authentication errors (code throttled when the gateway produced it; a per-key or per-address 429 has message only and a Retry-After header). Wait the Retry-After seconds, or back off, then retry.
• Pages: The Free plan includes 20 free pages per month, shared with PDFs on the website. Paid plans share their Document OCR allowance with the API too. Page Packs add pages to the same balance, and they work on the website too. Check what is left with GET /v1/balance.
  The API reserves pages when it knows the real page count. This is after /start returns. If fewer pages remain than the PDF has, the document finishes as partial. The API then processes the first pages only. If no pages remain, the document fails with buy_pages.

A document that fails during processing returns HTTP 200 with the status failed and an error object. The HTTP status describes the request. It does not describe the work.

• Match on code. Do not match on message. FastOCR can change messages without notice.
• FastOCR will add new codes. Treat an unknown code as processing_failed.
• Only buy_pages lets you start a failed document again. A document that runs out of pages fails with buy_pages. After you buy pages, call /start again on the same document.

Document failure codes

{
  "id": "3f9c2b1e-7d54-4a8e-9b0a-5c1e8d2f6a47",
  "status": "failed",
  "external_id": null,
  "error": {
    "type": "processing_error",
    "code": "timeout",
    "message": "This file took too long to process. Please try again.",
    "retryable": true
  }
}

Request errors

A rejected request returns a 4xx or 5xx status. The body has an error object with type, code, message, and request_id. Include the request_id when you contact support.

The type is invalid_request, not_found, conflict, rate_limit, or error.

{
  "error": {
    "type": "invalid_request",
    "code": "unsupported_file_type",
    "message": "Only PDF, PNG, JPG, JPEG, GIF, WebP and BMP files are supported",
    "request_id": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}

Gateway errors

The API gateway returns 401, 403, and 429 errors before the request reaches the API. The body has a message and, on newer deployments, an error object with type: "gateway_error". See Authentication. Treat an unknown code as a new condition for its HTTP status.

Handle errors in Python

The SDK raises DocumentFailedError for a failed document and RateLimitError (with retry_after) for a 429. All SDK errors extend FastOCRError.

extract_text raises PartialResultError when the account runs out of pages partway through, so it never returns truncated text without telling you. The request itself succeeded, so PartialResultError has no status_code, and its code is partial_result. Pass allow_partial=True to receive the text of the processed pages instead.

from fastocr_sdk import (
    DocumentFailedError,
    FastOCR,
    FastOCRError,
    PartialResultError,
    RateLimitError,
)

with FastOCR() as client:
    try:
        text = client.extract_text("scan.pdf")
    except PartialResultError as error:
        print(error.pages_processed, error.pages_total)
        text = client.documents.get_text(error.document_id)
    except DocumentFailedError as error:
        print(error.code, error.retryable, error.document_id)
    except RateLimitError as error:
        print(error.retry_after)
    except FastOCRError as error:
        print(error.status_code, error.code, error.request_id)

/v1 is additive-only. FastOCR adds fields. It never renames, retypes, or deletes a field. Status codes and existing error codes do not change.

New fields, new statuses, and new error codes may appear. Clients must ignore unknown fields. Clients must treat an unknown error code as processing_failed (document errors) or by its HTTP status (request errors).

A breaking change would ship as /v2. /v1 would stay available for at least 6 months after that.