PDF stapelweise zu Markdown konvertieren
Du hast einen Ordner voller Berichte, Paper oder Rechnungen? Konvertiere sie alle mit der REST API: ein kleiner Job pro Datei, iteriert über deinen Satz, mit sicheren Retries dank Idempotenz, sodass ein erneuter Lauf nie Arbeit dupliziert.
Ein Stapel sind viele kleine Jobs
Die API konvertiert eine PDF pro Job: erstellen, abfragen, herunterladen. Um viele zu konvertieren, führst du diesen Ablauf einmal pro Datei in einer Schleife aus, mit zwei Ergänzungen, die einen Stapel zuverlässig machen. Ein Idempotency-Key pro Datei bedeutet, dass ein erneuter Lauf nach einem Absturz dort weitermacht, wo er aufgehört hat, statt fertige Arbeit zu wiederholen. Ein kleines Nebenläufigkeitslimit hält mehrere Konvertierungen in Bearbeitung, ohne die API zu überlasten. Dieselbe Form skaliert von zehn Dateien bis zu Tausenden.
Konvertiere einen ganzen Ordner
Eine minimale Shell-Schleife über jede PDF in einem Verzeichnis. Setze deinen Schlüssel ein.
API="https://pdf2md.dev/api/v2"
AUTH="Authorization: Bearer p2m_your_key"
for pdf in *.pdf; do
# Dateiname als Idempotency-Key: ein erneuter Lauf nutzt denselben Job wieder
JID=$(curl -fsS -X POST "$API/jobs" -H "$AUTH" \
-H "Idempotency-Key: $pdf" -F file=@"$pdf" | jq -r .job_id)
until [ "$(curl -fsS "$API/jobs/$JID" -H "$AUTH" | jq -r .status)" = "ready" ]; do
sleep 3
done
curl -fsS "$API/jobs/$JID/download" -H "$AUTH" -o "${pdf%.pdf}.md"
echo "konvertiert $pdf"
done
Diese Version ist sequenziell der Klarheit halber. Für echtes Volumen konvertiere mehrere Dateien gleichzeitig mit einem Worker-Pool und wechsle vom Abfragen zu Webhooks, sodass du benachrichtigt wirst, sobald jeder Job fertig ist.
Vom Ordner zur Pipeline
Nebenläufigkeit
Konvertiere mehrere Dateien gleichzeitig mit einem begrenzten Worker-Pool. Beginne mit etwa fünf in Bearbeitung und stimme es auf deinen Tarif ab.
Idempotente Retries
Ein stabiler Schlüssel pro Datei (Dateiname oder Inhalts-Hash) macht einen erneuten Lauf sicher, sodass ein halb fertiger Stapel sauber fortgesetzt wird.
Webhooks
Bei Tausenden Dateien lass Webhooks dir sagen, wann jeder Job bereit ist, statt sie alle abzufragen.
Befüllst du eine Wissensdatenbank?
Ein Stapel PDFs wird zu einem Ordner voller sauberem Markdown, bereit zum Chunken und Einbetten. Siehe die RAG-Anleitung, um diese Ausgabe in abrufbaren Kontext zu verwandeln.
Fehler über einen Stapel hinweg behandeln
In einem echten Lauf werden ein paar Dateien passwortgeschützt, beschädigt oder schlicht zu groß sein. Das Ziel ist, den Stapel zu Ende laufen zu lassen und dir zu sagen, was übersprungen wurde, statt bei der ersten schlechten Datei zu stoppen.
Überspringen und protokollieren, nicht stoppen
Wenn ein Job mit status: error zurückkommt, halte den Dateinamen und seinen error_code in einem Log fest und mach weiter. Am Ende hast du einen sauberen Satz Markdown-Dateien plus eine kurze Liste derer, die Aufmerksamkeit brauchen, statt eines Stapels, der auf halbem Weg gestorben ist.
Sicher fortsetzen
Weil jedes Erstellen den Dateinamen (oder einen Inhalts-Hash) als seinen Idempotency-Key verwendet, ist das erneute Ausführen des gesamten Stapels sicher: fertige Dateien liefern ihren bestehenden Job zurück, und nur die zuvor fehlgeschlagenen oder unverarbeiteten machen echte Arbeit. Ein nächtlicher Job kann denselben Ordner erneut ausführen, ohne alles zu wiederholen.
Zwei weitere Details halten große Läufe ordentlich. Schreibe jedes Ergebnis neben seine Quelle (report.pdf wird zu report.md), damit die Zuordnung offensichtlich ist, und prüfe das truncated-Flag bei jedem Job, da ein sehr langes Dokument als Teilergebnis zurückkommen kann, das das Zeitbudget erreicht hat. Im Gratis-Tarif sind die Slot- und Größenlimits niedriger, ein großer Stapel ist also ein guter Grund, auf einen bezahlten Tarif umzusteigen, der Nebenläufigkeit, Dateigröße und das monatliche Seitenkontingent erhöht.
Häufige Fragen
Wie konvertiere ich viele PDFs auf einmal?
Führe den Erstellen-, Abfrage- und Download-Ablauf pro Datei in einer Schleife aus. Verwende einen Idempotency-Key pro Datei, damit ein erneuter Lauf keine Arbeit dupliziert, und ein kleines Nebenläufigkeitslimit, um die API zu schonen.
Gibt es einen einzelnen Bulk-Endpoint?
Die Konvertierung läuft pro Job, ein Stapel sind also viele Jobs. Dieselbe Schleife skaliert von einer Handvoll Dateien bis zu Tausenden; ergänze Nebenläufigkeit und Webhooks für große Läufe.
Wie vermeide ich, dass Dateien bei einem Retry erneut konvertiert werden?
Übergib beim Erstellen einen stabilen Idempotency-Key, zum Beispiel den Dateinamen oder einen Inhalts-Hash. Derselbe Key liefert denselben Job zurück, statt eine doppelte Konvertierung zu starten.
Wie viele kann ich parallel laufen lassen?
Beginne mit einem kleinen Pool, zum Beispiel fünf, und passe ihn an. Der Gratis-Tarif hat niedrigere Slot-Limits; bezahlte Tarife erhöhen Slots und Durchsatz.
Kann ich Webhooks nutzen, statt jeden Job abzufragen?
Ja. Bei großen Stapeln benachrichtigen dich Webhooks, sobald jeder Job fertig ist, was besser skaliert als das Abfragen Tausender Jobs. Siehe den Entwickler-Hub.