# docling-api: Scalable Document to Markdown Conversion Server

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/drmingler-docling-api
Generated for open source discovery and AI-assisted research.

docling-api is a robust and scalable backend server designed for converting a wide array of document formats, including PDFs, DOCX, and images, into Markdown. Built with FastAPI, Celery, and Redis, it supports both CPU and GPU processing, making it ideal for large-scale workflows requiring efficient text, table, and image extraction, along with OCR capabilities. This service offers flexible synchronous and asynchronous API endpoints for single and batch document conversions.

GitHub: https://github.com/drmingler/docling-api
OSRepos URL: https://osrepos.com/repo/drmingler-docling-api

## Summary

docling-api is a robust and scalable backend server designed for converting a wide array of document formats, including PDFs, DOCX, and images, into Markdown. Built with FastAPI, Celery, and Redis, it supports both CPU and GPU processing, making it ideal for large-scale workflows requiring efficient text, table, and image extraction, along with OCR capabilities. This service offers flexible synchronous and asynchronous API endpoints for single and batch document conversions.

## Topics

- Python
- API
- FastAPI
- Markdown Conversion
- PDF Parser
- Document Processing
- OCR
- Scalable Backend

## Repository Information

Last analyzed by OSRepos: Fri Jan 30 2026 20:01:27 GMT+0000 (Western European Standard Time)
Detail views: 13
GitHub clicks: 12

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## Introduction
`docling-api` is an advanced backend server that provides a highly efficient and scalable solution for converting diverse document formats into Markdown. Leveraging IBM's powerful [Docling](https://github.com/DS4SD/docling){:target="_blank"} parser, alongside FastAPI, Celery, and Redis, this service excels at transforming PDFs, DOCX, PPTX, HTML, images, and more into structured Markdown. It supports both CPU and GPU processing modes, with GPU recommended for optimal performance in production, making it perfect for complex, large-scale document processing tasks. The project also highlights its superior parsing capabilities compared to other libraries through visual comparisons.

## Installation
Setting up `docling-api` is straightforward, whether you prefer a local environment or a Dockerized deployment.

### Local Setup (Prerequisites: Python 3.8+, Poetry, Redis server)

1.  **Install Poetry:**
    bash
    curl -sSL https://install.python-poetry.org | python3 -
    

2.  **Clone and Setup Project:**
    bash
    git clone https://github.com/drmingler/docling-api.git
    cd docling-api
    poetry install
    

3.  **Configure Environment:**
    Create a `.env` file in the project root:
    bash
    REDIS_HOST=redis://localhost:6379/0
    ENV=development
    

4.  **Start Redis Server:**
    *   **For MacOS:**
        bash
        brew install redis
        brew services start redis
        
    *   **For Ubuntu/Debian:**
        bash
        sudo apt-get install redis-server
        sudo service redis-server start
        

5.  **Start Application Components:**
    *   Start FastAPI server:
        bash
        poetry run uvicorn main:app --reload --port 8080
        
    *   Start Celery worker (new terminal):
        bash
        poetry run celery -A worker.celery_config worker --pool=solo -n worker_primary --loglevel=info
        
    *   Start Flower dashboard (optional, new terminal):
        bash
        poetry run celery -A worker.celery_config flower --port=5555
        

### Docker Setup

1.  **Clone the repository:**
    bash
    git clone https://github.com/drmingler/docling-api.git
    cd docling-api
    

2.  **Create a `.env` file:**
    bash
    REDIS_HOST=redis://redis:6379/0
    ENV=production
    

3.  **CPU Mode:**
    bash
    docker-compose -f docker-compose.cpu.yml up --build --scale celery_worker=1
    

4.  **GPU Mode (Recommended for production):**
    bash
    docker-compose -f docker-compose.gpu.yml up --build --scale celery_worker=3
    

## Examples
The `docling-api` provides flexible API endpoints for various conversion needs.

### Synchronous Conversion (Single Document):
bash
curl -X POST "http://localhost:8080/documents/convert" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "document=@/path/to/document.pdf" \
  -F "extract_tables_as_images=true" \
  -F "image_resolution_scale=4"


### Asynchronous Conversion (Single Document):
1.  Submit document:
    bash
    curl -X POST "http://localhost:8080/conversion-jobs" \
      -H "accept: application/json" \
      -H "Content-Type: multipart/form-data" \
      -F "document=@/path/to/document.pdf"
    
2.  Check status (replace `{job_id}`):
    bash
    curl -X GET "http://localhost:8080/conversion-jobs/{job_id}" \
      -H "accept: application/json"
    

### Batch Processing (Asynchronous):
bash
curl -X POST "http://localhost:8080/batch-conversion-jobs" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "documents=@/path/to/document1.pdf" \
  -F "documents=@/path/to/document2.pdf"


## Why Use It
`docling-api` stands out as a powerful solution for document-to-Markdown conversion due to several key advantages:
*   **Extensive Format Support**: It handles a wide range of inputs, including PDFs, DOCX, PPTX, HTML, various image formats, and more, ensuring broad applicability.
*   **Advanced Conversion Capabilities**: Beyond basic text extraction, it offers robust table detection and extraction, image processing, and multi-language OCR, providing comprehensive content conversion.
*   **Scalability and Performance**: Designed for large-scale workflows, it leverages Celery for distributed task processing and supports both CPU and GPU modes, with GPU acceleration significantly boosting performance for demanding tasks.
*   **Flexible API**: With synchronous, asynchronous, and batch processing endpoints, developers can integrate the service seamlessly into diverse applications, with job tracking for long-running tasks.
*   **Ease of Deployment**: The project provides clear instructions for both local setup and Docker deployment, simplifying integration into existing infrastructures.
*   **Quality Output**: Visual comparisons in the repository demonstrate its superior Markdown output quality compared to other parsing libraries.

## Links
*   GitHub Repository: [https://github.com/drmingler/docling-api](https://github.com/drmingler/docling-api){:target="_blank"}
*   Docling (IBM's advanced document parser): [https://github.com/DS4SD/docling](https://github.com/DS4SD/docling){:target="_blank"}