Node.js-Tutorial

PDF zu Markdown in Node.js konvertieren

Drei Aufrufe und fertig: Lege einen Job an, frage ab, bis er ready ist, und lade dann sauberes Markdown herunter. Das Beispiel unten ist reines Node 18+ mit dem globalen fetch – keine Abhängigkeiten, keine GPU, nur die REST-API.

Kurze Antwort

Anlegen, abfragen, herunterladen

Die PDF-zu-Markdown-API ist eine kleine Job-API. Du machst POST einer PDF (eine URL oder eine hochgeladene Datei) an /api/v2/jobs mit deinem API-Schlüssel, bekommst eine job_id zurück, fragst /api/v2/jobs/{job_id} ab, bis der Status ready ist, und lädst dann das Markdown von /api/v2/jobs/{job_id}/download herunter. OCR, Tabellen und Formeln werden serverseitig erledigt, also gibt es nichts in deiner Node-App zu installieren.

Anleitung

Das vollständige Beispiel

Speichere es als convert.mjs und führe node convert.mjs aus. Ersetze den Schlüssel und die PDF-URL.

// Node 18+ has a global fetch, so no dependencies are needed.
const API = "https://pdf2md.dev/api/v2";
const H = { Authorization: "Bearer p2m_your_key" };

// 1) create a job from a PDF URL
const created = await fetch(`${API}/jobs`, {
  method: "POST",
  headers: { ...H, "Content-Type": "application/json", "Idempotency-Key": "report-2026-01" },
  body: JSON.stringify({ url: "https://example.com/report.pdf" }),
});
if (!created.ok) throw new Error(`create failed: ${created.status}`);
const { job_id } = await created.json();

// 2) poll until ready or error
let job;
do {
  await new Promise((r) => setTimeout(r, 3000));
  job = await (await fetch(`${API}/jobs/${job_id}`, { headers: H })).json();
} while (!["ready", "error"].includes(job.status));

if (job.status === "error") {
  throw new Error(`conversion failed: ${job.error_code} ${job.error_message}`);
}

// 3) download the Markdown
const md = await (await fetch(`${API}/jobs/${job_id}/download`, { headers: H })).text();
if (job.truncated) console.warn("note: partial result (hit the time budget)");
const fs = await import("node:fs/promises");
await fs.writeFile("report.md", md);
console.log("saved report.md");

Der Idempotency-Key macht einen wiederholten create sicher: Wird derselbe Schlüssel zweimal gesendet, bekommst du denselben Job zurück statt einer doppelten Konvertierung.

Schritt für Schritt

Was jeder Aufruf macht

1

Job anlegen

POST /api/v2/jobs mit dem API-Schlüssel als Bearer-Token und einem JSON-Body von { "url": "..." }. Um stattdessen eine lokale Datei zu konvertieren, schicke multipart/form-data mit einem file-Feld. Die Antwort liefert eine job_id.

2

Abfragen bis ready

GET /api/v2/jobs/{job_id} liefert einen status von queued, processing, ready oder error. Frage alle paar Sekunden ab, bis er sich einpendelt.

3

Markdown herunterladen

GET /api/v2/jobs/{job_id}/download liefert den Markdown-Text. Schreibe ihn in eine .md-Datei, gib ihn an ein LLM weiter oder speichere ihn für eine RAG-Pipeline.

Gut zu wissen

Fehler, Wiederholungen und große Dateien

Fehler behandeln

error_code ist maschinenlesbar (zum Beispiel processing_timeout, conversion_failed); error_message kannst du sicher loggen.
truncated: true bei einem ready-Job bedeutet ein Teilergebnis, das bei einem sehr langen Dokument das Zeitbudget erreicht hat.
Idempotency-Key lässt dich einen create sicher wiederholen, ohne einen doppelten Job.

Hochskalieren

Um viele PDFs zu konvertieren, führe dieselben drei Aufrufe pro Datei mit einem kleinen Concurrency-Limit aus oder wechsle vom Abfragen zu Webhooks, sodass du benachrichtigt wirst, wenn jeder Job ready ist. Der Vertrag ist in TypeScript identisch; typisiere die job-Antwort und du bist startklar.

Lieber Python oder die Shell? Sieh dir das Python-Tutorial und das cURL-Rezept an.

Baust du einen Agenten oder eine Pipeline?

Dieselbe Konvertierung ist als gehosteter MCP-Endpunkt verfügbar, sodass ein KI-Agent PDFs ohne Einrichtung konvertieren kann. Sieh im Entwickler-Hub die vollständige API-Referenz und die OpenAPI-Spezifikation.

FAQ

Häufige Fragen

Brauche ich einen API-Schlüssel, um PDFs in Node.js zu konvertieren?

Ja, für die REST-API übergibst du einen API-Schlüssel als Bearer-Token. Du kannst auch anonym im Browser oder in der Web-App ohne Schlüssel konvertieren; der API-Schlüssel ist für die programmatische und automatisierte Nutzung.

Welche Node.js-Version brauche ich?

Node 18 oder neuer, das ein globales fetch mitbringt, sodass das Beispiel keine zusätzlichen Abhängigkeiten benötigt. Auf älteren Versionen installiere ein fetch-Polyfill oder nutze eine Request-Bibliothek.

Wie konvertiere ich eine lokale PDF-Datei statt einer URL?

Schicke einen multipart/form-data-POST an /api/v2/jobs mit dem Feld file für die PDF, mit FormData und einem Blob, statt eines JSON-Bodys mit url. Der Rest des Ablaufs (abfragen, herunterladen) ist gleich.

Wie behandle ich Fehler und Timeouts?

Wenn status error ist, lies error_code (zum Beispiel processing_timeout oder conversion_failed) und error_message. Ein langes Dokument kann mit truncated auf true ready werden, was ein Teilergebnis bedeutet, das das Zeitbudget erreicht hat.

Kann ich Webhooks statt Abfragen nutzen?

Ja. Abfragen ist am einfachsten für den Start, aber die API unterstützt auch Webhooks, sodass du benachrichtigt wirst, wenn ein Job ready ist, statt abzufragen. Sieh im Entwickler-Hub die Webhook-Einrichtung.