Zum Hauptinhalt springen
PPDF123

PDF123 für Entwickler: REST-API, SDK, Kommandozeile und MCP

Die Entwicklerplattform von PDF123 stellt dieselben 97 PDF-Werkzeuge über vier Schnittstellen bereit: eine mit OpenAPI beschriebene REST-API, ein TypeScript-SDK, die Kommandozeile pdfx und MCP-Server für KI-Agenten. Anonyme Aufrufe brauchen weder Konto noch API-Schlüssel.

Auf dieser Seite

Wie nutze ich PDF123 aus dem Code heraus?

Alle vier Schnittstellen rufen dieselben Operationen auf, ein Zusammenführen liefert also überall dasselbe Ergebnis. Wählen Sie danach, wo Ihr Code läuft.

SchnittstelleAm besten fürInstallation oder AdresseAnleitung
REST-APIJede Sprache, Server, Shell-Skriptehttps://pdf123.xyz/api/v1API-Referenz
TypeScript-SDKNode-, Bun- und Browsercode, der Typen brauchtnpm install @pdf123/sdkSDK-Anleitung
KommandozeileTerminals, CI-Jobs, Stapel lokaler Dateiennpm install -g @pdf123/cliCLI-Anleitung
MCPKI-Agenten wie Claude Code, Claude Desktop und Cursornpx -y @pdf123/mcp oder https://pdf123.xyz/mcpMCP-Anleitung

Nutzen Sie die REST-API, wenn Ihr Code nicht in TypeScript geschrieben ist. Nutzen Sie das SDK, wenn er es ist, denn die Optionen der Werkzeuge sind typisiert und werden vor dem Hochladen geprüft. Nutzen Sie die Kommandozeile für einmalige Aufgaben und Shell-Skripte. Nutzen Sie MCP, wenn ein KI-Agent entscheiden soll, welches Werkzeug läuft.

Der Katalog umfasst 97 Werkzeuge. 58 davon haben eine eigene Seite auf dieser Website, zum Beispiel PDF zusammenführen, PDF teilen und PDF komprimieren. Die übrigen sind Backend-Operationen ohne Webseite; alle stehen im SDK, in der Kommandozeile und in MCP zur Verfügung.

Wie führe ich meine erste Anfrage aus?

Führen Sie zwei Dateien mit curl zusammen. Die Anfrage ist ein Multipart-Formular mit einem Teil fileInput pro Datei.

REST: zwei PDFs zusammenführenbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

Dasselbe Zusammenführen mit dem TypeScript-SDK:

