Documents to Markdown with Python
Use Python’s requests package to send a document to POST /v1/convert. This is an HTTP integration: it uses an API key and credits, with no separate SDK required. New accounts receive 500 free credits.
Prepare a file and key
Section titled “Prepare a file and key”- Create a key in API keys and set the
MDW_API_KEYenvironment variable. - Install the Python dependency with
python3 -m pip install requests. - Put your input file beside the script, or change the
sourcepath below.
You can try a single upload without writing code:
The API also accepts HTML. Older DOC, PPT and XLS files must be saved in their modern supported formats before conversion.
Convert and save Markdown
Section titled “Convert and save Markdown”This example reads the document’s existing content with OCR off. It checks the HTTP response before accessing Markdown, then writes a UTF-8 .md file. The multipart file field contains both the filename and an open binary stream.
import osfrom pathlib import Pathimport requests
source = Path("document.pdf")api_key = os.environ["MDW_API_KEY"]
with source.open("rb") as file: response = requests.post( "https://api.md.tlelabs.com/v1/convert", headers={"Authorization": f"Bearer {api_key}"}, files={"file": (source.name, file)}, data={"ocr": "off"}, timeout=180, )
response.raise_for_status()markdown = response.json().get("markdown")if not isinstance(markdown, str): raise ValueError("The response does not contain Markdown.")
output = source.with_suffix(".md")output.write_text(markdown, encoding="utf-8")print(f"Saved {output}")Replace document.pdf with a .docx, .pptx, .xlsx or .html path to use the same endpoint for another supported format. The service detects the format from the uploaded bytes.
Scans and pictures
Section titled “Scans and pictures”For OCR, change data={"ocr": "off"} to data={"ocr": "auto"}. OCR uses credits and may send the pages or pictures that need it to an OCR provider. Read the PDF API guide and OCR models for options and limits.
Changing the extension alone does not convert a document. Excel formulas are not recalculated, Word layout and PowerPoint themes are not reproduced, and a PDF may not carry semantic headings or tables. Review the Markdown before using it in documentation or a retrieval pipeline.
Handle failures and usage
Section titled “Handle failures and usage”response.raise_for_status() stops the script on a non-success HTTP response. A response without a Markdown string is also refused before any output is written. The script does not silently treat error JSON as a successful conversion.
Check Errors for authentication, file size, credit and OCR failures. Respect Retry-After for a 429; correct the file or request for a validation error. The JSON response’s usage describes the pages and credits used. Failed conversions are not charged.
For multiple files, call the endpoint once per file and stay within the concurrency limit. This example performs one synchronous request; it does not imply a batch API or background job service.