OCR PDF

​

Overview

• Text-based PDFs - Fast direct extraction using PDF text layer (sub-second per page)
• Scanned PDFs - Full OCR processing with Mistral Document AI (2-5 seconds per page)
• Mixed PDFs - Intelligently processes each page with the appropriate method
• Automatic detection - No need to specify document type

• Multi-page support - Process entire documents in one request
• Page-by-page results - Access text from individual pages
• Layout preservation - Maintains document structure and formatting
• High accuracy - State-of-the-art OCR for scanned documents
• Batch processing - Handle multiple pages efficiently
• Error resilience - Continues processing even if individual pages fail

• Contract analysis - Extract text from legal documents
• Invoice processing - Automate accounts payable workflows
• Document management - Digitize paper archives
• Compliance - Make scanned documents searchable
• Data extraction - Pull structured data from forms and reports
• Research - Extract text from academic papers
• Record keeping - Convert physical records to digital text
• Accessibility - Make scanned documents screen-reader compatible

​

How PDF Processing Works

1. PDF Analysis - Document is analyzed to determine content type
2. Method Selection - Each page is categorized as text-based or image-based
3. Text Extraction - For text PDFs, direct extraction from text layer
4. OCR Processing - For scanned pages, Mistral Document AI performs OCR
5. Page Aggregation - Results from all pages are combined
6. Output Generation - Returns full document text plus per-page breakdowns

• Text-based PDFs: < 1 second per page
• Scanned PDFs: 2-5 seconds per page
• Total time depends on page count and document type

​

Text-based vs Scanned PDFs

• Created digitally (Word, Google Docs, etc.)
• Contain selectable text layer
• Fast to process (no OCR needed)
• 100% accurate text extraction
• Examples: Digital forms, exported documents, e-books

• Created from physical documents via scanner
• Contains images of pages, not text
• Requires OCR processing
• Accuracy depends on scan quality
• Examples: Scanned contracts, historical documents, faxes

• Some pages digital, some scanned
• Common in compiled documents
• Each page processed optimally
• Examples: Reports with scanned attachments, annotated documents

​

Authentication

Authorization: Bearer ik_your_api_key_here

​

Request

​

Method 1: File Upload (multipart/form-data)

curl -X POST "https://api.incredible.one/ocr/pdf" \
  -H "Authorization: Bearer ik_your_api_key_here" \
  -F "file=@/path/to/document.pdf" \

​

Method 2: Base64 JSON

curl -X POST "https://api.incredible.one/ocr/pdf" \
  -H "Authorization: Bearer ik_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "pdf": "JVBERi0xLjcKCjEgMCBvYmoKPDwvVHlwZS...",
  }'

​

Request Parameters

​

Responses

​

Success Response (OCR Processing)

{
  "success": true,
  "text": "Extracted text from page 1...\n\nExtracted text from page 2...",
  "method": "mistral_document_ai",
  "pages_processed": 2,
  "total_pages": 10,
  "pages": [
    {
      "page_number": 1,
      "text": "Extracted text from page 1...",
      "success": true,
      "raw_response": {
        "pages": [
          {
            "index": 0,
            "markdown": "...",
            "text": "..."
          }
        ],
        "model": "mistral-document-ai-2505"
      }
    },
    {
      "page_number": 2,
      "text": "Extracted text from page 2...",
      "success": true,
      "raw_response": {
        "pages": [...]
      }
    }
  ]
}

​

Success Response (Text Extraction)

{
  "success": true,
  "text": "Extracted text from all pages...",
  "method": "text_extraction",
  "pages_processed": 5,
  "total_pages": 5,
  "pages": [
    {
      "page_number": 1,
      "text": "Extracted text from page 1...",
      "success": true
    },
    {
      "page_number": 2,
      "text": "Extracted text from page 2...",
      "success": true
    }
  ]
}

​

Field Reference

​

Top-Level Fields

• success boolean — Whether text extraction succeeded overall.
• text string — Concatenated text from all processed pages (pages separated by \n\n).
• method string — Extraction method: "mistral_document_ai" (OCR) or "text_extraction" (direct).
• pages_processed integer — Number of pages actually processed.
• total_pages integer — Total number of pages in the PDF.
• pages array — Per-page results (see below).

​

Per-Page Fields

• page_number integer — 1-indexed page number.
• text string — Extracted text from this page.
• success boolean — Whether extraction succeeded for this page.
• error string (optional) — Error message if extraction failed for this page.
• raw_response object (optional) — Complete raw response from Mistral Document AI for this page (only for OCR-processed pages).

​

Raw Response Object

• All fields returned by the API (not just markdown)
• Original structure and formatting
• Metadata and additional information
• Useful for advanced processing or debugging

​

Page Management

​

How Pages Are Processed

1. Text-based PDFs: Pages are extracted directly using fast text extraction
2. Scanned PDFs: Each page is converted to an image (at specified DPI) and processed through OCR individually

​

Accessing Per-Page Results

for page in result["pages"]:
    print(f"Page {page['page_number']}: {page['text']}")

​

Error Responses

​

Authentication Required

{
  "error": "Authentication required",
  "message": "API key must be provided in Authorization header as 'Bearer ik_your_api_key'"
}

​

Invalid API Key

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid, inactive, or expired"
}

​

Processing Error

{
  "success": false,
  "error": "Missing 'pdf' or 'file' field in request body"
}

​

Best Practices

• Use high-quality scans (300+ DPI for optimal results)
• Ensure pages are properly oriented before upload
• Remove password protection before processing
• Keep individual PDF files under 50MB for best performance
• For very large documents, consider splitting into sections

