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.
| Schnittstelle | Am besten für | Installation oder Adresse | Anleitung |
|---|---|---|---|
| REST-API | Jede Sprache, Server, Shell-Skripte | https://pdf123.xyz/api/v1 | API-Referenz |
| TypeScript-SDK | Node-, Bun- und Browsercode, der Typen braucht | npm install @pdf123/sdk | SDK-Anleitung |
| Kommandozeile | Terminals, CI-Jobs, Stapel lokaler Dateien | npm install -g @pdf123/cli | CLI-Anleitung |
| MCP | KI-Agenten wie Claude Code, Claude Desktop und Cursor | npx -y @pdf123/mcp oder https://pdf123.xyz/mcp | MCP-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.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfDasselbe Zusammenführen mit dem TypeScript-SDK:
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:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfWie 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…
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.pdfDas 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.
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.pdfWie 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?
| Limit | Wert |
|---|---|
| Dateigröße auf der Website | 500 MB pro Datei |
| Ein direkter API-Request-Body | 100 MiB, Multipart-Rahmen eingerechnet |
| Chunk-Upload | Das 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 Grund | HTTP-Status | Bedeutung |
|---|---|---|
bad_request | 400 | Ungültige Parameter oder ungültiger Multipart-Body |
password_required | 400 | Die PDF ist verschlüsselt und es wurde kein Passwort gesendet |
invalid_pdf | 400 | Die Datei ist keine PDF oder beschädigt; probieren Sie PDF reparieren |
page_out_of_range | 400 | Eine angeforderte Seite existiert nicht |
not_found | 404 | Unbekannter Operationspfad |
rate_limited | 429 | Kontingent 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.
| Werkzeugseite | API-Endpunkt | CLI-Befehl | Funktion |
|---|---|---|---|
| Zusammenführen | /general/merge-pdfs | pdfx merge | Mehrere PDFs zu einer verbinden |
| Teilen | /general/split-pages | pdfx split | Eine PDF in einzelne Dateien aufteilen |
| Komprimieren | /misc/compress-pdf | pdfx compress | PDF-Streams neu komprimieren, um die Größe zu verringern |
| Drehen | /general/rotate-pdf | pdfx rotate | Seitenausrichtung ändern |
| Schützen | /security/add-password | pdfx protect | Eine PDF mit einem Passwort verschlüsseln |
| Entsperren | /security/remove-password | pdfx unlock | Passwortschutz entfernen |
| Wasserzeichen | /security/add-watermark | pdfx watermark | Text- oder Bildwasserzeichen hinzufügen |
| OCR | /misc/ocr-pdf | pdfx ocr | Eine gescannte PDF lesen und Markdown zurückgeben |
| PDF in Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Eine PDF in Markdown umwandeln |
| PDF in Word | /convert/pdf/word | pdfx convert-to-word | Eine PDF in eine bearbeitbare Word-Datei umwandeln |
| Dokumentinfo | /security/get-info-on-pdf | pdfx get-info | Metadaten, Berechtigungen, Schriften und Struktur ausgeben |
| Reparieren | /misc/repair | pdfx repair | Die 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/mcpfür Dateien auf Ihrem Rechner und den gehosteten Endpunkt unterhttps://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.jsonldbeschreibt 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.