跳至主要內容
PPDF123

@pdf123/sdk：PDF123 的 TypeScript SDK

@pdf123/sdk 是 PDF123 PDF API 的 TypeScript SDK。它能執行合併、分割、壓縮與 OCR 等 95 個工具，為每個工具的選項提供型別，並加入批次處理、管線、密碼處理與有型別的錯誤。它是不含任何執行期相依套件的 ES 模組。

@pdf123/sdkNode 20.3 或更新版本，或 Bun

安裝

npm install @pdf123/sdk
本頁內容

如何安裝 SDK？

用套件管理工具安裝即可。需要 Node 20.3 或更新版本、Bun 或打包工具。套件已內含 TypeScript 型別，不需要 @types/node。

安裝bash
npm install @pdf123/sdk

bun add @pdf123/sdk 與 pnpm add @pdf123/sdk 的效果相同。

如何合併兩份 PDF？

建立用戶端，對兩個檔案執行 merge 工具，然後儲存結果。不帶任何選項時，用戶端會以匿名身分呼叫公開 API。

合併並儲存ts
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);

結果的 data 是位元組內容，另有 contentType、伺服器給的 filename，以及會回傳報告的工具所使用的 json。網站上的合併 PDF 提供相同的操作。

該匯入哪個進入點？

進入點需求提供內容
@pdf123/sdk只需要 fetchPdf123Client、TOOLS、getTool、Pdf123Error 與目錄輔助函式
@pdf123/sdk/nodeNode 或 BunreadFileInput、fileSource、saveResult、checkOutput 與 clientFromEnv

在瀏覽器與 edge 執行環境中請從根進入點匯入，只有需要讀寫檔案的地方才加上 node 進入點。

用戶端有哪些方法？

方法功能
run(tool, { input, params })執行一個工具並回傳結果
runBatch(tool, inputs, options)對多個輸入執行單檔工具，每個輸入各回傳一筆結果
pipeline(steps, input, options)在一次請求中執行多個工具
call(target, files, fields)對工具 ID、操作 ID 或 /api/... 路徑送出原始請求
upload(file)透過分段上傳 API 上傳一個檔案，並回傳其 ID

目錄輔助函式都是一般函式：TOOLS 列出所有工具，getTool(id) 回傳單一工具的欄位、預設值與可接受的檔案類型，toolGroup、toolSummary、matchesQuery 與 suggestTools 則有助於打造工具選擇器。命令列用 pdfx list 與 pdfx describe 印出同一份目錄。

如何把選項傳給工具？

params 依工具而有不同型別，只接受該工具的欄位，選項類欄位也只接受允許的值。數字欄位會檢查最小值與最大值，檔案會檢查是否為可接受的類型，這些都在上傳之前完成。伺服器需要的預設值會自動補上。

帶選項的浮水印ts
const marked = await client.run("watermark", {
  input: await readFileInput("a.pdf"),
  params: { watermarkText: "DRAFT", fontSize: 40, rotation: -45 },
});
await saveResult(marked, { output: "draft.pdf" });

空字串代表「未設定」，此時會套用預設值。各選項的作用請參閱加入浮水印。

如何處理多個檔案？

runBatch 會用相同的選項，對每個輸入執行單檔工具，例如壓縮、旋轉或加入密碼。預設一次處理兩個檔案。單一檔案出錯，不會讓其他檔案停下來。

可取消的批次處理ts
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) 是延遲讀取的來源，只有在工作執行緒取用時才會讀入，因此許多大型檔案不會同時佔用記憶體。
  • onResult 會在每個結果完成時收到它。請在這裡儲存；這樣在 100 個檔案處理到第 50 個時取消，前 49 個仍會保留。設定 retainData: false 時，回傳的陣列不會保留位元組內容。
  • 任何呼叫都可以帶 timeoutMs 與 signal 來取消。
  • idempotencyKey 會對每個檔案變成 <key>:<index>。

篩選類工具（ID 以 filter- 開頭）在條件不成立時，會以 matched: false 回應，而不是擲出錯誤。在批次中，這樣的檔案仍算 ok。

如何在一次請求中串接工具？

pipeline 會送出一份步驟清單與一個或多個輸入。伺服器會把每個步驟的輸出交給下一個步驟。

