メインコンテンツへスキップ
PPDF123

開発者向けPDF123: REST API、SDK、コマンドライン、MCP

PDF123の開発者向けプラットフォームは、同じ97種類のPDFツールを4つの方法で提供します。OpenAPIで記述されたREST API、TypeScript SDK、pdfxコマンドライン、AIエージェント向けのMCPサーバーです。匿名での呼び出しにアカウントやAPIキーは不要です。

このページの内容

コードからPDF123を使うには、どの方法を選べばよいですか?

4つのインターフェースはすべて同じ操作を呼び出すため、結合の結果はどれを使っても同じです。コードを実行する場所に合わせて選んでください。

インターフェース向いている用途インストールまたはアドレスガイド
REST API任意の言語、サーバー、シェルスクリプトhttps://pdf123.xyz/api/v1APIリファレンス
TypeScript SDK型が必要なNode、Bun、ブラウザのコードnpm install @pdf123/sdkSDKガイド
コマンドラインターミナル、CIジョブ、ローカルファイルの一括処理npm install -g @pdf123/cliCLIガイド
MCPClaude Code、Claude Desktop、CursorなどのAIエージェントnpx -y @pdf123/mcp または https://pdf123.xyz/mcpMCPガイド

コードがTypeScriptでなければREST APIを使います。TypeScriptならSDKを使うと、ツールのオプションに型が付き、アップロード前に検査されます。単発の作業やシェルスクリプトにはコマンドラインが向いています。AIエージェントに実行するツールを判断させたい場合はMCPを使います。

カタログには97個のツールがあります。そのうち58個は、PDFの結合、PDFの分割、PDFの圧縮のように、このサイトにページがあります。残りはWebページのないバックエンド操作で、すべてSDK、コマンドライン、MCPから利用できます。

最初のリクエストはどう実行しますか?

curlで2つのファイルを結合します。リクエストはマルチパートフォームで、ファイルごとに1つの fileInput パートを送ります。

REST: 2つのPDFを結合bash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

TypeScript SDKで同じ結合を行う例です。

SDK: 2つのPDFを結合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")],
});
await saveResult(result, { output: "merged.pdf" });

コマンドラインで同じ結合を行う例です。

CLI: 2つのPDFを結合bash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

認証はどのように行いますか?

公開APIへの匿名の呼び出しには、アカウントもキーも不要です。自分のトラフィックを識別したいとき、またはキーが必須のホスト型MCPエンドポイントを呼び出すときは、X-API-KEY ヘッダーにAPIキーを付けて送ります。

キーを作成するには、下のパネルでサインインします。作成したキーは安全な場所に保管してください。

セッションを確認しています…

キーを付けてAPIを呼び出すbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -H "X-API-KEY: <your-key>" \
  -F [email protected] -F [email protected] -o merged.pdf

SDKではキーを apiKey として渡します。コマンドラインとローカルのMCPサーバーは、環境変数 PDFX_API_KEY から読み取ります。

メモ

セルフホストしたサーバーでは、環境変数 SECURITY_CUSTOMGLOBALAPIKEY を設定すると、サーバーが受け付けるキーを1つ定義できます。詳しくはセルフホストをご覧ください。

APIリファレンスはどこにありますか?

REST APIのドキュメントは2種類あります。Swagger UIでは、ブラウザ上で各エンドポイントを試せます。OpenAPIドキュメントは、クライアント生成ツール向けの機械可読なソースです。

すべての操作は、ベースURL https://pdf123.xyz/api/v1 配下の POST で、カテゴリごとにまとめられています。たとえば結合は /general/merge-pdfs、圧縮は /misc/compress-pdf です。

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

POST /api/v1/pipeline は、fileInput パートと steps フィールドを受け取ります。steps フィールドは、op と任意の params を持つオブジェクトのJSON配列です。各ステップは、前のステップの出力を入力として受け取ります。

結合してから圧縮を1回のリクエストで実行bash
curl -X POST https://pdf123.xyz/api/v1/pipeline \
  -F [email protected] -F [email protected] \
  -F 'steps=[{"op":"general/merge-pdfs"},{"op":"misc/compress-pdf"}]' \
  -o out.pdf

リクエストを安全に再試行するには?

どの操作でも Idempotency-Key ヘッダーを付けて送れます。24時間以内に同じリクエストを繰り返すと、再実行されず、最初の結果がヘッダー Idempotency-Replayed: true 付きで返ります。同じキーを別のリクエストに使うと拒否されます。32 MiBを超える結果は保存されないため、そのようなリクエストを繰り返すと409が返り、新しいキーが必要になります。

サイズとレート制限はどうなっていますか?

制限値
Webサイトでのファイルサイズ1ファイルあたり500 MB
直接のAPIリクエスト本文(1回)100 MiB(マルチパートの枠組みを含む)
チャンクアップロード合計が95 MBを超えると、SDKが自動でアップロードAPIに切り替える

レスポンスには X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset のヘッダーが含まれます。ステータス429のレスポンスには Retry-After も付きます。セルフホストしたサーバーは独自の制限を設定するため、固定のクォータを前提にせず、ヘッダーを読んでください。本文が大きすぎる場合のエラーについては、ブログ記事のリクエストサイズの上限で解説しています。

