Parse Document

​

Overview

​

Request

​

Configuration Best Practices

{
  "use_high_resolution": true,
  "segmentation_method": "smart_layout_detection",
  "ocr_mode": "force_ocr",
  "merge_tables": true,
  "validate_segments": ["Table", "Picture", "Formula"],
  "segment_analysis": {
    "Table": {
      "html": "LLM",
      "markdown": "LLM",
      "extended_context": true,
      "crop_image": "All",
      "model_id": "us_table_v2"
    }
  }
}

{
  "use_high_resolution": false,
  "segmentation_method": "page_by_page",
  "ocr_mode": "auto_ocr",
  "merge_tables": false
}

{
  "merge_tables": true,
  "keep_segment_types": "table,picture",
  "validate_segments": ["Table", "Picture"],
  "segmentation_method": "smart_layout_detection",
  "ocr_mode": "auto_ocr",
  "segment_analysis": {
    "Table": {
      "html": "LLM",
      "markdown": "LLM",
      "model_id": "us_table_v2"
    }
  }
}

{
  "merge_tables": true,
  "keep_segment_types": "table",
  "validate_segments": ["Table"],
  "output_fields": {
    "html": true,
    "markdown": true,
    "ocr": false,
    "image": false,
    "content": true,
    "bbox": false,
    "confidence": false
  }
}

{
  "use_high_resolution": true,
  "segmentation_method": "smart_layout_detection",
  "ocr_mode": "auto_ocr",
  "xml_citation": true
}

{
  "use_high_resolution": true,
  "ocr_mode": "force_ocr",
  "segmentation_method": "smart_layout_detection"
}

{
  "output_fields": {
    "html": false,
    "markdown": false,
    "ocr": false,
    "image": false,
    "llm": false,
    "content": true,
    "bbox": false,
    "confidence": false,
    "embed": true
  }
}

{
  "output_fields": {
    "html": false,
    "markdown": true,
    "ocr": false,
    "image": false,
    "llm": false,
    "content": true,
    "bbox": true,
    "confidence": false,
    "embed": true
  }
}

​

Parameter Details

​

File Input Options

1. Direct File Upload (file parameter): Upload the document file directly as multipart/form-data
2. Presigned URL (url parameter): Provide a publicly accessible URL or presigned URL to the document

• You must provide either file or url, but not both
• When using url, the document will be downloaded from the provided URL before processing
• Presigned URLs are ideal for documents already stored in cloud storage (S3, GCS, Azure Blob, etc.)
• The URL must be publicly accessible or include necessary authentication parameters (e.g., S3 presigned URLs with signatures)
• Supported formats are the same for both methods: PDF, images (PNG, JPEG, TIFF), and office documents (PPT, PPTX, DOC, DOCX, XLS, XLSX)

• Documents already stored in cloud storage
• Avoiding duplicate file uploads
• Integration with existing document management systems
• Processing large files without upload overhead

​

Segmentation Method

• "smart_layout_detection" (default): Analyzes pages for layout elements (e.g., Table, Picture, Formula, etc.) using bounding boxes. Provides fine-grained segmentation and better chunking for complex documents.
• "page_by_page": Treats each page as a single segment. Faster processing, ideal for simple documents without complex layouts.

​

OCR Mode

• "auto_ocr" (default): Intelligently determines when OCR is needed based on the document content. Balances accuracy and performance.
• "force_ocr": Applies OCR to all content regardless of existing text layer. Use this for scanned documents or when maximum text extraction is required.

​

Table Merging

• Analyzes consecutive table segments across pages
• Identifies tables with matching column headers
• Merges them into a single unified table structure
• Preserves table formatting and data integrity

• Multi-Page Financial Statements: Consolidate P&L statements or balance sheets spanning multiple pages
• Large Data Tables: Merge inventory lists, transaction records, or data sets split across pages
• Reports with Continuation Tables: Automatically combine tables marked with “continued on next page”

{
  "merge_tables": true
}

