Embed images over NextPDF Connect

At a glance

Embed an image in a Portable Document Format (PDF) file over NextPDF Connect. Use either a server-readable file path or an inline base64 data URI as the source. You use create_pdf, add_image, and output_pdf — all Core tools. NextPDF draws the image as an image XObject, painted by the Do operator (ISO 32000-2 §8.9).

Install

composer require nextpdf/server

Bind a transport. NextPDF supports PNG, JPEG, and GIF raster formats.

Conceptual overview

add_image takes a source and resolves it in this fixed order:

Data URI — a string that starts with data:. NextPDF decodes the Multipurpose Internet Mail Extensions (MIME) type and base64 payload to a temporary file, embeds it, then removes the temporary file.
Raw base64 — NextPDF decodes a long base64 string and treats it as PNG.
File path — NextPDF treats anything else as a filesystem path that the server process must be able to read.

The image appears at x/y, in user units (millimetres by default). Pass only width, and NextPDF computes the height to preserve the aspect ratio. Pass both width and height, and NextPDF scales the image to those exact dimensions. The embedded object is an external object painted into the page content (ISO 32000-2 §8.8).

API surface

Tool	Role	Risk tier
`create_pdf`	Open the session	Safe
`add_image`	Embed an image from path or data URI	Caution
`output_pdf`	Render and return the PDF	Approval Required / Review (base64)

The tool catalog is the catalog of record. Your available tools depend on the installed tier.

Code sample — Quick start

create_pdf (A4 portrait, title) → document_id.
add_image with source set to an absolute path, x, y, width.
add_image with source set to a data:image/png;base64,... URI and explicit width and height.
output_pdf → base64.

Code sample — Production

Use a data URI for an image the host generated in memory, such as a chart render or screenshot. Use a file path for an asset that already exists on the server. Always use absolute paths. A relative path resolves against the server’s working directory, which is usually not the host’s. Before you continue, confirm that the add_image response reports the image on the expected page.

Edge cases & gotchas

Path not found. A missing file path returns an image-not-found error.
Unsupported format. NextPDF rejects SVG, BMP, and WebP. Convert the image first.
Malformed base64 / data URI. A bad payload, or a data URI that is missing the comma separator, returns a decode error.
Oversized image. An image larger than the page is clipped at the edge, not rejected. Compute width/height against the page minus its margins (A4 portrait is 210×297 mm).

Performance

Output size scales with image content. Two small images are typically 10–50 KB. The image-embed budget is wider than the text-only budget. This page uses the structural profile.

Security notes

File-path mode reads from the server’s filesystem with the server process’s privileges. Constrain which paths the host may pass. Do not let untrusted callers point source at arbitrary server files. Base64 mode carries the bytes inline, so it avoids server-path exposure.

Conformance

Statement	Spec	Clause	reference_id
An image is an image XObject painted by `Do`.	ISO 32000-2	§8.9
Images are external objects painted into page content.	ISO 32000-2	§8.8

Commercial context

Not applicable — all tools are included in Core.

Transport availability

Transport	Available	Notes
MCP (stdio)	Yes	Large base64 payloads inflate the stdio frame.
REST	Yes	Prefer multipart or a server path for large assets.
gRPC	Yes	Unary; message-size limits apply to inline base64.

HITL risk tier

create_pdf is Safe, add_image is Caution, and output_pdf is Approval Required — downgraded to Review in base64 mode. The path-mode read is server-side and is not separately gated, so constrain it at the policy layer (HITL risk tiers).

Confirmation gate JSON envelope

Base64 output here:

{ "allowed": true }