API
Dokumentenkonvertierungs-API
Die Dokumentenkonvertierungs-API ist eine HTTPS-API, die eine Datei, eine URL oder HTML in einem einzigen POST /v1/convert/{name}-Aufruf annimmt und Markdown zurückgibt.
Die anonyme Testnutzung akzeptiert Dateien bis 10 MB und 25 Seiten, mit 3 Konvertierungen pro IP und Stunde und 10 pro Tag. Lite startet bei $20 pro Monat mit Dateien bis 100 MB. Pro kostet $50 pro Monat; Max kostet $100 pro Monat.
- Ein POST /v1/convert/{name}-Aufruf pro Datei, URL oder Inline-Text
- Markdown in der Antwort innerhalb von 60 Sekunden oder eine Konvertierung zum Abfragen
- Dieselbe Konvertierungs-Engine wie die Web-App
# Upload a local file; Markdown comes back in the same response
curl -X POST https://api.markitdown.ai/v1/convert/pdf \
-H "x-api-key: mdai_…" \
-F file=@nist-cswp-29-csf-2.0.pdf
# Or convert a public web page
curl -X POST https://api.markitdown.ai/v1/convert/url \
-H "x-api-key: mdai_…" \
-H "content-type: application/json" \
-d '{"url":"https://markitdown.ai/blog/why-pdfs-break-llms"}'
# Took longer than the wait window? Long-poll the conversion
curl "https://api.markitdown.ai/v1/conversions/<id>?wait=100" \
-H "x-api-key: mdai_…"So funktioniert die Dokumentenkonvertierungs-API
Drei Schritte vom Schlüssel zum Markdown. Jeder Aufruf wartet bis zu 60 Sekunden und antwortet mit dem Ergebnis; längere Anfragen oder solche mit mehreren Dateien liefern 202 und eine Konvertierung zum Abfragen, statt die Verbindung offen zu halten.
Erstelle einen API-Schlüssel
Erstelle einen Schlüssel unter Einstellungen → Entwickler (erfordert ein aktives Abo) und sende ihn im x-api-key-Header.
POST /v1/convert/{name}
Sende eine Datei, eine öffentliche URL oder Inline-Text an den Endpunkt für dieses Format. Ein Eingabetyp pro Aufruf.
Nutze das Markdown
Lies die Ausgabe aus der Antwort oder warte nach einem 202 auf /v1/conversions/{id}.
Antwort und Webhooks
Die Antwort unten illustriert den API-Vertrag anhand verifizierter DOCX-Parser-Ausgabe; die Konvertierungs-ID ist ein Platzhalter. Eine abgeschlossene Konvertierung gibt das Markdown samt den verbrauchten Credits zurück. Ein 202 trägt einen Location-Header zur Konvertierung; frage sie mit ?wait= ab, streame ihre Events oder lass dich per Webhook benachrichtigen, wenn sie abgeschlossen ist.
{
"id": "cnv_3f7c…",
"object": "conversion",
"name": "word",
"status": "completed",
"files": [ { "outputs": [ { "format": "markdown", "content": "## Review Findings\n\nRisk ratings follow the standard High / Medium / Low scale defined in the vendor risk management policy.\n\n| Vendor | Risk Rating | Finding | Owner |\n| --- | --- | --- | --- |\n| CloudScan OCR | Medium | No documented data retention limit on uploaded scans | Security |\n| PayBridge | Low | SOC 2 Type II renewed; no open items | Finance |\n| LingoTrans API | High | Sub-processor list not disclosed on request | Legal |\n| ArchiveNow Storage | Medium | Encryption at rest confirmed; key rotation overdue | Security |\n" } ] } ],
"usage": { "credits_charged": 1 }
}POST https://your-app.example.com/webhooks
{
"type": "conversion.completed",
"data": { "id": "cnv_3f7c…", "object": "conversion", "status": "completed" }
}Abonniere conversion.completed und conversion.failed, damit du in dem Moment reagieren kannst, in dem eine lange oder mehrdateiige Konvertierung abgeschlossen ist, statt zu pollen. Zustellungen werden mit Standard-Webhooks-Headern signiert.
Dokumentenanalyse-API und Markdown-Konvertierungs-API
Teams suchen eine Dokumentenanalyse-API, wenn sie Struktur aus Dateien brauchen, und eine Markdown-Konvertierungs-API, wenn die Ausgabe in einen Prompt oder einen Speicher gelangen soll. Beide Begriffe beschreiben diesen Dienst. Formatspezifische Seiten wie die PDF-zu-Markdown-API und die URL-zu-Markdown-API sind Anker zu diesen Konvertern – sie nutzen dieselben /v1/convert/{name}-Endpunkte.
Konvertierungs-Endpunkte
POST /v1/convert/{name} – ein Endpunkt pro Format – nimmt eine Datei, eine URL oder Text und gibt Markdown, Text, HTML oder Ausgabe pro Seite zurück.
API-Schlüssel
Schlüssel pro Konto, gesendet im x-api-key-Header, damit die Konvertierung in jeden Server oder jedes Skript passt.
Mehrere Dateien und Webhooks
Sende viele Dateien an einen Konvertierungsaufruf und erhalte eine Konvertierung zurück; Webhooks melden jedes conversion.completed oder conversion.failed.
Markdown Render
POST /v1/convert/markdown/html oder /markdown/text verwandelt Markdown kostenlos in Credits zurück in HTML oder Klartext.
Anwendungsfälle
Wo Teams sie einbinden
RAG-Ingestion
Konvertiere Dokumente in Ingestion-Jobs, bevor du chunkst und einbettest.
KI-Agenten
Lass Agenten beliebige Dateien mitten in der Pipeline in sauberen Text verwandeln.
Content-Pipelines
Speise Markdown automatisch in ein CMS, eine Doku-Seite oder eine Wissensdatenbank ein.
Interne Tools
Ergänze die Dokumentenkonvertierung in den Produkten und Backoffice-Tools, die du schon betreibst.
Authentifizierung, Nutzung und Limits
- API-Schlüssel gehören zu deinem Konto, funktionieren nur unter /v1 und werden im x-api-key-Header gesendet – das Konto braucht ein aktives Lite-, Pro- oder Max-Abo
- Die Nutzung verbraucht dieselben Credits wie die Web-App – Standard- und OCR-Seiten kosten 1 Credit pro Seite
- Die Rate-Limits der Pläne sind Lite 20, Pro 40 und Max 60 Anfragen pro Minute
- Idempotency-Key bei jedem POST /v1/convert/{name}-Aufruf, damit ein erneuter Versuch nie doppelt berechnet wird
- Jeder v1-Endpunkt, jedes Anfragefeld und jede Antwort sind in der generierten API-Referenz dokumentiert; Fehler nutzen problem+json mit einer type-URI, die zur passenden Fehlercode-Seite auflöst
Leitfaden
Abschluss behandeln
Behandle in einem Client der Dokumentenkonvertierungs-API sowohl den Inline-Abschluss als auch die asynchrone Verarbeitung. Eine erfolgreiche Einreichung kann ein bereits abgeschlossenes Ergebnis zurückgeben, während HTTP 202 anzeigt, dass die Arbeit nach der Antwort weiterläuft. Bewahre die Konvertierungs-ID auf und nutze den dokumentierten Location- oder Konvertierungsstatus-Endpunkt, bevor du Ausgaben liest. Indexiere nicht direkt in eine angenommene erste Ausgabe, nur weil die HTTP-Anfrage erfolgreich war. Eine abgeschlossene Konvertierung kann auch Fehler auf Dateiebene enthalten, also prüfe jede Datei in einer Anfrage mit mehreren Quellen. Speichere genug Kontext, um jedes zurückgegebene Ergebnis mit der Quelle zu verbinden, die deine Anwendung gesendet hat. So wird aus einer langsamen Konvertierung oder einem Teilfehler nicht stillschweigend ein leeres Dokument in deinem nachgelagerten System.
Anfragelimits vs. Planlimits
Die Dokumentenkonvertierungs-API wendet Limits sowohl auf Anfragen als auch auf Konten an. Eine Multipart-Anfrage kann bis zu 100 Dateien mit einem gemeinsamen Limit von 100 MB enthalten. Eine URL-Anfrage akzeptiert bis zu 20 Quellen. Dein Abo steuert separat Credits, Speicher, Limits pro Datei und Parallelität. Eine Pro-Datei kann durch ihr Abo erlaubt und dennoch zu groß für eine einzelne Multipart-Anfrage sein; nutze für diesen Fall den dokumentierten Chunked-Upload-Workflow. Umgehe eine abgelehnte Anfrage nicht mit der Annahme, dass der höchste Plan Transportlimits aufhebt. Lies den Fehler und nutze die für die Quellgröße vorgesehene Eingabemethode.
Quellkontext bewahren
Bewahre deine eigene Quell-ID neben der Konvertierungs-ID auf, damit ein Ergebnis bis zum Job zurückverfolgt werden kann, der es eingereicht hat. Das metadata-Feld der API trägt vom Aufrufer gelieferte Daten; es ist kein Versprechen, Webseitentitel, Autoren oder Veröffentlichungsdaten zu extrahieren. Wenn deine Anwendung diese Fakten braucht, sammle und prüfe sie in einem passenden separaten Schritt. Prüfe vor dem Lesen ihres Textes, ob eine Ausgabe inline oder über ein referenziertes Artefakt zurückgegeben wird, und bewahre das Originaldokument auf, wenn dein Workflow einen Audit-Trail braucht. Eine Dokumentenkonvertierungs-API bereitet Inhalte für die nächste Stufe vor, während deine Anwendung dafür verantwortlich bleibt, diese Inhalte ihrer Quelle zuzuordnen und zu entscheiden, wie lange sie aufbewahrt werden.
Vor dem Start testen
Teste mehr als eine erfolgreiche kleine Datei, bevor du die Dokumentenkonvertierungs-API in einen Produktions-Workflow integrierst. Nimm eine Eingabe auf, die einen asynchronen Abschluss erfordert, eine nicht unterstützte oder beschädigte Datei, eine Anfrage mit mehreren Quellen und gemischten Ergebnissen sowie eine Antwort, die dein Client als Limitfehler behandeln muss. Vergewissere dich, dass deine eigene Retry-Logik nach einem Teilfehler keine erfolgreichen Dateien erneut sendet. Bewahre API-Zugangsdaten auf deinem Server auf und platziere sie nicht in Browsercode oder öffentlichen Beispielen. Prüfe das tatsächliche Markdown für repräsentative Quelltypen, bevor du das Retrieval oder das Modellverhalten nachgelagert bewertest. Ein Client, der Transportfehler korrekt behandelt, braucht trotzdem Prüfungen auf Inhaltsebene, um zu belegen, dass die resultierenden Dokumente nützlich sind.
FAQ
Fragen zur Dokument-zu-Markdown-API
Wie authentifiziere ich mich an der Dokumentenkonvertierungs-API?
Erstelle einen API-Schlüssel in deinem Konto und sende ihn im Header `x-api-key`. Schlüssel sind auf dein Konto beschränkt.
Wie läuft die eigentliche Konvertierung ab?
POST /v1/convert/{name} mit einer Datei, einer öffentlichen URL oder Text. Das Markdown kommt in derselben Antwort zurück, wenn das Dokument innerhalb des Wartefensters fertig wird; andernfalls erhältst du 202 und eine Konvertierung, auf die du mit GET /v1/conversions/{id}?wait= warten kannst.
Ist die Konvertierung synchron?
Standardmäßig bis zum Wartefenster: POST /v1/convert/{name} wartet auf ein Ergebnis und gibt es inline zurück oder liefert 202 mit einer Location, wenn die Konvertierung nicht rechtzeitig fertig wird. Sende Prefer: respond-async, um das Warten zu überspringen.
Welche Events kann ich abonnieren?
Ausgehende Webhooks unterstützen conversion.completed und conversion.failed, damit du reagieren kannst, sobald eine Konvertierung abgeschlossen ist, statt zu pollen.
Welche Pläne enthalten API-Zugang?
Der API-Zugang ist in kostenpflichtigen Plänen verfügbar. Sieh dir die Preisseite für die aktuellen Planlimits und Credits an.
Wie wird die API-Nutzung abgerechnet?
API-Konvertierungen schöpfen aus demselben Credit-Guthaben wie die Web-App. Standard- und OCR-Seiten kosten 1 Credit pro Seite.
Wo finde ich eine PDF-zu-Markdown-API oder URL-zu-Markdown-API?
Diese Begriffe sind Formatseiten, keine zusätzlichen Hosts. Nutze die Hinweise zur PDF-zu-Markdown-API unter /pdf-to-markdown und die zur URL-zu-Markdown-API unter /url-to-markdown und rufe dann dieselben hier dokumentierten Upload- und Konvertierungsendpunkte auf.
Wie hoch sind die Rate-Limits der API-Schlüssel?
Anfragen werden pro Konto begrenzt: Lite 20, Pro 40 und Max 60 Anfragen pro Minute.
Wandle deine erste Datei in Markdown um.
Kostenlos testen – keine Anmeldung nötig.