合併、加浮水印、壓縮ts
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" });

管線接受與 run 相同的密碼選項。

如何處理加密的 PDF？

對 run 傳入 password，會先開啟加密的輸入。解鎖與工具執行在同一次請求中完成。對於會接收多個檔案的工具，例如合併，請傳入 passwords，每個輸入一個項目，未加密的檔案用空字串。每個檔案會各自解鎖。

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

批次處理時，passwordFor(file, index) 會回傳每個輸入的密碼。若要永久移除保護，請使用移除密碼工具。

錯誤如何處理？

失敗時會擲出 Pdf123Error。它包含 status（沒有收到回應時為 undefined）、code、表示細部原因的 reason（例如 password_required），以及帶有伺服器問題詳情的 problem，其中若有提示會包含 hint。驗證錯誤會在上傳任何內容之前擲出。

處理錯誤ts
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;
  }
}

伺服器代碼列在錯誤代碼。用戶端另外加入以下自己的代碼：

代碼意義
network_error請求沒有收到回應
timeout請求超過了 timeoutMs
cancelled你的 signal 中止了呼叫
input_unreadable無法讀取本機路徑
output_unwritable無法把結果儲存到指定的路徑
output_mismatchsaveResult 拒絕把 ZIP 寫成 .pdf 檔名
unsupported_file_type工具不接受該檔案類型
unknown_tool工具 ID 不存在；訊息會建議相近的 ID
invalid_targetcall 拒絕含有 ..、. 或空片段的 /api/... 路徑
no_content工具沒有可回傳的內容（HTTP 204）

saveResult 絕不會覆寫目錄中的既有檔案。請先呼叫 checkOutput(output, { several })，在上傳之前確認路徑是否可寫入。

哪些 TypeScript 與模組設定可以使用？

型別可在 moduleResolution 設定為 nodenext、node16、bundler 以及較舊的 node10 時解析，包括 @pdf123/sdk/node 子路徑。套件是 ES 模組，因此 import 在任何地方都能用。從 CommonJS 以 require("@pdf123/sdk") 載入，在 Node 22.12 或更新版本可行，Node 20 上則無法使用。

如何設定用戶端？

選項環境變數預設值
baseUrlPDFX_API_BASEhttps://pdf123.xyz
apiKeyPDFX_API_KEY無，匿名
timeoutMs無300000

new Pdf123Client() 絕不會讀取環境變數。@pdf123/sdk/node 的 clientFromEnv() 會讀取這兩個變數，而你傳入的選項優先。金鑰會以 X-API-KEY 標頭送出；請參閱驗證。

若要使用自己的伺服器，請把 baseUrl 設為它的位址，例如 http://localhost:8080。請參閱自架。

可以在瀏覽器中使用 SDK 嗎？

可以。根進入點 @pdf123/sdk 只需要 fetch，沒有 Node 相依。請自行從 File 或 Uint8Array 建立 FileInput 物件，因為檔案輔助函式在 node 進入點中。請不要把 API 金鑰放進其他人看得到的瀏覽器程式碼。

常見問題

SDK 需要 API 金鑰嗎？

不需要。不帶任何選項建立的用戶端，會以匿名身分呼叫公開 API。傳入 apiKey 即可送出 X-API-KEY 標頭。

SDK 需要哪個版本的 Node？

Node 20.3 或更新版本，或 Bun。根進入點只需要 fetch，因此也能在瀏覽器與打包工具中執行。

如何使用比 SDK 更新的工具？

使用 client.call。它接收工具 ID、操作 ID（例如 general/merge-pdfs）或 /api/... 路徑，再加上檔案與欄位。本機不會做任何驗證，也不會補預設值。

可以上傳多大的檔案？

總大小超過 95 MB 的輸入會自動走分段上傳 API。單一直接請求的內容上限是 100 MiB。

為什麼對沒有表格的 PDF 呼叫會擲出錯誤？

pdf-to-csv 與 pdf-to-xlsx 等工具在 PDF 偵測不到表格時，會回應沒有內容。SDK 會擲出代碼為 no_content 的 Pdf123Error，而不是回傳空檔案。如果可以接受空結果，請檢查這個代碼。