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
| Option | Default | Description |
|---|---|---|
to_formats | ["md"] | Any of md, html, text, json, doclang, dclx. See output formats. |
page_range | all pages | [first, last], 1-based and inclusive, for example [1, 5] |
Text and OCR
| Option | Default | Description |
|---|---|---|
do_ocr | true | Run OCR on scanned pages and images. Turn it off for born-digital PDFs to speed things up. |
force_ocr | false | Replace the PDF's embedded text with OCR output. Use it when the embedded text is broken (garbled encodings, wrong characters). |
ocr_lang | auto | OCR languages as BCP-47 tags, for example ["en"] or ["de-DE", "fr"] |
Structure
| Option | Default | Description |
|---|---|---|
do_table_structure | true | Recognize table rows, columns and merged cells. If turned off, tables are kept as images. |
do_pdf_heading_hierarchy | false | Infer heading levels (chapter, section, subsection) in PDFs and images, instead of treating all headings as one level |
do_picture_classification | false | Classify each picture: chart type, diagram, photo, logo, signature, … |
Images
| Option | Default | Description |
|---|---|---|
include_images | true | Generate an image for each picture in the document |
image_export_mode | placeholder | How pictures appear in Markdown, HTML and JSON: placeholder, embedded (inline base64) or referenced (separate files) |
images_scale | 2.0 | Resolution factor for generated images |
include_page_images | false | Also 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());
}
}