@pdf123/sdk: das TypeScript-SDK von PDF123

Wie installiere ich das SDK?#

Installieren Sie das Paket mit Ihrem Paketmanager. Erforderlich ist Node 20.3 oder neuer, Bun oder ein Bundler. TypeScript-Typen sind enthalten, @types/node wird nicht benötigt.

npm install @pdf123/sdk

bun add @pdf123/sdk und pnpm add @pdf123/sdk funktionieren genauso.

Wie führe ich zwei PDFs zusammen?#

Erstellen Sie einen Client, führen Sie das Werkzeug merge auf zwei Dateien aus und speichern Sie das Ergebnis. Ohne Optionen spricht der Client die öffentliche API anonym an.

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")],
});
const path = await saveResult(result, { output: "merged.pdf" });
console.log(path);

Das Ergebnis enthält die Bytes in data, den contentType, den filename des Servers und json für Werkzeuge, die einen Bericht liefern. Dieselbe Operation gibt es auf der Website als PDF zusammenführen.

Welchen Einstiegspunkt importiere ich?#

Importieren Sie in Browsern und Edge-Laufzeiten vom Root-Einstiegspunkt und fügen Sie den Einstiegspunkt node nur dort hinzu, wo Sie Dateien lesen oder schreiben.

Welche Methoden hat der Client?#

Die Katalog-Helfer sind einfache Funktionen: TOOLS listet alle Werkzeuge, getTool(id) liefert Felder, Standardwerte und akzeptierte Dateitypen eines Werkzeugs, und toolGroup, toolSummary, matchesQuery und suggestTools helfen beim Bau von Werkzeugauswahlen. Die Kommandozeile gibt denselben Katalog mit pdfx list und pdfx describe aus.

Wie übergebe ich Optionen an ein Werkzeug?#

params ist pro Werkzeug typisiert. Es akzeptiert nur die Felder dieses Werkzeugs, und Auswahlfelder nur ihre erlaubten Werte. Zahlenfelder werden gegen Minimum und Maximum geprüft, eine Datei gegen die akzeptierten Typen, und zwar bevor etwas hochgeladen wird. Standardwerte, die der Server braucht, werden ergänzt.

const marked = await client.run("watermark", {
  input: await readFileInput("a.pdf"),
  params: { watermarkText: "DRAFT", fontSize: 40, rotation: -45 },
});
await saveResult(marked, { output: "draft.pdf" });

Eine leere Zeichenfolge bedeutet „nicht gesetzt“, es gilt also der Standardwert. Was die einzelnen Optionen bewirken, steht unter PDF-Wasserzeichen.

Wie verarbeite ich viele Dateien?#

runBatch führt ein Einzeldatei-Werkzeug wie Komprimieren, Drehen oder Schützen mit denselben Optionen auf jeder Eingabe aus. Standardmäßig laufen zwei Dateien gleichzeitig. Eine fehlerhafte Datei stoppt die anderen nie.

import { fileSource, saveResult } from "@pdf123/sdk/node";

const controller = new AbortController();
const entries = await client.runBatch("compress", [fileSource("a.pdf"), fileSource("b.pdf")], {
  concurrency: 2,
  signal: controller.signal,
  onResult: async (entry, index) => {
    if (entry.ok) await saveResult(entry.result, { output: "compressed/" });
  },
});
console.log(entries.map((entry) => entry.ok));

• fileSource(path) ist eine verzögerte Quelle, die erst gelesen wird, wenn ein Worker sie übernimmt. So liegen viele große Dateien nie gleichzeitig im Speicher.
• onResult erhält jedes Ergebnis, sobald es fertig ist. Speichern Sie es dort; bricht man bei Datei 50 von 100 ab, bleiben die ersten 49 erhalten. Mit retainData: false behält das zurückgegebene Array die Bytes nicht.
• Jeder Aufruf akzeptiert timeoutMs und ein signal zum Abbrechen.
• idempotencyKey wird für jede Datei zu <key>:<index>.

Filter-Werkzeuge (IDs, die mit filter- beginnen) liefern matched: false, statt einen Fehler auszulösen, wenn ihre Bedingung nicht zutrifft. In einem Stapel zählt eine solche Datei trotzdem als ok.

Wie verkette ich Werkzeuge in einer Anfrage?#

pipeline sendet eine Liste von Schritten und eine oder mehrere Eingaben. Der Server leitet die Ausgabe jedes Schritts in den nächsten weiter.

