メインコンテンツへスキップ
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 でも同様にインストールできます。

2つのPDFを結合するには？

クライアントを作成し、2つのファイルに対して 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 も使えます。同じ操作は、WebサイトではPDFの結合として利用できます。

どのエントリポイントをインポートすればよいですか？

エントリポイント必要なもの提供するもの
@pdf123/sdkfetch のみPdf123Client、TOOLS、getTool、Pdf123Error、カタログ用ヘルパー
@pdf123/sdk/nodeNodeまたはBunreadFileInput、fileSource、saveResult、checkOutput、clientFromEnv

ブラウザやエッジランタイムではルートのエントリポイントからインポートし、ファイルの読み書きが必要な場所だけに node エントリポイントを追加してください。

クライアントにはどのメソッドがありますか？

メソッド機能
run(tool, { input, params })1つのツールを実行し、結果で解決する
runBatch(tool, inputs, options)単一ファイル用のツールを多数の入力に実行し、入力ごとに1件のエントリで解決する
pipeline(steps, input, options)複数のツールを1回のリクエストで実行する
call(target, files, fields)ツールID、操作ID、/api/... パスのいずれかに生のリクエストを送る
upload(file)チャンクアップロードAPIで1つのファイルをアップロードし、そのIDを返す

カタログ用のヘルパーは通常の関数です。TOOLS は全ツールを一覧し、getTool(id) は1つのツールのフィールド、既定値、受け付けるファイル形式を返します。toolGroup、toolSummary、matchesQuery、suggestTools はツール選択UIの構築に役立ちます。コマンドラインでも、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 は、圧縮、回転、保護のような単一ファイル用のツールを、同じオプションで各入力に対して実行します。既定では2ファイルずつ並行して実行します。1つのファイルが失敗しても、ほかのファイルは止まりません。

キャンセル付きのバッチ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 として数えられます。

1回のリクエストで複数のツールをつなぐには？

pipeline は、ステップの一覧と1つ以上の入力を送ります。サーバーは、各ステップの出力を次のステップに渡します。

結合、透かし、圧縮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 を渡すと、暗号化された入力を先に開きます。ロック解除とツールの実行は、1回のリクエストで行われます。結合のように複数のファイルを受け取るツールでは、入力ごとに1つの要素を持つ 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、password_required のような詳細な原因を示す reason、サーバーの問題の詳細である 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 を超えた
cancelledsignal によって呼び出しが中止された
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() は2つの環境変数を読み取り、渡したオプションが優先されます。キーは X-API-KEY ヘッダーとして送られます。詳しくは認証をご覧ください。

自分のサーバーを使うには、baseUrl をそのアドレス（たとえば http://localhost:8080）に設定します。セルフホストもあわせてご覧ください。

SDKはブラウザで使えますか？

はい。ルートのエントリポイント @pdf123/sdk は fetch だけを必要とし、Nodeへの依存はありません。ファイル用のヘルパーは node エントリポイントにあるため、FileInput オブジェクトは File または Uint8Array から自分で作成してください。ほかの人が読めるブラウザのコードにAPIキーを含めないでください。

FAQ

SDKにAPIキーは必要ですか？

いいえ。オプションなしで作成したクライアントは、公開APIに匿名でアクセスします。X-API-KEY ヘッダーを送るには apiKey を渡します。

SDKにはどのバージョンのNodeが必要ですか？

Node 20.3以降、またはBunです。ルートのエントリポイントは fetch だけを必要とするため、ブラウザやバンドラーでも動作します。

SDKより新しいツールを使うには？

client.call を使います。ツールID、general/merge-pdfs のような操作ID、または /api/... パスと、ファイルおよびフィールドを受け取ります。ローカルでの検証や既定値の補完は行われません。

アップロードできるファイルの大きさは？

合計が95 MBを超える入力は、自動的にチャンクアップロードAPIを経由します。直接のリクエスト本文1回の上限は100 MiBです。

表のないPDFで呼び出しが例外になったのはなぜですか？

pdf-to-csv や pdf-to-xlsx などのツールは、PDFから表を検出できないと、内容なしで応答します。SDKは空のファイルを返す代わりに、コード no_content の Pdf123Error を投げます。空の結果を許容できる場合は、このコードを確認してください。