Package ai.docling.serve.api

Interface DoclingServeConvertApi

All Known Subinterfaces:

DoclingServeApi

public interface DoclingServeConvertApi

Interface representing the Docling Serve Convert API. This API is responsible for processing and converting document source(s) into a structured or processed document format based on the specified conversion options.

Method Summary

Modifier and Type	Method	Description
default ConvertDocumentResponse	convertFiles(@Nullable ConvertDocumentRequest request, Path... files)	Converts the specified files into a processed document based on the options provided in the request.
default ConvertDocumentResponse	convertFiles(Path... files)	Converts the specified files into a processed document using default options.
default CompletionStage<ConvertDocumentResponse>	convertFilesAsync(@Nullable ConvertDocumentRequest request, Path... files)	Initiates an asynchronous conversion of the specified files into a processed document using the provided conversion request options.
default CompletionStage<ConvertDocumentResponse>	convertFilesAsync(Path... files)	Initiates an asynchronous conversion of the provided files into a processed document using default conversion options.
ConvertDocumentResponse	convertSource(ConvertDocumentRequest request)	Converts the provided document source(s) into a processed document based on the specified options.
CompletionStage<ConvertDocumentResponse>	convertSourceAsync(ConvertDocumentRequest request)	Initiates an asynchronous conversion of the provided document source(s) and returns a CompletionStage that completes when the conversion is done.
TaskStatusPollResponse	convertSourceBatch(BatchConvertDocumentRequest request)	Submits a batch conversion request for processing multiple document sources asynchronously.
CompletionStage<ConvertDocumentResponse>	convertSourceBatchAsync(BatchConvertDocumentRequest request)	Submits a batch conversion request and automatically polls for completion.

Method Details

convertSource

ConvertDocumentResponse convertSource(ConvertDocumentRequest request)

Converts the provided document source(s) into a processed document based on the specified options.

Parameters:

request - the ConvertDocumentRequest containing the source(s), conversion options, and optional target.

Returns:

a ConvertDocumentResponse describing the convert document response.

Throws:

ValidationException - If request validation fails for any reason.

convertFiles

default ConvertDocumentResponse convertFiles(Path... files)

Converts the specified files into a processed document using default options. This is a convenience method that delegates to convertFiles(ConvertDocumentRequest, Path...) with a null request.

Parameters:

files - an array of Path objects representing the file paths to be converted

Returns:

a ConvertDocumentResponse containing the processed document data, metadata, and any errors

Throws:

ValidationException - If request validation fails for any reason.

convertFiles

default ConvertDocumentResponse convertFiles(@Nullable ConvertDocumentRequest request,
 Path... files)

Converts the specified files into a processed document based on the options provided in the request. If the request is null, default conversion options are applied.

Parameters:

request - an optional ConvertDocumentRequest specifying conversion settings and parameters

files - an array of Path objects representing the file paths to be converted

Returns:

a ConvertDocumentResponse containing the processed document data, any errors encountered, and additional processing metadata

Throws:

ValidationException - If request validation fails for any reason.

convertSourceAsync

CompletionStage<ConvertDocumentResponse> convertSourceAsync(ConvertDocumentRequest request)

Initiates an asynchronous conversion of the provided document source(s) and returns a CompletionStage that completes when the conversion is done.

This method starts the conversion, polls the status in the background, and completes the future with the result when the conversion finishes.

Example usage:

 client.convertSourceAsync(request)
     .thenApply(response -> response.getDocument().getMarkdownContent())
     .thenAccept(markdown -> System.out.println(markdown))
     .exceptionally(ex -> { ex.printStackTrace(); return null; });
 

Parameters:

request - the ConvertDocumentRequest containing the source(s) and conversion options.

Returns:

a CompletionStage that completes with the ConvertDocumentResponse when the conversion is finished, or completes exceptionally if the conversion fails or times out.

Throws:

ValidationException - If request validation fails for any reason.

convertFilesAsync

default CompletionStage<ConvertDocumentResponse> convertFilesAsync(Path... files)

Initiates an asynchronous conversion of the provided files into a processed document using default conversion options.

Parameters:

files - an array of Path objects representing the file paths to be converted

Returns:

a CompletionStage that completes with the ConvertDocumentResponse when the conversion finishes, or completes exceptionally if the conversion fails or times out

Throws:

ValidationException - If request validation fails for any reason.

convertFilesAsync

default CompletionStage<ConvertDocumentResponse> convertFilesAsync(@Nullable ConvertDocumentRequest request,
 Path... files)

Initiates an asynchronous conversion of the specified files into a processed document using the provided conversion request options. If the request is null, default conversion options are applied.

Parameters:

request - an optional ConvertDocumentRequest containing conversion settings and parameters, or null to use default options

files - an array of Path objects representing the file paths to be converted

Returns:

a CompletionStage that completes with the ConvertDocumentResponse when the conversion finishes, or completes exceptionally if the conversion fails or times out

Throws:

ValidationException - If request validation fails for any reason.

convertSourceBatch

TaskStatusPollResponse convertSourceBatch(BatchConvertDocumentRequest request)

Submits a batch conversion request for processing multiple document sources asynchronously.

This method posts the batch request to the server, which returns a task status containing a task ID. The caller can then use DoclingServeTaskApi.pollTaskStatus(ai.docling.serve.api.task.request.TaskStatusPollRequest) and DoclingServeTaskApi.convertTaskResult(ai.docling.serve.api.task.request.TaskResultRequest) to track and retrieve results.

Parameters:

request - the BatchConvertDocumentRequest containing the sources, target, conversion options, and optional callbacks.

Returns:

a TaskStatusPollResponse containing the task ID and initial status.

Throws:

ValidationException - If request validation fails for any reason.

convertSourceBatchAsync

CompletionStage<ConvertDocumentResponse> convertSourceBatchAsync(BatchConvertDocumentRequest request)

Submits a batch conversion request and automatically polls for completion.

This method submits the batch request, polls the task status in the background, and completes the returned future with the conversion result when all documents have been processed.

Example usage:

 client.convertSourceBatchAsync(request)
     .thenAccept(response -> System.out.println("Batch complete"))
     .exceptionally(ex -> { ex.printStackTrace(); return null; });
 

Parameters:

request - the BatchConvertDocumentRequest containing the sources, target, conversion options, and optional callbacks.

Returns:

a CompletionStage that completes with the ConvertDocumentResponse when all documents have been processed, or completes exceptionally if the batch conversion fails or times out.

Throws:

ValidationException - If request validation fails for any reason.