• Simplified Data Processing: Work with complete tables instead of fragments
• Better Context: Maintain full table context for analysis and extraction
• Reduced Post-Processing: Eliminates need for manual table stitching

​

Citation Extraction (Research Papers)

• Extracts structured bibliography from the document
• Identifies in-text citation references (e.g., “Chen et al., 2021”)
• Hyperlinks citations in the markdown output to their bibliography entries
• Returns structured citation metadata in the response

{
  "xml_citation": true
}

{
  "metadata": {
    "citations": [
      {
        "id": 1,
        "title": "Deep Learning for NLP",
        "authors": ["John Smith", "Jane Doe"],
        "year": "2021",
        "journal": "Nature",
        "volume": "15",
        "pages": "123-145",
        "doi": "10.1000/example"
      }
    ],
    "document_metadata": {
      "title": "Document Title",
      "authors": ["Author Name"]
    }
  }
}

• Original: "As shown by Chen et al. (2021)..."
• Enhanced: "As shown by [Chen et al. (2021)](#ref-5)..."

​

Content Type Filtering

• Accepts a comma-separated list of segment types (case-insensitive)
• Filters segments after processing is complete
• Removes chunks that have no segments after filtering

• "all" (default): Include all segment types
• "table": Only table segments
• "picture": Only image/graphic segments
• "table,picture": Tables and pictures only
• "table,formula": Tables and formulas only
• Custom combinations using any segment type

• table, picture, formula, text, sectionheader, title, listitem, caption, footnote, pageheader, pagefooter

{
  "keep_segment_types": "table,picture"
}

• Tables Only: Extract only tabular data from financial documents
• Pictures Only: Extract charts, graphs, and diagrams for visual analysis
• Tables + Pictures: Get structured data and visualizations, skip text content
• Custom Combinations: Mix any segment types based on your needs

• Reduced Response Size: Filter out unwanted content before receiving results
• Faster Processing: Less data to transfer and parse
• Focused Extraction: Get only the content types you need
• Cost Optimization: Smaller responses reduce bandwidth usage

​

Output Fields Configuration

• html (default: true): Include HTML representation of segments
• markdown (default: true): Include Markdown representation of segments
• ocr (default: true): Include OCR results with bounding boxes and confidence scores
• image (default: true): Include cropped segment images (base64 encoded)
• llm (default: true): Include LLM-generated content and descriptions
• content (default: true): Include text content of segments
• bbox (default: true): Include bounding box coordinates
• confidence (default: true): Include confidence scores for segments
• embed (default: true): Include embed text in chunk responses

{
  "html": false,
  "markdown": true,
  "ocr": false,
  "image": false,
  "llm": false,
  "content": true,
  "bbox": true,
  "confidence": false,
  "embed": true
}

• Reduced Response Size: Excluding large fields like image and html can significantly reduce payload size
• Faster Processing: Less data to serialize and transfer
• Cost Optimization: Smaller responses reduce bandwidth costs
• Selective Data: Only retrieve the fields you need for your use case

• Minimal Response: Set most fields to false when you only need basic content
• Text-Only Processing: Exclude image, ocr, and llm when processing text content
• Embedding Generation: Include only content and embed when generating embeddings
• Full Analysis: Keep all fields enabled (default) for comprehensive document analysis

​

Segment Analysis Configuration

• Table: Tabular data segments
• Picture: Image and graphic segments
• Formula: Mathematical equations
• Title: Document titles
• SectionHeader: Section headers
• Text: Regular text content
• ListItem: List items
• Caption: Image captions
• Footnote: Footnotes
• PageHeader: Page headers
• PageFooter: Page footers
• Page: Full page segments

• html: Generation strategy for HTML representation
  • "Auto" (default): Automatically determine the best method
  • "LLM": Use LLM to generate HTML
• markdown: Generation strategy for Markdown representation
  • "Auto" (default): Automatically determine the best method
  • "LLM": Use LLM to generate Markdown
