Skip to content

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.

  1. Create a key in API keys and set the MDW_API_KEY environment variable.
  2. Install the Python dependency with python3 -m pip install requests.
  3. Put your input file beside the script, or change the source path 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.

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 os
from pathlib import Path
import 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.

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.

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.