Dieselbe Operation, vier Clients: Browser, curl, MCP, pdfx
Derselbe Merge in PDF123 über vier Clients: Browserformular, curl an /api/v1/general/merge-pdfs, MCP unter /mcp und pdfx lokal oder mit --cloud gegen eine API-Basis.
Vier Clients wirken wie vier Produkte. Sie teilen einen Katalog. Nimm Zusammenführen als konkrete Aufgabe: PDFs in der Reihenfolge des Uploads verbinden, ohne Seiten in Bilder umzuwandeln. Dasselbe Muster gilt für jedes andere Werkzeug des Katalogs (Komprimieren, OCR, Konvertieren und der Rest): eine Kennung der Operation, vier Wege sie aufzurufen.
Browser
Öffne /de/merge, füge die Dateien in der gewünschten Reihenfolge hinzu, klicke auf Verarbeiten und lade herunter. Für Werkzeuge des Katalogs ist kein Konto nötig. Der Block „Call this from code“ auf der Seite baut ein curl aus denselben Feldern, die das Formular sendet, damit Oberfläche und Vertrag über HTTP aufeinander abgestimmt bleiben.
Dieser Block ist kein Werbetext. Er wird aus der Definition des Werkzeugs erzeugt, die das Portal bereits für das Formular verwendet; deshalb erscheint eine Umbenennung eines Parameters an beiden Stellen zugleich. Nimmt das Formular das optionale sortType=byFileName entgegen, kann das Beispiel für curl dasselbe Feld enthalten.
curl / REST
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
Anonyme Aufrufe des Katalogs brauchen keinen Schlüssel. Schlüssel von Entwickler geben der Automatisierung eine stabile Identität (und selbst gehosteten Servern eine Sperre). OpenAPI liegt unter /v1/openapi.json.
Für Aufgaben mit mehreren Schritten nimmt POST /api/v1/pipeline geordnete Operationen in einem Feld steps entgegen (zum Beispiel zusammenführen, dann Wasserzeichen, dann komprimieren). Sende Idempotency-Key, wenn Wiederholungen die Arbeit nicht doppelt ausführen dürfen; eine erfolgreiche Wiederholung kann mit Idempotency-Replayed zurückkommen. Fehler nutzen application/problem+json mit stabilen Codes wie rate_limited und bad_request (Entwickler: Fehler).
Antworten der gehosteten Variante enthalten außerdem X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset; HTTP 429 enthält Retry-After. Behandle diese Header als das aktuelle Budget und nicht als eine Zahl, die du dir aus einem Blogbeitrag gemerkt hast (anonyme Ratenbegrenzung).
MCP
Agenten, die das Model Context Protocol sprechen, verbinden sich mit /mcp, entdecken das Zusammenführen als Werkzeug und rufen es mit derselben Geschichte der Schlüssel wie bei REST auf. Dokumentation: Entwickler: MCP.
MCP ist kein zweiter Katalog. Es ist ein Protokoll zum Entdecken und Aufrufen derselben Operationen, die OpenAPI auflistet. Fehlt eine Operation in MCP, ist das ein Fehler des Servers und keine eigene Produktplanung. Kombiniere MCP mit /llms.txt, wenn du vor dem Verbinden des Clients einen Index der Werkzeuge in Prosa willst.
pdfx CLI
Lokales pdf-core:
pdfx merge a.pdf b.pdf -o merged.pdf
Oder derselbe Server, den das Portal nutzt:
pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
Der lokale Modus lädt nie hoch; der Cloud-Modus spricht deine Basis-URL mit derselben Multipart-Form wie curl an. Der Skill für Coding-Agenten unter dist/skills/pdf-toolbox/SKILL.md dokumentiert dieselben Formen für das Zusammenführen und für Pipelines, damit Agenten kein zweites OpenAPI erfinden.
OCR liefert über jeden dieser Clients weiterhin Markdown von /api/v1/misc/ocr-pdf und keine verborgene Textebene. Diese Tatsache gehört zum gemeinsamen Vertrag: den Rückgabetyp in einem Client zu ändern, ohne die anderen anzupassen, würde das Versprechen derselben Operation brechen. Komprimieren bleibt auf /api/v1/misc/compress-pdf für die Rekompression von Streams; es ist eine andere Operation als das Zusammenführen und auf dieselben vier Wege erreichbar.
Warum die Gleichheit zählt
Würden das Zusammenführen im Browser und über die API jemals auseinanderlaufen, würden Automatisierungen stillschweigend schlechter, während die Vorführseite weiter gut aussähe. Eine Operation, vier Zugänge, das ist der Punkt. Das Portal ist ein bequemer Client und keine zweite Umsetzung von Zusammenführen, Komprimieren oder OCR.
Deshalb gibt es auch keinen Ableger für den Desktop: ein fünfter Baum von Oberflächen würde das Problem der Abweichung unter einem anderen Namen einer Binärdatei neu schaffen. Der größere Zusammenhang steht in Für KI-Agenten gebaut, nicht nur für Browser. Zur Entscheidung über den Desktop siehe Warum wir auf die Desktop-App verzichtet haben. Zum Betrieb der API in deinem Netz siehe Selbst hosten.