• content_source: Defines which field should populate the content field in the response
  • "OCR" (default): Use OCR text for content
  • "HTML": Use HTML representation as content
  • "Markdown": Use Markdown representation as content
• model_id (Table segments only): Specifies which AI model to use for table processing
  • "us_table_v1": Standard table processing model
  • "us_table_v2": Enhanced table processing model with improved accuracy

{
  "Table": {
    "html": "LLM",
    "markdown": "LLM",
    "content_source": "HTML",
    "model_id": "us_table_v2"
  },
  "Picture": {
    "html": "LLM",
    "markdown": "LLM",
    "content_source": "Markdown"
  }
}

• When content_source is set to "HTML", the content field will contain the HTML representation, and the separate html and markdown fields will be empty
• When content_source is set to "Markdown", the content field will contain the Markdown representation, and the separate html and markdown fields will be empty
• When content_source is set to "OCR" (default), the content field contains OCR text, and html and markdown fields are populated separately

• HTML as Content: Set content_source: "HTML" for Table segments when you want HTML-formatted table data directly in the content field
• Markdown as Content: Set content_source: "Markdown" for Picture segments when you want Markdown-formatted descriptions in the content field
• LLM-Enhanced Output: Use "LLM" for both html and markdown generation strategies to get AI-enhanced representations in those fields

​

Response

​

Document Analysis Features

​

Text Extraction

​

Image Recognition

​

Table Parsing

​

OCR Processing

​

Section Detection

​

Bounding Box Information

​

Advanced Content Processing

• LLM-Enhanced Analysis: Uses language models for better content understanding
• Multi-Format Output: Generates HTML, Markdown, and plain text versions
• Context-Aware Processing: Maintains document context across segments
• Intelligent Chunking: Creates semantically meaningful document chunks

curl -X 'POST' \
  'https://prod.visionapi.unsiloed.ai/parse' \
  -H 'accept: application/json' \
  -H 'api-key: your-api-key' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@document.pdf;type=application/pdf' \
  -F 'use_high_resolution=true' \
  -F 'segmentation_method=smart_layout_detection' \
  -F 'ocr_mode=auto_ocr' \
  -F 'ocr_engine=UnsiloedHawk' \
  -F 'validate_table_segments=false' \
  -F 'merge_tables=true' \
  -F 'keep_segment_types=all' \
  -F 'validate_segments=["Table","Picture","Formula"]' \
  -F 'segment_analysis={"Table":{"html":"LLM","markdown":"LLM","extended_context":true,"crop_image":"All","model_id":"us_table_v2"}}'

# Alternative: Use presigned URL instead of file upload
# Replace the file parameter with url parameter:
# -F 'url=https://your-bucket.s3.amazonaws.com/document.pdf?signature=...' \

{
  "job_id": "e77a5c42-4dc1-44d0-a30e-ed191e8a8908",
  "status": "Starting",
  "file_name": "document.pdf",
  "created_at": "2025-07-18T10:42:10.545832520Z",
  "message": "Task created successfully. Use GET /parse/{job_id} to check status and retrieve results.",
  "credit_used": 5,
  "quota_remaining": 23695,
  "merge_tables": false
}

​

Retrieving Results

curl -X 'GET' \
  'https://prod.visionapi.unsiloed.ai/parse/{job_id}' \
  -H 'accept: application/json' \
  -H 'api-key: your-api-key'

import requests
import time

def get_parse_results(job_id, api_key):
    """Monitor job and retrieve results when complete"""
    
    headers = {"api-key": api_key}
    status_url = f"https://prod.visionapi.unsiloed.ai/parse/{job_id}"
    
    # Poll for completion
    while True:
        response = requests.get(status_url, headers=headers)
        
        if response.status_code == 200:
            status_data = response.json()
            print(f"Job Status: {status_data['status']}")
            
            if status_data['status'] == 'Succeeded':
                return status_data  # Results are included in the same response
                    
            elif status_data['status'] == 'Failed':
                raise Exception(f"Job failed: {status_data.get('message', 'Unknown error')}")
                
        time.sleep(5)  # Check every 5 seconds

