DoclingDocling for IBM watsonx
Guides

Conversion Options

Control OCR, tables, images, page ranges and output formats

Every conversion request accepts an options object. The defaults work well for most documents. Use the options below to trade quality for speed, skip what you don't need, or get extra outputs.

The same options are available in the Workbench when you create a task, in the API, and in the SDKs.

Options reference

Output

OptionDefaultDescription
to_formats["md"]Any of md, html, text, json, doclang, dclx. See output formats.
page_rangeall pages[first, last], 1-based and inclusive, for example [1, 5]

Text and OCR

OptionDefaultDescription
do_ocrtrueRun OCR on scanned pages and images. Turn it off for born-digital PDFs to speed things up.
force_ocrfalseReplace the PDF's embedded text with OCR output. Use it when the embedded text is broken (garbled encodings, wrong characters).
ocr_langautoOCR languages as BCP-47 tags, for example ["en"] or ["de-DE", "fr"]

Structure

OptionDefaultDescription
do_table_structuretrueRecognize table rows, columns and merged cells. If turned off, tables are kept as images.
do_pdf_heading_hierarchyfalseInfer heading levels (chapter, section, subsection) in PDFs and images, instead of treating all headings as one level
do_picture_classificationfalseClassify each picture: chart type, diagram, photo, logo, signature, …

Images

OptionDefaultDescription
include_imagestrueGenerate an image for each picture in the document
image_export_modeplaceholderHow pictures appear in Markdown, HTML and JSON: placeholder, embedded (inline base64) or referenced (separate files)
images_scale2.0Resolution factor for generated images
include_page_imagesfalseAlso generate an image of every full page

Examples

Fast conversion of a born-digital PDF

Skip OCR and only convert the first ten pages:

curl -X POST "${DOCLING_SERVICE_URL}/v1/convert/source/async" \
  -H "X-Api-Key: ${DOCLING_SERVICE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [{ "kind": "http", "url": "https://arxiv.org/pdf/2501.17887" }],
    "options": {
      "to_formats": ["md"],
      "do_ocr": false,
      "page_range": [1, 10]
    }
  }'

Scanned document in German

{
  "options": {
    "to_formats": ["md", "dclx"],
    "force_ocr": true,
    "ocr_lang": ["de-DE"]
  }
}

HTML with embedded pictures and a clean heading hierarchy

{
  "options": {
    "to_formats": ["html"],
    "image_export_mode": "embedded",
    "do_pdf_heading_hierarchy": true,
    "do_picture_classification": true
  }
}

Python SDK

Pass options with ConvertDocumentsOptions:

from pathlib import Path
from docling.datamodel.service.options import ConvertDocumentsOptions
from docling.service_client import DoclingServiceClient
import os

options = ConvertDocumentsOptions(
    to_formats=["md", "html"],
    do_ocr=False,
    page_range=(1, 10),
)

with DoclingServiceClient(
    url=os.environ["DOCLING_SERVICE_URL"],
    api_key=os.environ["DOCLING_SERVICE_API_KEY"],
) as client:
    result = client.convert(source=Path("path/to/doc.pdf"), options=options)
    print(result.document.export_to_html())

Java SDK

Set options on the request with ConvertDocumentOptions.builder():

import java.net.URI;

import ai.docling.serve.api.DoclingServeApi;
import ai.docling.serve.api.convert.request.ConvertDocumentRequest;
import ai.docling.serve.api.convert.request.options.ConvertDocumentOptions;
import ai.docling.serve.api.convert.request.options.ImageRefMode;
import ai.docling.serve.api.convert.request.options.OutputFormat;
import ai.docling.serve.api.convert.request.source.HttpSource;
import ai.docling.serve.api.convert.response.InBodyConvertDocumentResponse;

public class Main {
    public static void main(String[] args) {
        DoclingServeApi client = DoclingServeApi.builder()
            .baseUrl(System.getenv("DOCLING_SERVICE_URL"))
            .apiKey(System.getenv("DOCLING_SERVICE_API_KEY"))
            .build();

        ConvertDocumentRequest request = ConvertDocumentRequest.builder()
            .source(HttpSource.builder()
                .url(URI.create("https://arxiv.org/pdf/2501.17887"))
                .build())
            .options(ConvertDocumentOptions.builder()
                .toFormat(OutputFormat.HTML)
                .imageExportMode(ImageRefMode.EMBEDDED)
                .doOcr(true)
                .build())
            .build();

        InBodyConvertDocumentResponse response =
            (InBodyConvertDocumentResponse) client.convertSource(request);
        System.out.println(response.getDocument().getHtmlContent());
    }
}

On this page