← Về thư mục
📄 / / profiles / r-and-d / raw_evidence / scientific-agent-skills / skills / markitdown / references / api_reference.md

MarkItDown 0.1.6 API Reference

Verified against the v0.1.6 source tag and installed package on July 23, 2026.

Public Imports

from markitdown import (
    DocumentConverter,
    DocumentConverterResult,
    FileConversionException,
    MarkItDown,
    MissingDependencyException,
    PRIORITY_GENERIC_FILE_FORMAT,
    PRIORITY_SPECIFIC_FILE_FORMAT,
    StreamInfo,
    UnsupportedFormatException,
)

Azure file-type enums are exported from markitdown.converters:

from markitdown.converters import (
    ContentUnderstandingFileType,
    DocumentIntelligenceFileType,
)

MarkItDown

Constructor

MarkItDown(
    *,
    enable_builtins: bool | None = None,
    enable_plugins: bool | None = None,
    **kwargs,
)

Built-in converters are enabled by default. Third-party plugins are disabled by default.

Recognized constructor keywords include:

Keyword Purpose
requests_session Custom requests.Session used by HTTP(S) URI conversion
llm_client OpenAI-compatible client for image descriptions and compatible plugins
llm_model Provider-specific model identifier
llm_prompt Prompt for image description/OCR
exiftool_path Explicit trusted ExifTool executable
style_map Mammoth style map for DOCX conversion
docintel_endpoint Enable Azure Document Intelligence
docintel_credential Explicit AzureKeyCredential or token credential
docintel_file_types Restrict Document Intelligence routing
docintel_api_version Azure Document Intelligence API version
cu_endpoint Enable Azure Content Understanding
cu_credential Explicit AzureKeyCredential or token credential
cu_analyzer_id Custom Content Understanding analyzer
cu_file_types Restrict Content Understanding routing

The public signature uses **kwargs; spell these names exactly.

Conversion methods

convert()

convert(
    source: str | Path | requests.Response | BinaryIO,
    *,
    stream_info: StreamInfo | None = None,
    **kwargs,
) -> DocumentConverterResult

Dispatch rules:

This convenience method is broad. Prefer a narrower method for untrusted or application-facing inputs.

convert_local()

convert_local(
    path: str | Path,
    *,
    stream_info: StreamInfo | None = None,
    file_extension: str | None = None,
    url: str | None = None,
    **kwargs,
) -> DocumentConverterResult

file_extension and url are legacy parameters; put overrides in StreamInfo.

from pathlib import Path

from markitdown import MarkItDown

source = Path("experiment.xlsx")
result = MarkItDown().convert_local(source)
Path("experiment.md").write_text(result.markdown, encoding="utf-8")

convert_stream()

convert_stream(
    stream: BinaryIO,
    *,
    stream_info: StreamInfo | None = None,
    file_extension: str | None = None,
    url: str | None = None,
    **kwargs,
) -> DocumentConverterResult

Requirements and behavior:

from io import BytesIO

from markitdown import MarkItDown, StreamInfo

payload = b"sample,value\ncontrol,1\ntreated,2\n"
result = MarkItDown().convert_stream(
    BytesIO(payload),
    stream_info=StreamInfo(
        extension=".csv",
        mimetype="text/csv",
        charset="utf-8",
        filename="results.csv",
    ),
)
print(result.markdown)

convert_uri()

convert_uri(
    uri: str,
    *,
    stream_info: StreamInfo | None = None,
    file_extension: str | None = None,
    mock_url: str | None = None,
    **kwargs,
) -> DocumentConverterResult

Supported schemes:

HTTP(S) conversion uses the configured requests.Session, follows Requests defaults, and then buffers the complete response in memory. It does not provide an application-level SSRF policy, download-size limit, or redirect allowlist. Validate and fetch remote resources yourself before calling convert_response().

convert_url() remains a backward-compatible alias, but new code should use convert_uri().

convert_response()

convert_response(
    response: requests.Response,
    *,
    stream_info: StreamInfo | None = None,
    file_extension: str | None = None,
    url: str | None = None,
    **kwargs,
) -> DocumentConverterResult

The method derives hints from Content-Type, Content-Disposition, and the response URL, then buffers every response chunk into memory. The caller is responsible for destination validation, redirect handling, timeout, maximum size, authentication, and TLS policy.

StreamInfo

StreamInfo(
    *,
    mimetype: str | None = None,
    extension: str | None = None,
    charset: str | None = None,
    filename: str | None = None,
    local_path: str | None = None,
    url: str | None = None,
)

Examples:

pdf_info = StreamInfo(
    mimetype="application/pdf",
    extension=".pdf",
    filename="paper.pdf",
)

