# Documents to Markdown with Python

> Send PDF, Word, PowerPoint or Excel files to the Markdown conversion API from Python, check the HTTP response and save a UTF-8 .md file.

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

1. Create a key in [API keys](https://md.tlelabs.com/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:

- [PDF to Markdown](https://md.tlelabs.com/pdf-to-markdown/)
- [Word DOCX to Markdown](https://md.tlelabs.com/docx-to-markdown/)
- [PowerPoint PPTX to Markdown](https://md.tlelabs.com/pptx-to-markdown/)
- [Excel XLSX to Markdown](https://md.tlelabs.com/xlsx-to-markdown/)

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

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.

```py
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.

## 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](https://md.tlelabs.com/docs/guides/pdf-to-markdown-api/) and [OCR models](https://md.tlelabs.com/docs/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

`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](https://md.tlelabs.com/docs/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](https://md.tlelabs.com/docs/rate-limits/). This example performs one synchronous request; it does not imply a batch API or background job service.
