無料の Web コンバータではなく、PDF ツールキットをセルフホストする理由

ブラウザだけで動く PDF コンバータは、アップロード、クリック、ダウンロードに最適化されている。ページは広告で支えられていることが多く、フォーム以外に安定した開発者向けの面は通常ない。この形は人間が一度だけ行う作業には正しい。自動化、保持ポリシー、あるいはファイルを自ネットワーク内に留めたい場合には、誤った形になる。

ブラウザコンバータが最適化しているもの

公開コンバータが売っているのは利便性だ。タブを開き、ファイルを落とし、結果を得て、去る。UI そのものが製品である。スクリプトは HTML をスクレイピングするか、予告なく変わる未文書化のエンドポイントを叩くしかない。一時ファイルの保持は運営者任せだ。個人の PDF を二つ結合するだけなら、この取引で十分だ。

しかし CI、エージェント、エアギャップネットワークから同じ作業を回す必要が出た瞬間、欠けていたものが一斉に現れる。認証、OpenAPI、冪等な再試行、そして先週クリックしたフォームから静かに乖離しない操作カタログである。

このカタログを自分で動かすと得られるもの

ホスト版とセルフホスト版は同じ操作を共有する。PDF の圧縮 も PDF の結合 も、ポータルから来たリクエストでも POST /api/v1/… から来たリクエストでも同じ op だ。セルフホストは、その共有カタログの周囲に制御を足す。

• REST + OpenAPI（/v1/openapi.json）：カタログの各ツールが安定したエンドポイントになる。フォームだけではない。
• MCP（/mcp）：エージェントがスクレイパーを自作せずに、同じ操作を発見して呼び出せる。
• CLI（pdfx）：ローカルの pdf-core、または base URL 上の API Key に対して --cloud。
• デスクトップクライアントなし：オフラインの解は Docker Compose だ。プラグインと Windows インストーラーは意図的に範囲外としている。
• 広告が自スタックに入らない：公開サイトの AdSense はセルフホストのデプロイには含まれない。アップロードは自分が動かすマシンから出ない。

Compose は Rust の pdfx-server と Next.js ポータルを一緒に起動し、人間とスクリプトが一つのカタログを共有する。ネイティブ開発（task pdfx:dev とポータル）も同じ op の経路を通る。詳細は セルフホスト にある。

どちらのデプロイでも、OCR は /api/v1/misc/ocr-pdf から Markdown（text/markdown）を返す。テキスト層を重ね直した検索可能 PDF ではない。サーバーを移すと変わるのはバイトの着地点であり、op の契約が別物になるわけではない。

意図的に真似しないもの

オンラインの「PDF 編集」キャンバス、視覚的な比較、白紙からの「PDF 作成」、コンシューマ向けの署名 UI には、別の製品としての作業が必要だ。こちらはフォームベースのツール群と API を維持する。セルフホストは第二の UI ツリーを開放するのではなく、同じツリーを自分のファイアウォールの内側に移すだけだ。

こうしたコンシューマ向けの面を省くのは意図的である。キャンバスエディタは第二のコードベースになり、OpenAPI に対して恒常的に遅れる。プライベート利用で本当に重要な制約は「バイトがここに留まる」ことで、「.exe がある」ことではない。デスクトップ版を作らない理由は デスクトップアプリを作らない理由 にある。

ホスト版で足りるとき、足りないとき

ゼロ設定で匿名の単発作業をしたいなら公開サイトを使う。カタログツールと匿名の /api/v1/ 呼び出しにアカウントは不要だ。ホスト側の応答はレート制限ヘッダーを告知し、上限があるのは無料の面が他人のバッチ農場にならないためだ（匿名レート制限）。

保持ルール、プライベートネットワーク、プライベートな自動化が必要ならセルフホストする。その場合、稼働率、イメージ更新、一時ファイル用のディスク、TLS、キーローテーション（固定ゲートには SECURITY_CUSTOMGLOBALAPIKEY）は自分のものになる。操作は同じままで、変わるのはバイトの着地点だけだ。

試す

セルフホスト と 開発者向け から始める。どちらの base URL でもエージェント向けの API 面については ブラウザだけでなく AI エージェントのために作る を読むとよい。コストと便益のより長い整理は セルフホストが実際にもたらすもの にある。