@pdf123/sdk：PDF123 的 TypeScript SDK

如何安装 SDK？#

使用包管理器安装即可。需要 Node 20.3 或更高版本、Bun 或打包工具。包内已包含 TypeScript 类型，不需要 @types/node。

npm install @pdf123/sdk

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

如何合并两个 PDF？#

创建客户端，对两个文件运行 merge 工具，然后保存结果。不传任何选项时，客户端以匿名方式访问公共 API。

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。

应该导入哪个入口？#

在浏览器和边缘运行时中请从根入口导入，只在需要读写文件的地方再引入 node 入口。

客户端有哪些方法？#

目录辅助函数都是普通函数：TOOLS 列出全部工具，getTool(id) 返回单个工具的字段、默认值和接受的文件类型，toolGroup、toolSummary、matchesQuery 和 suggestTools 可用来构建工具选择器。命令行通过 pdfx list 和 pdfx describe 输出同一份目录。

如何向工具传递选项？#

params 按工具提供类型。它只接受该工具自己的字段，选择类字段只接受允许的取值。在上传任何内容之前，SDK 会按最小值和最大值检查数字字段，并按接受的类型检查文件。服务器需要的默认值会自动补全。

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

空字符串表示“未设置”，此时使用默认值。各选项的作用见PDF 水印。

如何处理大量文件？#

runBatch 会用相同的选项对每个输入运行单文件工具，例如压缩、旋转或加密保护。默认同时处理两个文件。一个文件出错不会影响其他文件。

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 发送一组步骤和一个或多个输入。服务器会把每一步的输出作为下一步的输入。

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，每个输入对应一项，未加密的文件用空字符串。每个文件会分别解锁。

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。校验错误会在上传任何内容之前抛出。

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

服务器错误码列在错误码页面。客户端自身还会添加以下错误码：

saveResult 不会覆盖目录中已有的文件。请先调用 checkOutput(output, { several })，在上传之前确认某个路径能否写入。

支持哪些 TypeScript 和模块设置？#

在 moduleResolution 设置为 nodenext、node16、bundler 以及较旧的 node10 时，类型都能正确解析，包括 @pdf123/sdk/node 子路径。该包是 ES 模块，因此 import 在各处都可用。在 CommonJS 中使用 require("@pdf123/sdk") 需要 Node 22.12 或更高版本，Node 20 不支持。

如何配置客户端？#

new Pdf123Client() 从不读取环境变量。@pdf123/sdk/node 中的 clientFromEnv() 会读取这两个变量，你传入的选项优先。密钥以 X-API-KEY 请求头发送；参见身份验证。

若要使用自己的服务器，请把 baseUrl 设置为其地址，例如 http://localhost:8080。参见自托管。

可以在浏览器中使用 SDK 吗？#

可以。根入口 @pdf123/sdk 只需要 fetch，没有 Node 依赖。请自行用 File 或 Uint8Array 构建 FileInput 对象，因为文件辅助函数位于 node 入口中。不要把 API 密钥放进其他人能读取的浏览器代码里。

相关页面#

• 开发者概览，包含 REST API 和身份验证
• pdfx 命令行，基于本 SDK 构建
• 面向 AI 智能体的 MCP 服务器
• Swagger UI 和 OpenAPI 文档
• 工具页面：合并、拆分、压缩、OCR、加密保护

常见问题#

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，而不是返回空文件。如果可以接受空结果，请检查这个错误码。