html_info = StreamInfo(
    mimetype="text/html",
    extension=".html",
    charset="utf-8",
    filename="article.html",
)

Hints are merged with extension, HTTP header, and Magika content-detection guesses. If a caller-supplied hint conflicts with content detection, MarkItDown may try both guesses.

DocumentConverterResult

DocumentConverterResult(
    markdown: str,
    *,
    title: str | None = None,
)

Attributes and conversions:

Interface Status
result.markdown Canonical converted Markdown
result.title Optional source-derived title
result.text_content Soft-deprecated alias for markdown
str(result) Returns markdown 
result = MarkItDown().convert_local("paper.pdf")
markdown = result.markdown
title = result.title

Per-conversion Options

Converter-specific values can be forwarded through a conversion call:

result = converter.convert_local(
    "page.html",
    keep_data_uris=False,
)

Common options:

Option Used by
keep_data_uris HTML/Markdown conversion; preserve rather than truncate data URIs
youtube_transcript_languages YouTube transcript language preference
llm_client, llm_model, llm_prompt Image/PPTX description and compatible plugins
style_map DOCX conversion
exiftool_path Image/audio metadata

Exceptions

from markitdown import (
    FileConversionException,
    MissingDependencyException,
    UnsupportedFormatException,
)
Exception Meaning
MissingDependencyException The converter matched, but its optional dependency is unavailable
UnsupportedFormatException No registered converter accepted the source
FileConversionException One or more matching converters attempted and failed
TypeError convert() received an unsupported source type, such as a text stream 
from markitdown import (
    FileConversionException,
    MarkItDown,
    MissingDependencyException,
    UnsupportedFormatException,
)

try:
    result = MarkItDown().convert_local("input.pdf")
except MissingDependencyException:
    print("Install markitdown[pdf]==0.1.6")
except UnsupportedFormatException:
    print("No converter accepted this input")
except FileConversionException as exc:
    print(f"A matching converter failed: {exc}")

Converter Registration

register_converter(
    converter: DocumentConverter,
    *,
    priority: float = PRIORITY_SPECIFIC_FILE_FORMAT,
) -> None

Lower numeric priorities run first. The built-in specific-format priority is 0.0; generic converters use 10.0. For registrations with equal priority, the most recently registered converter is attempted first.

register_page_converter() is deprecated.

Custom Converter

Version 0.1.x converters operate on binary streams and implement both accepts() and convert():

from typing import Any, BinaryIO

from markitdown import (
    DocumentConverter,
    DocumentConverterResult,
    StreamInfo,
)


class RtfConverter(DocumentConverter):
    def accepts(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> bool:
        return (stream_info.extension or "").lower() == ".rtf"

    def convert(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> DocumentConverterResult:
        raw = file_stream.read()
        # Replace this placeholder with a real, bounded RTF parser.
        return DocumentConverterResult(
            markdown=f"```text\n{raw.decode('utf-8', errors='replace')}\n```"
        )

Do not advance the stream in accepts(). If inspection is necessary, save the position with tell() and restore it with seek().

Plugin Package Contract

The plugin module exports interface version 1 and a registration function:

from markitdown import MarkItDown

__plugin_interface_version__ = 1


def register_converters(markitdown: MarkItDown, **kwargs) -> None:
    markitdown.register_converter(RtfConverter())

Register the module through pyproject.toml:

[project.entry-points."markitdown.plugin"]
example = "example_markitdown_plugin"

Inspect and install a trusted, pinned plugin, then verify discovery:

markitdown --list-plugins
markitdown --use-plugins input.rtf -o output.md

CLI Reference

markitdown [options] [filename]

If filename is omitted, MarkItDown reads binary input from stdin.

Option Meaning
-v, --version Print package version
-o, --output PATH Write UTF-8 Markdown to a file
-x, --extension EXT File-extension hint
-m, --mime-type TYPE MIME-type hint
-c, --charset NAME Charset hint
-d, --use-docintel Use Azure Document Intelligence
-e, --endpoint URL Document Intelligence endpoint
--use-cu, --use-content-understanding Use Azure Content Understanding
--cu-endpoint URL Content Understanding endpoint
--cu-analyzer ID Custom analyzer ID
--cu-file-types LIST Comma-separated CU file types
-p, --use-plugins Enable installed third-party plugins
--list-plugins List discovered plugins and exit
--keep-data-uris Preserve full data URIs

Document Intelligence and Content Understanding are mutually exclusive in one CLI invocation.

The core 0.1.6 parser does not expose --llm-client or --llm-model. Configure image descriptions or the OCR plugin through Python.

Source Basis