Azure Content Understanding¶

Azure Content Understanding provides higher-quality conversion with structured field extraction (YAML front matter), multi-modal support (documents, images, audio, video), and configurable analyzers.

Install:

pip install 'markitdown[az-content-understanding]'

When to use Content Understanding¶

Content Understanding is ideal when you need capabilities beyond what built-in or Document Intelligence converters provide:

Audio and video files — CU is the only option for video, and the higher-quality cloud option for audio. Built-in converters have no video support and only basic audio transcription.
Structured field extraction — Prebuilt or custom-built analyzers extract domain-specific fields (invoice amounts, receipt dates, contract clauses) serialized as YAML front matter. Neither built-in nor Doc Intel integration exposes fields.
Higher-quality document extraction — Cloud-based layout analysis and OCR for scanned PDFs, complex tables, and multi-page documents.
Single API for all modalities — One cu_endpoint handles documents, images, audio, and video with automatic analyzer routing.

Capability	Built-in converters	Azure Document Intelligence	Azure Content Understanding
Document conversion	Offline, format-specific extraction	Cloud layout extraction	Cloud multimodal extraction
Structured fields	Not available	Not exposed by this integration	YAML front matter from analyzer fields
Custom analyzers	Not available	Not configurable in this integration	Supported with `cu_analyzer_id`
Audio and video	Basic audio, no video	Not supported	Audio and video analyzers
Cost	Local compute only	Billable Azure API calls	Billable Azure API calls

CLI¶

markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"

The endpoint can also be set once in the environment, so callers only need --use-cu:

export MARKITDOWN_CU_ENDPOINT="<content_understanding_endpoint>"
markitdown path-to-file.pdf --use-cu

Python API¶

from markitdown import MarkItDown

# Zero-config — auto-selects analyzer per file type
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf")   # documents → prebuilt-documentSearch
result = md.convert("meeting.mp4")  # video → prebuilt-videoSearch
result = md.convert("call.wav")     # audio → prebuilt-audioSearch
print(result.markdown)

With a custom analyzer¶

For domain-specific field extraction:

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_analyzer_id="my-invoice-analyzer",
)
result = md.convert("invoice.pdf")
print(result.markdown)
# Output includes YAML front matter with extracted fields:
# ---
# contentType: document
# fields:
#   VendorName: CONTOSO LTD.
#   InvoiceDate: '2019-11-15'
# ---
# <!-- page 1 -->
# ...

When cu_analyzer_id is set, the converter automatically scopes it to compatible file types based on the analyzer's modality. Incompatible types (e.g., audio files with a document analyzer) auto-route to default prebuilt analyzers.

Cost note¶

Each convert() call for a CU-routed format is a billable Azure API call. Use cu_file_types to restrict which formats route to CU:

from markitdown.converters import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # only PDFs use CU
)

More information about Azure Content Understanding can be found here.