• Text-based PDFs process much faster than scanned PDFs
• Process large documents asynchronously with progress tracking
• Implement caching for frequently accessed documents
• Consider parallel processing for document batches
• Monitor processing time and adjust based on document type

• Always check the success field before using extracted text
• Review pages_processed vs total_pages to detect failures
• Implement retry logic for failed pages
• Validate critical data extracted from documents
• Maintain original PDFs for reference

• Cache OCR results to avoid reprocessing
• Prioritize text-based PDF conversion when creating documents
• Batch similar documents together for efficiency
• Monitor API usage and optimize based on patterns

​

Integration Patterns

def process_uploaded_pdf(pdf_file):
    """Process uploaded PDF and store extracted text"""
    response = requests.post(
        "https://api.incredible.one/ocr/pdf",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": pdf_file}
    )
    
    result = response.json()
    
    if result["success"]:
        # Store full document text
        document_text = result["text"]
        
        # Store per-page text for navigation
        pages = {
            page["page_number"]: page["text"]
            for page in result["pages"]
            if page.get("success")
        }
        
        # Save to database
        save_document(
            text=document_text,
            pages=pages,
            method=result["method"],
            page_count=result["pages_processed"]
        )
        
        return document_text
    else:
        raise Exception(f"PDF processing failed: {result['error']}")

def extract_invoice_data(pdf_path):
    """Extract and structure invoice data from PDF"""
    # Step 1: Extract text with OCR
    with open(pdf_path, "rb") as f:
        ocr_result = requests.post(
            "https://api.incredible.one/ocr/pdf",
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"file": f}
        ).json()
    
    if not ocr_result["success"]:
        return None
    
    # Step 2: Structure the extracted text
    invoice_schema = {
        "type": "object",
        "properties": {
            "invoice_number": {"type": "string"},
            "date": {"type": "string"},
            "vendor": {"type": "string"},
            "total": {"type": "number"},
            "line_items": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "description": {"type": "string"},
                        "amount": {"type": "number"}
                    }
                }
            }
        }
    }
    
    structured_data = client.answer(
        query="Extract invoice details",
        response_format=invoice_schema,
        context=ocr_result["text"]
    )
    
    return structured_data

import concurrent.futures

def process_pdf_batch(pdf_paths, max_workers=5):
    """Process multiple PDFs in parallel"""
    def process_single(path):
        with open(path, "rb") as f:
            response = requests.post(
                "https://api.incredible.one/ocr/pdf",
                headers={"Authorization": f"Bearer {API_KEY}"},
                files={"file": f}
            )
        return path, response.json()
    
    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
        futures = [executor.submit(process_single, path) for path in pdf_paths]
        results = {}
        
        for future in concurrent.futures.as_completed(futures):
            path, result = future.result()
            results[path] = result
    
    return results

def create_searchable_archive(pdf_directory):
    """Convert PDF archive to searchable text database"""
    import os
    from pathlib import Path
    
    documents = []
    
    for pdf_file in Path(pdf_directory).glob("*.pdf"):
        print(f"Processing: {pdf_file.name}")
        
        with open(pdf_file, "rb") as f:
            result = requests.post(
                "https://api.incredible.one/ocr/pdf",
                headers={"Authorization": f"Bearer {API_KEY}"},
                files={"file": f}
            ).json()
        
        if result["success"]:
            documents.append({
                "filename": pdf_file.name,
                "text": result["text"],
                "pages": result["pages_processed"],
                "method": result["method"],
                "page_data": result["pages"]
            })
            print(f"✓ Extracted {result['pages_processed']} pages")
        else:
            print(f"✗ Failed: {result['error']}")
    
    # Save to searchable database or index
    index_documents(documents)
    return documents

​

Common Issues and Solutions

• Solution: Check individual page errors in the pages array
• Solution: Retry failed pages separately
• Solution: Verify PDF is not corrupted
• Solution: Check if pages are blank or contain only images

• Solution: Verify PDF quality (for scanned documents, rescan at higher DPI)
• Solution: Check if pages are properly oriented
• Solution: Ensure text is clearly visible in original
• Solution: Try preprocessing to improve contrast

• Solution: Scanned PDFs take longer than text-based PDFs (expected)
• Solution: Process large documents asynchronously
• Solution: Consider splitting very large documents
• Solution: Implement parallel processing for batches

• Solution: Increase request timeout (recommend 5+ minutes for large documents)
• Solution: Split PDF into smaller chunks
• Solution: Implement retry logic with exponential backoff
• Solution: Process pages in batches

• Solution: Check if PDF is password protected
• Solution: Verify PDF is not corrupted
• Solution: Try opening in PDF reader to confirm text layer exists
• Solution: Check PDF version compatibility

​

Performance Guidelines

• Small (1-10 pages): Process synchronously, < 30 seconds
• Medium (11-50 pages): Consider async, 1-5 minutes
• Large (51-200 pages): Always async, 5-20 minutes
• Very Large (200+ pages): Split or batch process, 20+ minutes

• Safe to process multiple small PDFs in parallel
• Limit concurrent requests based on your rate limits
• Use threading/async for batch operations
• Monitor API response times and adjust concurrency

• Cache results for frequently accessed documents
• Store extracted text in database for quick retrieval
• Use CDN or fast storage for original PDFs
• Implement smart retry logic for transient failures
• Monitor costs and optimize based on document types

​

Advanced Use Cases

1. Extract text with OCR
2. Use Answer API with schema to structure form data
3. Validate extracted values

• Storing raw_response for detailed metadata
• Logging processing timestamps and methods
• Tracking which pages used OCR vs text extraction
• Archiving original PDFs alongside extracted text