HTTP-API
Den Konverter in Skripten, Automatisierungen oder eigener Software nutzen: Datei hochladen, auf das Ergebnis warten, PDF und Word herunterladen. Ohne Anmeldung und ohne Schlüssel.
So funktioniert’s
- 1
Senden
Das Dokument per POST senden (oder Markdown-Text oder einen GitHub-Link) und ?wait=50 anhängen, um auf das Ergebnis zu warten.
- 2
Warten
Die meisten Dokumente sind in Sekunden fertig. Dauert es länger als 50 Sekunden, kommt zuerst die Auftrags-ID; mit GET weiter warten.
- 3
Herunterladen
files im Ergebnis enthält für jede Datei einen Download-Link, 2 Stunden gültig.
Kein Schlüssel
Direkt aufrufen; dasselbe kostenlose Kontingent wie die Webseite.
Gleiche Qualität wie die Seite
Stile, Tabellen, Formeln, Literatur und Word-Vorlagen funktionieren.
Viele Eingaben
Markdown (mit Bildordner oder .zip), Word, LaTeX, PDF, GitHub-Links.
Automatisch gelöscht
Ergebnisse werden nach 2 Stunden gelöscht, oder sofort mit DELETE.
Schnellstart
report.md in PDF und Word umwandeln. Wenn es fertig ist, kommt 200 mit den Download-Links in files:
curl -F "file=@report.md" -F 'options={"formats":["pdf","docx"]}' \
"https://mdpdfword.com/api/v1/jobs?wait=50"Bei 202 (noch in der Warteschlange oder in Arbeit) mit der Auftrags-ID weiter warten:
curl "https://mdpdfword.com/api/v1/jobs/JOB_ID?wait=50"Endpunkte
| Anfrage | Zweck |
|---|---|
POST /api/v1/jobs?wait=50 | Umwandlung senden und bis zu wait Sekunden warten (höchstens 50). 200, wenn fertig, sonst 202 mit der Auftrags-ID. |
GET /api/v1/jobs/{job_id}?wait=50 | Stand des Auftrags; mit wait wird gewartet, bis er fertig ist oder die Zeit abläuft. |
DELETE /api/v1/jobs/{job_id} | Die Ergebnisdateien sofort löschen. |
GET /api/v1/info | Verfügbare Stile, die Limits und die aktuelle Warteschlange. |
Zu sendende Felder (multipart/form-data)
| Feld | Zweck |
|---|---|
file | Eine umzuwandelnde Datei; mehrfach angeben für das Dokument und seine Bilder, .bib-Dateien usw. Ein .zip geht auch. |
paths | Optional: die relativen Pfade der Dateien in derselben Reihenfolge (JSON-Liste), um Ordner zu erhalten – z. B. ["report.md", "images/a.png"]. |
markdown | Markdown-Text statt einer Datei. |
url | Eine Markdown-Datei aus einem öffentlichen GitHub-Repository statt einer Datei; ihre Bilder werden mitgeholt. |
template | Optional: eine .docx-Vorlage – das Ergebnis übernimmt Seiteneinrichtung, Schriften, Formatvorlagen, Kopf- und Fußzeilen. |
options | Umwandlungsoptionen (JSON-Objekt), siehe unten. |
Umwandlungsoptionen (options)
| Option | Zweck |
|---|---|
formats | ["pdf", "docx"] (Standard), ["pdf"] oder ["docx"]; bei Word-, LaTeX- und PDF-Eingabe auch ["markdown"] für nur bearbeitbares Markdown. |
theme | Name des Stils, Standard business; die Auswahl steht in /api/v1/info. |
toc | true: Inhaltsverzeichnis einfügen. |
number_sections | true / false: Überschriften nummerieren. |
docx_fonts | windows (Standard) oder mac: die CJK-Schriftnamen in Word. |
main | Bei mehreren hochgeladenen Dokumenten das umzuwandelnde (relativer Pfad). |
filename | Dateiname für gesendeten Markdown-Text. |
track_changes | Word-Eingabe: Überarbeitungen accept (Standard) oder reject. |
keep_source_format | Word- und LaTeX-Eingabe: false verwendet stattdessen die Formatierung des gewählten Stils. |
pdf_ocr | PDF-Eingabe: true bedeutet, dass Sie dem Senden des PDFs an SoMark zur erweiterten Erkennung zustimmen (siehe Datenschutz). Ohne diese Option wird nichts gesendet. |
Das Ergebnis
status ist queued, running, done oder error (dann nennen error und code den Grund). warnings listet Punkte zum Prüfen auf, etwa fehlende Bilder.
{
"ok": true,
"job_id": "Vq3…",
"status": "done",
"version": 3,
"main": "report.md",
"elapsed": 4.2,
"files": [
{
"format": "pdf",
"name": "report.pdf",
"size": 182340,
"url": "https://mdpdfword.com/files/results/…/report.pdf",
"file_id": "…"
},
{
"format": "docx",
"name": "report.docx",
"size": 48211,
"url": "https://mdpdfword.com/files/results/…/report.docx",
"file_id": "…"
}
],
"warnings": [],
"pdf_pages": 3,
"expires_in_minutes": 120
}Python-Beispiel
import json
import requests
API = "https://mdpdfword.com/api/v1/jobs"
with open("report.md", "rb") as f:
job = requests.post(API, params={"wait": 50}, files={"file": f},
data={"options": json.dumps({"formats": ["pdf", "docx"]})},
timeout=70).json()
while job.get("status") in ("queued", "running"):
job = requests.get(f"{API}/{job['job_id']}", params={"wait": 50}, timeout=70).json()
if not job.get("ok"):
raise SystemExit(f"{job.get('code')}: {job.get('error')}")
for out in job["files"]:
with open(out["name"], "wb") as f:
f.write(requests.get(out["url"], timeout=120).content)Fehlercodes
| code | Zweck |
|---|---|
bad_request / no_document | 400: falsche Parameter oder kein umzuwandelndes Dokument gefunden. |
file_too_big / total_too_big / too_many_files | 413: Größen- oder Dateianzahl-Limit überschritten. |
too_many_active / rate_hour / rate_limited | 429: zu viele gleichzeitig oder Stundenkontingent überschritten; später erneut versuchen (bei einem Retry-After-Header so viele Sekunden warten). |
busy / storage_full | 503: Server ausgelastet; in ein paar Minuten erneut versuchen. |
not_found | 404: Auftrag existiert nicht oder ist abgelaufen. |
pdf_scanned | Auftrag fehlgeschlagen: gescanntes PDF; pdf_ocr: true setzen, um es zu erkennen. |
timeout / conversion_failed | Auftrag fehlgeschlagen: Dokument zu komplex oder fehlerhaft; error erklärt es. |
Limits
Wie auf der Webseite: pro IP-Adresse höchstens 2 gleichzeitig und 30 pro Stunde; 20 MB pro Datei, insgesamt 60 MB und 300 Dateien; bis zu 5 Minuten pro Umwandlung; Ergebnisse 2 Stunden aufbewahrt.
Der Dienst läuft auf einem einzigen Rechner. Damit Besucher der Webseite nie hinter Skripten warten, teilen sich API-Anfragen einen Teil der Umwandlungsplätze, und die Warteschlange kann bei hoher Last länger sein. Bitte nacheinander senden statt in parallelen Stapeln.
Datenschutz
Hochgeladene Dateien werden nur für diese Umwandlung verwendet, Ergebnisse nach 2 Stunden gelöscht. PDFs werden nur auf dem Server dieser Seite gelesen; nur wenn die Anfrage "pdf_ocr": true enthält, wird das PDF zur erweiterten Erkennung an den Drittanbieter SoMark gesendet – bei sensiblen Dateien bitte nicht setzen. Siehe Datenschutzerklärung. Datenschutzerklärung
Fragen und Antworten
Brauche ich eine Anmeldung oder einen API-Schlüssel?
Nein. Direkt aufrufen; es teilt das kostenlose Kontingent der Webseite.
Kann ich sie aus einer Webseite (JavaScript im Browser) aufrufen?
Nein. Damit andere Seiten die Dateien ihrer Besucher nicht hierher leiten können, erlaubt die API keine seitenübergreifenden Aufrufe. Rufen Sie sie von einem Server oder Skript aus auf.
Was ist der Unterschied zu MCP?
MCP ist für KI-Assistenten wie Claude Code und Codex; die HTTP-API für Skripte und Programme. Qualität und Kontingent sind gleich.
Wird sich die API ändern?
/api/v1 ist stabil: Felder können hinzukommen, vorhandene behalten ihre Bedeutung. /api/jobs, das die Webseite intern nutzt, ist nicht garantiert – bitte nicht darauf aufbauen.