@pdf123/sdk: PDF123:s TypeScript-SDK

Hur installerar jag SDK:n?#

Installera paketet med din pakethanterare. Node 20.3 eller senare, Bun eller en bundlare krävs. TypeScript-typer ingår och @types/node behövs inte.

npm install @pdf123/sdk

bun add @pdf123/sdk och pnpm add @pdf123/sdk fungerar på samma sätt.

Hur slår jag ihop två PDF:er?#

Skapa en klient, kör verktyget merge på två filer och spara resultatet. Utan alternativ anropar klienten det publika API:t anonymt.

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);

Resultatet innehåller bytena i data, contentType, serverns filename och json för verktyg som returnerar en rapport. Samma operation finns som Slå ihop PDF på webbplatsen.

Vilken ingångspunkt ska jag importera?#

Importera från rotens ingångspunkt i webbläsare och edge-miljöer, och lägg bara till ingångspunkten node där du läser eller skriver filer.

Vilka metoder har klienten?#

Katalogens hjälpfunktioner är vanliga funktioner: TOOLS listar alla verktyg, getTool(id) returnerar fält, standardvärden och godtagna filtyper för ett verktyg, och toolGroup, toolSummary, matchesQuery och suggestTools hjälper dig bygga verktygsväljare. Kommandoraden skriver ut samma katalog med pdfx list och pdfx describe.

Hur skickar jag alternativ till ett verktyg?#

params är typat per verktyg. Det godtar bara det verktygets fält, och val-fält godtar bara sina tillåtna värden. Talfält kontrolleras mot sitt minimum och maximum, och en fil kontrolleras mot de godtagna typerna, innan något laddas upp. Standardvärden som servern behöver fylls i.

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

En tom sträng betyder "inte angivet", så standardvärdet gäller. På sidan Lägg till vattenmärke förklaras vad varje alternativ gör.

Hur bearbetar jag många filer?#

runBatch kör ett enfilsverktyg, till exempel Komprimera, Rotera eller Lägg till lösenord, på varje indata med samma alternativ. Som standard körs två filer åt gången. En felaktig fil stoppar aldrig de andra.

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) är en lat källa som läses först när en arbetare tar den, så många stora filer ligger aldrig i minnet samtidigt.
• onResult får varje resultat så fort det är klart. Spara det där, så behåller ett avbrott vid fil 50 av 100 de första 49. Med retainData: false behåller den returnerade arrayen inte bytena.
• Varje anrop godtar timeoutMs och en signal för att avbryta det.
• idempotencyKey blir <key>:<index> för varje fil.

Filterverktyg (id:n som börjar med filter-) returnerar matched: false i stället för att kasta ett fel när deras villkor inte uppfylls. I en batch räknas en sådan fil ändå som ok.

Hur kedjar jag verktyg i en och samma begäran?#

pipeline skickar en lista med steg och en eller flera indatafiler. Servern matar varje stegs utdata vidare till nästa steg.

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 godtar samma lösenordsalternativ som run.

Hur arbetar jag med krypterade PDF:er?#

Ange password till run för att först öppna en krypterad indatafil. Upplåsningen och verktyget körs i samma begäran. För verktyg som tar flera filer, till exempel Slå ihop, anger du passwords med en post per indatafil, med en tom sträng för en öppen fil. Varje fil låses upp separat.

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", ""],
});

För en batch returnerar passwordFor(file, index) lösenordet för varje indatafil. Om du vill ta bort skyddet permanent använder du verktyget Ta bort lösenord.

Hur fungerar fel?#

Misslyckade anrop kastar Pdf123Error. Det har status (undefined när något svar saknas), code, reason för den detaljerade orsaken, till exempel password_required, och problem med serverns problemdetaljer, som innehåller hint när det finns en. Valideringsfel kastas innan något laddas upp.

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;
  }
}

Serverkoderna finns listade under Felkoder. Klienten lägger till dessa egna koder:

saveResult skriver aldrig över en fil i en katalog. Anropa checkOutput(output, { several }) först för att redan före uppladdningen ta reda på om en sökväg går att skriva till.

Vilka TypeScript- och modulinställningar fungerar?#

Typerna fungerar med moduleResolution-inställningarna nodenext, node16, bundler och den äldre node10, inklusive undersökvägen @pdf123/sdk/node. Paketet är en ES-modul, så import fungerar överallt. require("@pdf123/sdk") från CommonJS fungerar på Node 22.12 eller senare och är inte tillgängligt på Node 20.

Hur konfigurerar jag klienten?#

new Pdf123Client() läser aldrig miljön. clientFromEnv() från @pdf123/sdk/node läser de två variablerna, och alternativ du anger har företräde. Nyckeln skickas som rubriken X-API-KEY; se Autentisering.

Om du vill använda din egen server anger du dess adress i baseUrl, till exempel http://localhost:8080. Se Self-host.

Kan jag använda SDK:n i en webbläsare?#

Ja. Rotens ingångspunkt @pdf123/sdk behöver bara fetch och har inga Node-beroenden. Bygg FileInput-objekt själv från en File eller en Uint8Array, eftersom filhjälparna finns i ingångspunkten node. Lägg inte en API-nyckel i webbläsarkod som andra kan läsa.

Relaterade sidor#

• Översikt för utvecklare med REST API och autentisering
• Kommandoraden pdfx, byggd på den här SDK:n
• MCP-servrar för AI-agenter
• Swagger UI och OpenAPI-dokumentet
• Verktygssidor: Slå ihop, Dela, Komprimera, OCR, Lägg till lösenord

Vanliga frågor#

Behöver SDK:n en API-nyckel?#

Nej. En klient som skapas utan alternativ anropar det publika API:t anonymt. Ange apiKey för att skicka rubriken X-API-KEY.

Vilken Node-version kräver SDK:n?#

Node 20.3 eller senare, eller Bun. Rotens ingångspunkt behöver bara fetch, så den fungerar även i webbläsare och bundlare.

Hur når jag ett verktyg som är nyare än SDK:n?#

Använd client.call. Den tar ett verktygs-id, ett operations-id som general/merge-pdfs eller en /api/...-sökväg, samt filer och fält. Inget valideras eller får standardvärden lokalt.

Hur stor fil kan jag ladda upp?#

Indata som sammanlagt överstiger 95 MB går automatiskt via uppladdnings-API:t i delar. En enskild direkt begärandekropp är begränsad till 100 MiB.

Varför kastade mitt anrop ett fel för en PDF utan tabeller?#

Verktyg som pdf-to-csv och pdf-to-xlsx svarar utan innehåll när PDF:en saknar en tabell som går att upptäcka. SDK:n kastar Pdf123Error med koden no_content i stället för att returnera en tom fil. Kontrollera den koden om ett tomt resultat är acceptabelt.