コードからPDF123を使うには、どの方法を選べばよいですか?
4つのインターフェースはすべて同じ操作を呼び出すため、結合の結果はどれを使っても同じです。コードを実行する場所に合わせて選んでください。
| インターフェース | 向いている用途 | インストールまたはアドレス | ガイド |
|---|---|---|---|
| REST API | 任意の言語、サーバー、シェルスクリプト | https://pdf123.xyz/api/v1 | APIリファレンス |
| TypeScript SDK | 型が必要なNode、Bun、ブラウザのコード | npm install @pdf123/sdk | SDKガイド |
| コマンドライン | ターミナル、CIジョブ、ローカルファイルの一括処理 | npm install -g @pdf123/cli | CLIガイド |
| MCP | Claude Code、Claude Desktop、CursorなどのAIエージェント | npx -y @pdf123/mcp または https://pdf123.xyz/mcp | MCPガイド |
コードがTypeScriptでなければREST APIを使います。TypeScriptならSDKを使うと、ツールのオプションに型が付き、アップロード前に検査されます。単発の作業やシェルスクリプトにはコマンドラインが向いています。AIエージェントに実行するツールを判断させたい場合はMCPを使います。
カタログには97個のツールがあります。そのうち58個は、PDFの結合、PDFの分割、PDFの圧縮のように、このサイトにページがあります。残りはWebページのないバックエンド操作で、すべてSDK、コマンドライン、MCPから利用できます。
最初のリクエストはどう実行しますか?
curlで2つのファイルを結合します。リクエストはマルチパートフォームで、ファイルごとに1つの fileInput パートを送ります。
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfTypeScript SDKで同じ結合を行う例です。
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" });コマンドラインで同じ結合を行う例です。
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf認証はどのように行いますか?
公開APIへの匿名の呼び出しには、アカウントもキーも不要です。自分のトラフィックを識別したいとき、またはキーが必須のホスト型MCPエンドポイントを呼び出すときは、X-API-KEY ヘッダーにAPIキーを付けて送ります。
キーを作成するには、下のパネルでサインインします。作成したキーは安全な場所に保管してください。
セッションを確認しています…
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.pdfSDKではキーを 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配列です。各ステップは、前のステップの出力を入力として受け取ります。
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 は人が読むための文章で、ツールの生の出力は含まれません。すべてのコードはエラーコードに一覧があります。
| コードまたは reason | HTTPステータス | 意味 |
|---|---|---|
bad_request | 400 | パラメーターまたはマルチパート本文が不正 |
password_required | 400 | PDFが暗号化されているが、パスワードが送られていない |
invalid_pdf | 400 | PDFではない、または破損している。PDFの修復を試してください |
page_out_of_range | 400 | 指定したページが存在しない |
not_found | 404 | 不明な操作パス |
rate_limited | 429 | クォータを使い切った。Retry-After の時間だけ待つ |
まず呼び出せるツールは何ですか?
次の12個のツールで、ほとんどのリクエストをカバーできます。ブラウザで試すには、各ツールのページを使ってください。
| ツールページ | APIエンドポイント | CLIコマンド | できること |
|---|---|---|---|
| 結合 | /general/merge-pdfs | pdfx merge | 複数のPDFを1つにまとめる |
| 分割 | /general/split-pages | pdfx split | PDFを複数のファイルに分ける |
| 圧縮 | /misc/compress-pdf | pdfx compress | PDFのストリームを再圧縮してサイズを減らす |
| 回転 | /general/rotate-pdf | pdfx rotate | ページの向きを変える |
| 保護 | /security/add-password | pdfx protect | パスワードでPDFを暗号化する |
| 解除 | /security/remove-password | pdfx unlock | パスワード保護を取り除く |
| 透かし | /security/add-watermark | pdfx watermark | テキストまたは画像の透かしを追加する |
| OCR | /misc/ocr-pdf | pdfx ocr | スキャンしたPDFを読み取り、Markdownを返す |
| PDFからMarkdown | /convert/pdf/markdown | pdfx pdf-to-markdown | PDFをMarkdownに変換する |
| PDFからWord | /convert/pdf/word | pdfx convert-to-word | PDFを編集可能なWordファイルに変換する |
| 文書情報 | /security/get-info-on-pdf | pdfx get-info | メタデータ、権限、フォント、構造を報告する |
| 修復 | /misc/repair | pdfx 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つとも同じカタログと同じサーバーを使うため、組み合わせて使えます。