エラーはどのような形式で返りますか?

失敗時は application/problem+json が返り、フィールドは type、title、status、detail、code、reason、hint です。reason で分岐し、なければ code にフォールバックしてください。detail は人が読むための文章で、ツールの生の出力は含まれません。すべてのコードはエラーコードに一覧があります。

コードまたは reasonHTTPステータス意味
bad_request400パラメーターまたはマルチパート本文が不正
password_required400PDFが暗号化されているが、パスワードが送られていない
invalid_pdf400PDFではない、または破損している。PDFの修復を試してください
page_out_of_range400指定したページが存在しない
not_found404不明な操作パス
rate_limited429クォータを使い切った。Retry-After の時間だけ待つ

まず呼び出せるツールは何ですか?

次の12個のツールで、ほとんどのリクエストをカバーできます。ブラウザで試すには、各ツールのページを使ってください。

ツールページAPIエンドポイントCLIコマンドできること
結合/general/merge-pdfspdfx merge複数のPDFを1つにまとめる
分割/general/split-pagespdfx splitPDFを複数のファイルに分ける
圧縮/misc/compress-pdfpdfx compressPDFのストリームを再圧縮してサイズを減らす
回転/general/rotate-pdfpdfx rotateページの向きを変える
保護/security/add-passwordpdfx protectパスワードでPDFを暗号化する
解除/security/remove-passwordpdfx unlockパスワード保護を取り除く
透かし/security/add-watermarkpdfx watermarkテキストまたは画像の透かしを追加する
OCR/misc/ocr-pdfpdfx ocrスキャンしたPDFを読み取り、Markdownを返す
PDFからMarkdown/convert/pdf/markdownpdfx pdf-to-markdownPDFをMarkdownに変換する
PDFからWord/convert/pdf/wordpdfx convert-to-wordPDFを編集可能なWordファイルに変換する
文書情報/security/get-info-on-pdfpdfx get-infoメタデータ、権限、フォント、構造を報告する
修復/misc/repairpdfx repair破損したPDFの構造を再構築する

エンドポイントは https://pdf123.xyz/api/v1 からの相対パスです。97個すべてのツールを確認するには、pdfx list を実行するか、OpenAPIドキュメントを開いてください。

AIエージェントからPDF123を使うには?

エージェントがツールを使う方法は3つあります。

  • MCPサーバーを接続する。MCPガイドでは、自分のマシン上のファイル向けのローカルサーバー @pdf123/mcp と、https://pdf123.xyz/mcp のホスト型エンドポイントを説明しています。
  • エージェント用スキルを読み込む。エージェント用スキルは、Claude Code、Codex、Cursorなどのツール向けの SKILL.md ファイルで、カタログ用に1つ、各ツール用に1つずつあります。
  • サイトのインデックスを読む。/llms.txt にはツール、API、MCPエンドポイントがプレーンテキストで一覧されており、/site.jsonld はサイトを構造化データとして記述しています。

REST APIとMCPがどう組み合わさるかは、PDF123ブログの記事「Built for AI Agents, Not Just Browsers」で解説しています。

PDF123を自分のサーバーで動かせますか?

はい。バックエンドは pdfx-server というプログラムで、Dockerで動作します。SDK、コマンドライン、MCPサーバーを PDFX_API_BASE でそのサーバーに向ければ、ファイルは自分のネットワーク内にとどまります。構築方法はセルフホスト、サポートの選択肢はエンタープライズをご覧ください。

FAQ

PDF123 APIは無料ですか?

匿名での利用は無料です。公開APIの呼び出しにアカウントやキーは必要ありません。ホスト側のレスポンスにはレート制限のヘッダーが含まれるため、クライアントは429レスポンスを受け取る前に速度を落とせます。

APIキーは必要ですか?

公開サイトを使う場合、REST API、SDK、コマンドラインでは不要です。ホスト型MCPエンドポイント /mcp には必要で、X-API-KEY ヘッダーがないと401が返ります。キーは、このページでサインインすると作成できます。

ファイルサイズの上限は?

Webサイトは1ファイルあたり500 MBまで受け付けます。直接のAPIリクエスト本文は、マルチパートの枠組みを含めて1回あたり最大100 MiBです。合計が95 MBを超えると、SDKはより大きな入力を自動的にチャンクでアップロードします。

APIをセルフホストできますか?

はい。サーバーを自分で動かし、APIベースをそのアドレスに設定します。SDK、コマンドライン、ローカルのMCPサーバーは、いずれもカスタムのベースURLを受け付けます。

エラーを報告するには?

問題レスポンスの code、reason、detail の各フィールドと、リクエストした時刻をコピーして、お問い合わせページから送ってください。サポートから求められない限り、PDFそのものは送らないでください。

SDK、コマンドライン、MCPのどれを使えばよいですか?

TypeScriptのコード内ではSDK、スクリプトやローカルファイルの一括処理にはコマンドライン、AIエージェントがツールを選ぶ場合はMCPを使います。3つとも同じカタログと同じサーバーを使うため、組み合わせて使えます。