Quickstart

Installation

Node.js
Python

Install the Zerox package:

npm install zerox

System Dependencies

Zerox requires GraphicsMagick and Ghostscript for PDF processing. These are usually installed automatically, but you may need to install them manually:

sudo apt-get update
sudo apt-get install -y graphicsmagick ghostscript

Install the py-zerox package:

pip install py-zerox

System Dependencies

Zerox requires poppler for PDF processing. Install it based on your platform:

sudo apt-get update
sudo apt-get install -y poppler-utils

For detailed installation instructions by platform, see the pdf2image documentation.

Set Up API Keys

Zerox uses vision models from various providers. Set up your API key for your chosen provider:

OpenAI
Azure OpenAI
AWS Bedrock
Google Gemini

export OPENAI_API_KEY="your-api-key-here"

export AZURE_API_KEY="your-api-key-here"
export AZURE_API_BASE="https://your-endpoint.openai.azure.com"
export AZURE_API_VERSION="2023-05-15"

export AWS_ACCESS_KEY_ID="your-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
export AWS_REGION="us-east-1"

export GEMINI_API_KEY="your-api-key-here"

Basic Usage

Node.js
Python

Process a PDF from URL

import { zerox } from "zerox";

const result = await zerox({
  filePath: "https://omni-demo-data.s3.amazonaws.com/test/cs101.pdf",
  credentials: {
    apiKey: process.env.OPENAI_API_KEY,
  },
});

console.log(result.pages[0].content); // Markdown content
console.log(`Processed ${result.pages.length} pages`);
console.log(`Total tokens: ${result.inputTokens + result.outputTokens}`);

Process a Local File

import { zerox } from "zerox";
import path from "path";

const result = await zerox({
  filePath: path.resolve(__dirname, "./document.pdf"),
  credentials: {
    apiKey: process.env.OPENAI_API_KEY,
  },
});

// Access individual pages
result.pages.forEach((page) => {
  console.log(`Page ${page.page}:`);
  console.log(page.content);
});

Save Output to File

import { zerox } from "zerox";

const result = await zerox({
  filePath: "path/to/document.pdf",
  credentials: {
    apiKey: process.env.OPENAI_API_KEY,
  },
  outputDir: "./output", // Saves as output/document.md
});

console.log(`Saved to: ${result.fileName}.md`);

Process a PDF from URL

from pyzerox import zerox
import os
import asyncio

# Set up your API key
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

async def main():
    result = await zerox(
        file_path="https://omni-demo-data.s3.amazonaws.com/test/cs101.pdf",
        model="gpt-4o-mini"
    )
    
    print(result.pages[0].content)  # Markdown content
    print(f"Processed {len(result.pages)} pages")
    print(f"Total tokens: {result.input_tokens + result.output_tokens}")
    
    return result

# Run the async function
result = asyncio.run(main())

Process a Local File

from pyzerox import zerox
import os
import asyncio

os.environ["OPENAI_API_KEY"] = "your-api-key-here"

async def main():
    result = await zerox(
        file_path="./document.pdf",
        model="gpt-4o-mini"
    )
    
    # Access individual pages
    for page in result.pages:
        print(f"Page {page.page}:")
        print(page.content)
    
    return result

result = asyncio.run(main())

Save Output to File

from pyzerox import zerox
import os
import asyncio

os.environ["OPENAI_API_KEY"] = "your-api-key-here"

async def main():
    result = await zerox(
        file_path="./document.pdf",
        model="gpt-4o-mini",
        output_dir="./output"  # Saves as output/document.md
    )
    
    print(f"Saved to: {result.file_name}.md")
    return result

result = asyncio.run(main())

Understanding the Output

Zerox returns a structured object with the following information:

{
  completionTime: number,      // Time taken in milliseconds
  fileName: string,            // Sanitized filename without extension
  inputTokens: number,         // Total input tokens used
  outputTokens: number,        // Total output tokens used
  pages: [                     // Array of processed pages
    {
      page: number,            // Page number (1-indexed)
      content: string,         // Markdown content
      contentLength: number,   // Length of content
      status: "SUCCESS"        // Processing status
    }
  ],
  summary: {
    totalPages: number,
    ocr: {
      successful: number,
      failed: number
    }
  }
}