const piped = await client.pipeline(
  [{ tool: "merge" }, { tool: "watermark", params: { watermarkText: "DRAFT" } }, { tool: "compress" }],
  [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
);
await saveResult(piped, { output: "out.pdf" });

Pipelines akzeptieren dieselben Passwortoptionen wie run.

Wie arbeite ich mit verschlüsselten PDFs?#

Übergeben Sie password an run, um eine verschlüsselte Eingabe zuerst zu öffnen. Entsperren und Werkzeug laufen in einer Anfrage. Bei Werkzeugen mit mehreren Dateien wie Zusammenführen übergeben Sie passwords mit einem Eintrag pro Eingabe; für eine nicht geschützte Datei steht eine leere Zeichenfolge. Jede Datei wird einzeln entsperrt.

await client.run("compress", { input: await readFileInput("locked.pdf"), password: "secret" });
await client.run("merge", {
  input: [await readFileInput("locked.pdf"), await readFileInput("open.pdf")],
  passwords: ["secret", ""],
});

Bei einem Stapel liefert passwordFor(file, index) das Passwort für jede Eingabe. Um den Schutz dauerhaft zu entfernen, nutzen Sie das Werkzeug Entsperren.

Wie funktionieren Fehler?#

Fehlschläge lösen Pdf123Error aus. Die Klasse hat status (undefined, wenn es keine Antwort gab), code, reason für die genaue Ursache wie password_required und problem mit den Problemdetails des Servers, die bei Bedarf hint enthalten. Validierungsfehler werden ausgelöst, bevor etwas hochgeladen wird.

import { Pdf123Error } from "@pdf123/sdk";

try {
  await client.run("compress", { input: await readFileInput("locked.pdf") });
} catch (error) {
  if (error instanceof Pdf123Error) {
    console.error(error.status, error.code, error.reason, error.problem?.hint);
  } else {
    throw error;
  }
}

Die Server-Codes stehen unter Fehlercodes. Der Client ergänzt diese eigenen Codes:

saveResult überschreibt nie eine Datei in einem Verzeichnis. Rufen Sie zuerst checkOutput(output, { several }) auf, um vor dem Hochladen zu erfahren, ob ein Pfad beschreibbar ist.

Welche TypeScript- und Moduleinstellungen funktionieren?#

Die Typen werden mit den moduleResolution-Einstellungen nodenext, node16, bundler und dem älteren node10 aufgelöst, einschließlich des Subpfads @pdf123/sdk/node. Das Paket ist ein ES-Modul, daher funktioniert import überall. require("@pdf123/sdk") aus CommonJS funktioniert ab Node 22.12 und ist unter Node 20 nicht verfügbar.

Wie konfiguriere ich den Client?#

new Pdf123Client() liest nie die Umgebung. clientFromEnv() aus @pdf123/sdk/node liest die beiden Variablen, und übergebene Optionen haben Vorrang. Der Schlüssel wird als Header X-API-KEY gesendet; siehe Authentifizierung.

Für einen eigenen Server setzen Sie baseUrl auf dessen Adresse, zum Beispiel http://localhost:8080. Siehe Self-Host.

Kann ich das SDK im Browser verwenden?#

Ja. Der Root-Einstiegspunkt @pdf123/sdk braucht nur fetch und hat keine Node-Abhängigkeiten. Erstellen Sie FileInput-Objekte selbst aus einer File oder einem Uint8Array, denn die Datei-Helfer liegen im Einstiegspunkt node. Liefern Sie keinen API-Schlüssel in Browsercode aus, den andere lesen können.

Weiterführende Seiten#

• Entwicklerübersicht mit REST-API und Authentifizierung
• Kommandozeile pdfx, aufgebaut auf diesem SDK
• MCP-Server für KI-Agenten
• Swagger UI und das OpenAPI-Dokument
• Werkzeugseiten: Zusammenführen, Teilen, Komprimieren, OCR, Schützen

FAQ#

Braucht das SDK einen API-Schlüssel?#

Nein. Ein Client, der ohne Optionen erstellt wurde, ruft die öffentliche API anonym auf. Übergeben Sie apiKey, um den Header X-API-KEY zu senden.

Welche Node-Version braucht das SDK?#

Node 20.3 oder neuer, oder Bun. Der Root-Einstiegspunkt braucht nur fetch und läuft daher auch in Browsern und Bundlern.

Wie erhalte ich ein Werkzeug, das neuer ist als das SDK?#

Nutzen Sie client.call. Es nimmt eine Werkzeug-ID, eine Operations-ID wie general/merge-pdfs oder einen /api/...-Pfad sowie Dateien und Felder entgegen. Lokal wird nichts validiert oder mit Standardwerten ergänzt.

Wie große Dateien kann ich hochladen?#

Eingaben mit insgesamt mehr als 95 MB laufen automatisch über die Chunk-Upload-API. Ein einzelner direkter Request-Body ist auf 100 MiB begrenzt.

Warum hat mein Aufruf für eine PDF ohne Tabellen einen Fehler ausgelöst?#

Werkzeuge wie pdf-to-csv und pdf-to-xlsx antworten ohne Inhalt, wenn die PDF keine erkennbare Tabelle enthält. Das SDK löst dann Pdf123Error mit dem Code no_content aus, statt eine leere Datei zurückzugeben. Prüfen Sie diesen Code, wenn ein leeres Ergebnis für Sie in Ordnung ist.