NextPDF Connect で画像を埋め込む

概要

NextPDF Connect を介して PDF に画像を埋め込みます。ソースには、サーバーが読み取れるファイルパス、またはインラインの base64 データ URI を指定できます。使用するツールは create_pdf、add_image、output_pdf で、いずれも Core です。画像は画像 XObject として描画され、Do オペレーターによって描かれます（ISO 32000-2 §8.9）。

インストール

composer require nextpdf/server

トランスポートをバインドします。サポートされるラスター形式は PNG、JPEG、GIF です。

概念の概要

add_image は source を受け取り、固定された順序で解決します。

1. データ URI — data: で始まる文字列。NextPDF は MIME タイプと base64 ペイロードを一時ファイルにデコードして埋め込み、その後その一時ファイルを削除します。
2. 生の base64 — 長い base64 文字列はデコードされ、PNG として扱われます。
3. ファイルパス — それ以外はすべて、サーバープロセスが読み取れる必要があるファイルシステムのパスとして扱われます。

画像は x/y の位置に、ユーザー単位（デフォルトはミリメートル）で配置されます。width のみを渡すと、アスペクト比を保つように高さが計算されます。width と height の両方を渡すと、画像は指定した寸法どおりに拡大縮小されます。埋め込まれたオブジェクトは、ページコンテンツに描画される外部オブジェクトです（ISO 32000-2 §8.8）。

API サーフェス

ツール	役割	リスクティア
create_pdf	セッションを開く	Safe
add_image	パスまたはデータ URI から画像を埋め込む	Caution
output_pdf	PDF をレンダリングして返す	Approval Required / Review（base64）

ツールカタログが正式な参照カタログです。利用できるツールは、インストールされているティアによって異なります。

コードサンプル — クイックスタート

1. create_pdf（A4 縦、タイトル）→ document_id。
2. add_image で source を絶対パスに設定し、x、y、width を指定します。
3. add_image で source を data:image/png;base64,... URI に設定し、width と height を明示的に指定します。
4. output_pdf → base64。

コードサンプル — プロダクション

チャートのレンダリングやスクリーンショットなど、ホストがメモリ内で生成した画像にはデータ URI を使用します。すでにサーバー上にあるアセットにはファイルパスを使用します。常に絶対パスを使用してください。相対パスはサーバーの作業ディレクトリを基準に解決されますが、通常はホストの作業ディレクトリとは異なります。続行する前に、add_image のレスポンスで、期待したページに画像があると報告されていることを確認してください。

エッジケースと落とし穴

• パスが見つからない。 存在しないファイルパスは、画像が見つからないというエラーを返します。
• サポートされていない形式。 SVG、BMP、WebP は拒否されます。 先に画像を変換してください。
• 不正な base64 / データ URI。 不正なペイロード、またはカンマ区切りが欠けているデータ URI は、デコードエラーを返します。
• サイズ超過の画像。 ページより大きい画像は、拒否されるのではなく、端でクリップされます。ページから余白を差し引いた範囲に収まるように width/height を計算してください（A4 縦は 210×297 mm です）。

パフォーマンス

出力サイズは画像コンテンツに応じて変化します。小さい画像 2 枚で通常 10〜50 KB です。画像埋め込みのバジェットは、テキストのみの場合より広く設定されています。プロファイルは structural です。

セキュリティに関する注意

ファイルパスモードでは、サーバープロセスの権限でサーバーのファイルシステムから読み取ります。ホストが渡せるパスを制限してください。信頼できない呼び出し元が source でサーバー上の任意のファイルを参照できないようにしてください。base64 モードではバイトをインラインで運ぶため、サーバーパスの露出を回避できます。

適合性

記述	仕様	箇条	reference_id
画像は、Do によって描画される画像 XObject です。	ISO 32000-2	§8.9
画像は、ページコンテンツに描画される外部オブジェクトです。	ISO 32000-2	§8.8

商用コンテキスト

該当なし — すべてのツールは Core です。

トランスポートの利用可否

トランスポート	利用可否	注記
MCP (stdio)	対応	大きな base64 ペイロードは stdio フレームを大きくします。
REST	対応	大きなアセットには、マルチパートまたはサーバーパスを推奨します。
gRPC	対応	Unary。インラインの base64 にはメッセージサイズの上限が適用されます。

HITL リスクティア

create_pdf は Safe、add_image は Caution、output_pdf は Approval Required で、base64 モードでは Review に引き下げられます。パスモードの読み取りはサーバー側で行われ、個別にはゲートされないため、ポリシーレイヤーで制限してください（HITL リスクティア）。

確認ゲートの JSON エンベロープ

ここに base64 出力が入ります。

{ "allowed": true }

関連項目

• Hello world
• HTML テーブル
• ツールカタログ