The pages array contains the Markdown content for each page. You can combine them or process them individually based on your needs.

Using Different Models

Zerox supports multiple vision model providers. Here’s how to use each:

Node.js
Python

import { zerox } from "zerox";
import { ModelOptions, ModelProvider } from "zerox/node-zerox/dist/types";

const result = await zerox({
  filePath: "path/to/file.pdf",
  modelProvider: ModelProvider.OPENAI,
  model: ModelOptions.OPENAI_GPT_4O,
  credentials: {
    apiKey: process.env.OPENAI_API_KEY,
  },
});

from pyzerox import zerox
import os

os.environ["OPENAI_API_KEY"] = "your-api-key"

result = await zerox(
    file_path="path/to/file.pdf",
    model="gpt-4o-mini"
)

Python uses LiteLLM under the hood, which supports 100+ LLMs. Model names follow the LiteLLM format: provider/model-name. Refer to the LiteLLM documentation for the complete list of supported models.

Common Configuration Options

Here are some frequently used options to customize Zerox’s behavior:

Node.js
Python

import { zerox } from "zerox";

const result = await zerox({
  filePath: "path/to/file.pdf",
  credentials: {
    apiKey: process.env.OPENAI_API_KEY,
  },
  
  // Process only specific pages (e.g., pages 1, 3, and 5)
  pagesToConvertAsImages: [1, 3, 5],
  
  // Control parallel processing
  concurrency: 5,
  
  // Maintain consistent formatting across pages (slower but better for tables)
  maintainFormat: true,
  
  // Save combined markdown to a file
  outputDir: "./output",
  
  // Keep temporary images after processing
  cleanup: false,
  
  // Add custom instructions for the vision model
  prompt: "Extract all tables and preserve their structure exactly.",
  
  // Adjust image quality
  imageDensity: 300,  // DPI for image conversion
  imageHeight: 2048,  // Maximum height in pixels
});

from pyzerox import zerox

result = await zerox(
    file_path="path/to/file.pdf",
    model="gpt-4o-mini",
    
    # Process only specific pages (e.g., pages 1, 3, and 5)
    select_pages=[1, 3, 5],
    
    # Control parallel processing
    concurrency=5,
    
    # Maintain consistent formatting across pages (slower but better for tables)
    maintain_format=True,
    
    # Save combined markdown to a file
    output_dir="./output",
    
    # Keep temporary images after processing
    cleanup=False,
    
    # Use a custom system prompt
    custom_system_prompt="Extract all tables and preserve their structure exactly.",
    
    # Adjust image quality
    image_density=300,  # DPI for image conversion
    image_height=(None, 2048),  # Maximum height in pixels
)

The maintainFormat option processes pages sequentially (not in parallel) because it passes the previous page’s output as context. This is slower but produces more consistent formatting, especially for tables that span multiple pages.

Next Steps

Structured Data Extraction

Learn how to extract specific fields using JSON schemas

Advanced Configuration

Explore all configuration options and fine-tuning

Node.js API Reference

Complete API documentation for all parameters

Examples

Real-world examples and use cases

Get Started

Installation

Core Concepts

Guides

Installation

System Dependencies

System Dependencies

Set Up API Keys

Basic Usage

Process a PDF from URL

Process a Local File

Save Output to File

Process a PDF from URL

Process a Local File

Save Output to File

Understanding the Output

Using Different Models

Common Configuration Options

Next Steps

Structured Data Extraction

Advanced Configuration

Node.js API Reference

Examples

Build docs developers (and LLMs) love

Get Started

Installation

Core Concepts

Guides

​Installation

​System Dependencies

​System Dependencies

​Set Up API Keys

​Basic Usage

​Process a PDF from URL

​Process a Local File

​Save Output to File

​Process a PDF from URL

​Process a Local File

​Save Output to File

​Understanding the Output

​Using Different Models

​Common Configuration Options

​Next Steps

Structured Data Extraction

Advanced Configuration

Node.js API Reference

Examples

Build docs developers (and LLMs) love

Installation

System Dependencies

System Dependencies

Set Up API Keys

Basic Usage

Process a PDF from URL

Process a Local File

Save Output to File

Process a PDF from URL

Process a Local File

Save Output to File

Understanding the Output

Using Different Models

Common Configuration Options

Next Steps