SDK: zwei PDFs zusammenführents
import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const result = await client.run("merge", {
  input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
await saveResult(result, { output: "merged.pdf" });

Dasselbe Zusammenführen mit der Kommandozeile:

CLI: zwei PDFs zusammenführenbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

Wie funktioniert die Authentifizierung?

Anonyme Aufrufe der öffentlichen API brauchen weder Konto noch Schlüssel. Senden Sie einen API-Schlüssel im Header X-API-KEY, wenn Sie Ihren Datenverkehr kenntlich machen oder den gehosteten MCP-Endpunkt aufrufen wollen, der immer einen Schlüssel verlangt.

Melden Sie sich an, um im folgenden Bereich einen Schlüssel zu erstellen, und bewahren Sie ihn sicher auf.

Sitzung wird geprüft…

API mit Schlüssel aufrufenbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -H "X-API-KEY: <your-key>" \
  -F [email protected] -F [email protected] -o merged.pdf

Das SDK erhält den Schlüssel als apiKey. Die Kommandozeile und der lokale MCP-Server lesen ihn aus der Umgebungsvariable PDFX_API_KEY.

Hinweis

Auf einem selbst gehosteten Server legen Sie mit der Umgebungsvariable SECURITY_CUSTOMGLOBALAPIKEY einen Schlüssel fest, den der Server akzeptiert. Siehe Self-Host.

Wo finde ich die API-Referenz?

Die REST-API ist in zwei Formen dokumentiert. In Swagger UI können Sie jeden Endpunkt direkt im Browser ausprobieren. Das OpenAPI-Dokument ist die maschinenlesbare Quelle für Client-Generatoren.

Jede Operation ist ein POST unterhalb der Basis-URL https://pdf123.xyz/api/v1, nach Kategorien gegliedert. Zusammenführen ist zum Beispiel /general/merge-pdfs und Komprimieren /misc/compress-pdf.

Wie verkette ich mehrere Werkzeuge in einer Anfrage?

POST /api/v1/pipeline nimmt die Teile fileInput und ein Feld steps entgegen. Dieses Feld ist ein JSON-Array aus Objekten mit op und optionalen params. Jeder Schritt erhält die Ausgabe des vorherigen.

Zusammenführen und danach komprimieren, in einer Anfragebash
curl -X POST https://pdf123.xyz/api/v1/pipeline \
  -F [email protected] -F [email protected] \
  -F 'steps=[{"op":"general/merge-pdfs"},{"op":"misc/compress-pdf"}]' \
  -o out.pdf

Wie wiederhole ich eine Anfrage sicher?

Senden Sie bei jeder Operation einen Header Idempotency-Key. Eine Wiederholung derselben Anfrage innerhalb von 24 Stunden liefert das erste Ergebnis mit dem Header Idempotency-Replayed: true, statt erneut zu laufen. Wird derselbe Schlüssel für eine andere Anfrage verwendet, wird sie abgelehnt. Ergebnisse über 32 MiB werden nicht gespeichert; eine Wiederholung einer solchen Anfrage wird daher mit 409 beantwortet und braucht einen neuen Schlüssel.

Welche Größen- und Ratenlimits gibt es?

LimitWert
Dateigröße auf der Website500 MB pro Datei
Ein direkter API-Request-Body100 MiB, Multipart-Rahmen eingerechnet
Chunk-UploadDas SDK wechselt ab insgesamt 95 MB automatisch zur Upload-API

Antworten enthalten die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Eine Antwort mit Status 429 enthält zusätzlich Retry-After. Lesen Sie die Header, statt ein festes Kontingent anzunehmen, denn ein selbst gehosteter Server legt eigene Limits fest. Der Blogbeitrag zum Limit der Anfragegröße erklärt den Fehler bei einem zu großen Body.

Wie sieht ein Fehler aus?

Fehlschläge liefern application/problem+json mit den Feldern type, title, status, detail, code, reason und hint. Verzweigen Sie anhand von reason und greifen Sie auf code zurück. Der Text in detail ist für Menschen geschrieben und enthält nie die Rohausgabe eines Werkzeugs. Alle Codes stehen unter Fehlercodes.

Code oder GrundHTTP-StatusBedeutung
bad_request400Ungültige Parameter oder ungültiger Multipart-Body
password_required400Die PDF ist verschlüsselt und es wurde kein Passwort gesendet
invalid_pdf400Die Datei ist keine PDF oder beschädigt; probieren Sie PDF reparieren
page_out_of_range400Eine angeforderte Seite existiert nicht
not_found404Unbekannter Operationspfad
rate_limited429Kontingent aufgebraucht; warten Sie die Zeit aus Retry-After ab

Welche Werkzeuge kann ich zuerst aufrufen?

Diese zwölf Werkzeuge decken die meisten Anfragen ab. Auf der Werkzeugseite können Sie ein Werkzeug im Browser ausprobieren.

WerkzeugseiteAPI-EndpunktCLI-BefehlFunktion
Zusammenführen/general/merge-pdfspdfx mergeMehrere PDFs zu einer verbinden
Teilen/general/split-pagespdfx splitEine PDF in einzelne Dateien aufteilen
Komprimieren/misc/compress-pdfpdfx compressPDF-Streams neu komprimieren, um die Größe zu verringern
Drehen/general/rotate-pdfpdfx rotateSeitenausrichtung ändern
Schützen/security/add-passwordpdfx protectEine PDF mit einem Passwort verschlüsseln
Entsperren/security/remove-passwordpdfx unlockPasswortschutz entfernen
Wasserzeichen/security/add-watermarkpdfx watermarkText- oder Bildwasserzeichen hinzufügen
OCR/misc/ocr-pdfpdfx ocrEine gescannte PDF lesen und Markdown zurückgeben
PDF in Markdown/convert/pdf/markdownpdfx pdf-to-markdownEine PDF in Markdown umwandeln
PDF in Word/convert/pdf/wordpdfx convert-to-wordEine PDF in eine bearbeitbare Word-Datei umwandeln
Dokumentinfo/security/get-info-on-pdfpdfx get-infoMetadaten, Berechtigungen, Schriften und Struktur ausgeben
Reparieren/misc/repairpdfx repairDie Struktur einer beschädigten PDF wiederherstellen

Die Endpunkte gelten relativ zu https://pdf123.xyz/api/v1. Mit pdfx list oder im OpenAPI-Dokument sehen Sie alle 97 Werkzeuge.

Wie nutze ich PDF123 mit einem KI-Agenten?

Ein Agent kann die Werkzeuge auf drei Wegen nutzen:

  • Einen MCP-Server anbinden. Die MCP-Anleitung behandelt den lokalen Server @pdf123/mcp für Dateien auf Ihrem Rechner und den gehosteten Endpunkt unter https://pdf123.xyz/mcp.
  • Einen Agent-Skill laden. Agent-Skills sind SKILL.md-Dateien für Claude Code, Codex, Cursor und ähnliche Tools, eine für den Katalog und eine pro Werkzeug.
  • Den Website-Index lesen. /llms.txt listet die Werkzeuge, die API und den MCP-Endpunkt als reinen Text, und /site.jsonld beschreibt die Website als strukturierte Daten.

Der Blogbeitrag „Built for AI Agents, Not Just Browsers“ im PDF123-Blog erklärt, wie REST-API und MCP zusammenpassen.

Kann ich PDF123 auf dem eigenen Server betreiben?

Ja. Das Backend ist das Programm pdfx-server, das in Docker läuft. Richten Sie das SDK, die Kommandozeile oder den MCP-Server mit PDFX_API_BASE darauf aus, und Ihre Dateien bleiben in Ihrem Netzwerk. Die Einrichtung beschreibt Self-Host, Support-Optionen finden Sie unter Enterprise.

FAQ

Ist die PDF123-API kostenlos?

Ja, bei anonymer Nutzung. Aufrufe der öffentlichen API brauchen weder Konto noch Schlüssel. Antworten des gehosteten Dienstes enthalten Rate-Limit-Header, sodass ein Client langsamer werden kann, bevor er eine Antwort mit Status 429 erhält.

Brauche ich einen API-Schlüssel?

Nein für die REST-API, das SDK und die Kommandozeile, wenn Sie die öffentliche Website nutzen. Ja für den gehosteten MCP-Endpunkt unter /mcp, der ohne Header X-API-KEY mit 401 antwortet. Nach der Anmeldung können Sie auf dieser Seite einen Schlüssel erstellen.

Wie groß dürfen Dateien sein?

Die Website akzeptiert Dateien bis 500 MB pro Datei. Ein einzelner direkter API-Request-Body darf bis zu 100 MiB groß sein, Multipart-Rahmen eingerechnet. Das SDK lädt größere Eingaben automatisch in Chunks hoch, sobald die Gesamtgröße 95 MB überschreitet.

Kann ich die API selbst hosten?

Ja. Betreiben Sie den Server selbst und setzen Sie die API-Basis auf seine Adresse. Das SDK, die Kommandozeile und der lokale MCP-Server akzeptieren alle eine eigene Basis-URL.

Wie melde ich einen Fehler?

Kopieren Sie die Felder code, reason und detail aus der Problem-Antwort sowie den Zeitpunkt der Anfrage und senden Sie sie über die Kontaktseite. Senden Sie die PDF selbst nur, wenn der Support danach fragt.

Soll ich das SDK, die Kommandozeile oder MCP verwenden?

Verwenden Sie das SDK in TypeScript-Code, die Kommandozeile für Skripte und Stapel lokaler Dateien und MCP, wenn ein KI-Agent das Werkzeug auswählt. Alle drei nutzen denselben Katalog und denselben Server, Sie können sie also kombinieren.