Skip to main content

​
Basic Usage

from datalab_sdk import DatalabClient

client = DatalabClient()

# Convert to markdown (default)
result = client.convert("document.pdf")
print(result.markdown)

# Convert from URL
result = client.convert(file_url="https://example.com/document.pdf")
print(result.markdown)

​
Conversion Options

Use ConvertOptions to control the conversion: 
from datalab_sdk import DatalabClient, ConvertOptions

client = DatalabClient()

options = ConvertOptions(
    output_format="markdown",     # Output format
    mode="balanced",              # Processing mode
    paginate=True,                # Add page delimiters
    max_pages=10,                 # Limit pages processed
    page_range="0-5,10",          # Specific pages (0-indexed)
)

result = client.convert("document.pdf", options=options)

​
All Options

OptionTypeDefaultDescription
output_formatstr"markdown"Output format: "markdown", "html", "json", "chunks"
modestr"fast"Processing mode: "fast", "balanced", "accurate"
paginateboolFalseAdd page delimiters to output
max_pagesintNoneMaximum number of pages to process
page_rangestrNoneSpecific pages to process (e.g., "0-5,10,15-20"). For spreadsheets, filters by sheet index.
skip_cacheboolFalseSkip cached results, force reprocessing
disable_image_extractionboolFalseDon’t extract images from document
disable_image_captionsboolFalseDon’t generate captions for images
token_efficient_markdownboolFalseOptimize markdown output for LLM token usage
fence_synthetic_captionsboolFalseFence synthetic image captions
include_markdown_in_chunksboolFalseInclude markdown in chunks/JSON output
save_checkpointboolFalseSave intermediate checkpoint for reuse
extrasstrNoneComma-separated features: "track_changes", "chart_understanding", "extract_links", "table_row_bboxes", "infographic", "new_block_types"
add_block_idsboolFalseAdd block IDs to HTML output for citations
keep_spreadsheet_formattingboolFalsePreserve spreadsheet styling in HTML output
webhook_urlstrNoneOverride account webhook URL for this request
additional_configdictNoneAdditional configuration options
Use save_checkpoint=True to save the parsed document state. Then call client.extract() or client.segment() with the returned checkpoint_id to run extraction or segmentation without re-parsing.

​
Processing Modes

ModeDescriptionUse Case
fastLowest latency (default)Simple documents, real-time applications
balancedBalance of speed and accuracyGeneral use
accurateHighest accuracyComplex layouts, tables, figures

​
Output Formats

FormatDescription
markdownClean markdown with headers, lists, tables
htmlStructured HTML preserving layout
jsonBlock-level structure with bounding boxes
chunksPre-chunked output for RAG applications

​
Conversion Result

The ConversionResult object contains the converted content and metadata: 
result = client.convert("document.pdf")

# Access content based on output format
print(result.markdown)        # Markdown output
print(result.html)            # HTML output
print(result.json)            # JSON structure
print(result.chunks)          # Chunked output

# Metadata
print(result.success)         # True if conversion succeeded
print(result.page_count)      # Number of pages processed
print(result.images)          # Dict of extracted images (filename -> base64)
print(result.metadata)        # Document metadata
print(result.parse_quality_score)  # Quality score (0-5)
print(result.cost_breakdown)  # Cost in cents

​
Result Fields

FieldTypeDescription
successboolWhether conversion succeeded
markdownstrMarkdown output (if format is markdown)
htmlstrHTML output (if format is html)
jsondictJSON output (if format is json)
chunksdictChunked output (if format is chunks)
imagesdictExtracted images as {filename: base64_data}
metadatadictDocument metadata
page_countintNumber of pages processed
parse_quality_scorefloatQuality score from 0-5
cost_breakdowndictCost details (list_cost_cents, final_cost_cents)
checkpoint_idstrCheckpoint ID if save_checkpoint was True
errorstrError message if conversion failed

​
Saving Output

Save the conversion result to files: 
# Save during conversion
result = client.convert("document.pdf", save_output="output/document")

# Or save afterward
result.save_output("output/document", save_images=True)
This creates:
  • document.md (or .html, .json based on format)
  • document_images/ directory with extracted images (if save_images=True)

​
Async Usage

For high-throughput applications: 
import asyncio
from datalab_sdk import AsyncDatalabClient, ConvertOptions

async def convert_documents():
    async with AsyncDatalabClient() as client:
        options = ConvertOptions(mode="fast", max_pages=5)
        result = await client.convert("document.pdf", options=options)
        return result.markdown

markdown = asyncio.run(convert_documents())

​
Polling Configuration

Control polling behavior for long-running conversions: 
result = client.convert(
    "large_document.pdf",
    max_polls=600,        # Maximum polling attempts (default: 300)
    poll_interval=2,      # Seconds between polls (default: 1)
)

​
Special Features

​
Track Changes (Word Documents)

Extract tracked changes and comments from DOCX files: 
options = ConvertOptions(
    output_format="html",
    extras="track_changes",
)
result = client.convert("contract.docx", options=options)
# HTML contains <ins>, <del>, and <comment> tags

​
Chart Understanding

Extract data from charts and graphs: 
options = ConvertOptions(
    extras="chart_understanding",
)
result = client.convert("report.pdf", options=options)

​
Block IDs for Citations

Add block IDs for tracking content back to source locations: 
options = ConvertOptions(
    output_format="html",
    add_block_ids=True,
)
result = client.convert("document.pdf", options=options)
# HTML elements include data-block-id attributes

​
Structured Extraction

For structured data extraction, use the dedicated client.extract() method.

​
Next Steps

Structured Extraction Recipe

Extract structured data from documents using JSON schemas.

Batch Processing

Process multiple documents efficiently in parallel.

Form Filling SDK

Programmatically fill PDF and image forms with field data.

CLI Reference

Convert documents from the command line.