# Usage
job_id = "e77a5c42-4dc1-44d0-a30e-ed191e8a8908"
results = get_parse_results(job_id, "your-api-key")

​

Expected Results Structure

{
  "job_id": "04a7a6d8-5ef7-465a-b22a-8a98e7104dd9",
  "status": "Succeeded",
  "created_at": "2025-10-22T06:51:16.870302Z",
  "started_at": "2025-10-22T06:51:16.966136Z",
  "finished_at": "2025-10-22T06:57:19.821541Z",
  "total_chunks": 25,
  "chunks": [
    {
      "segments": [
        {
          "segment_type": "Title",
          "content": "Disinvestment of IFCI's entire stake in Assets Care & Reconstruction Enterprise Ltd (ACRE)",
          "image": null,
          "page_number": 1,
          "segment_id": "cc5f8dff-31be-4ccf-885d-4f9062fcee17",
          "confidence": 0.90187776,
          "page_width": 1191.0,
          "page_height": 1684.0,
          "html": "<h1>Disinvestment of IFCI's entire stake in Assets Care & Reconstruction Enterprise Ltd (ACRE)</h1>",
          "markdown": "# Disinvestment of IFCI's entire stake in Assets Care & Reconstruction Enterprise Ltd (ACRE)",
          "bbox": {
            "left": 72.92226,
            "top": 62.030334,
            "width": 230.36308,
            "height": 55.395317
          },
          "ocr": [
            {
              "bbox": {
                "left": 63.753525,
                "top": 5.395447,
                "width": 164.45312,
                "height": 42.757812
              },
              "text": "Disinvestment",
              "confidence": 0.9999992
            }
          ]
        },
        {
          "segment_type": "Text",
          "content": "Background and context information about the disinvestment process...",
          "image": null,
          "page_number": 1,
          "segment_id": "9d60e48b-77ba-4a23-a0ac-95ee13c615ec",
          "confidence": 0.88558982,
          "page_width": 1191.0,
          "page_height": 1684.0,
          "html": "<p>Background and context information about the disinvestment process...</p>",
          "markdown": "Background and context information about the disinvestment process...",
          "bbox": {
            "left": 486.9685,
            "top": 139.61847,
            "width": 241.29932,
            "height": 48.451706
          },
          "ocr": [
            {
              "bbox": {
                "left": 50.9729,
                "top": 3.4557495,
                "width": 46.046875,
                "height": 19.734375
              },
              "text": "Background",
              "confidence": 0.99999654
            }
          ]
        }
      ]
    }
  ]
}

​

Segment Types

​

Picture

​

SectionHeader

​

Text

​

Table

• us_table_v1: Standard table processing model
• us_table_v2: Enhanced table processing model with improved accuracy

​

Caption

​

Formula

​

Title

​

Footnote

​

ListItem

​

Error Handling

​

Common Error Scenarios

1. Invalid API Key: Authentication failed
2. File Too Large: File exceeds size limits
3. Invalid Configuration: Malformed processing parameters
4. Server Error: Internal processing error
5. Processing Timeout: Task took too long to complete
6. Missing File or URL: Neither file nor url parameter provided
7. Both File and URL Provided: Cannot provide both file and url simultaneously
8. Invalid URL: URL is not accessible or malformed
9. URL Download Failed: Unable to download document from provided URL
10. Insufficient Quota (402): Not enough page credits remaining.
11. Usage Limit Exceeded (429): Billing usage cap reached. Returns plain text: Usage limit exceeded. No Retry-After header.
12. Rate Limit Exceeded (429): Org exceeded 60 requests / 60s sliding window. Returns plain text: Rate limit exceeded. A Retry-After header may be present depending on the infrastructure layer (Envoy/Istio), but is not set by the application.