Bilder mit NextPDF Connect einbetten

Auf einen Blick

Betten Sie mit NextPDF Connect ein Bild in ein PDF ein. Als Quelle dient entweder ein vom Server lesbarer Dateipfad oder ein eingebetteter Base64-Daten-URI. Die beteiligten Tools sind create_pdf, add_image und output_pdf — alle gehören zu Core. Ein Bild wird als Bild-XObject gezeichnet und mit dem Operator Do gemalt (ISO 32000-2 §8.9).

Installation

composer require nextpdf/server

Binden Sie einen Transport an. Unterstützte Rasterformate sind PNG, JPEG und GIF.

Konzeptioneller Überblick

add_image nimmt eine source entgegen und löst sie in festgelegter Reihenfolge auf:

Daten-URI — eine Zeichenkette, die mit data: beginnt. NextPDF dekodiert den MIME-Typ und die Base64-Nutzlast in eine temporäre Datei, bettet sie ein und entfernt anschließend die temporäre Datei.
Rohes Base64 — eine lange Base64-Zeichenkette wird dekodiert und als PNG behandelt.
Dateipfad — alles andere wird als Dateisystempfad behandelt, den der Serverprozess lesen können muss.

Das Bild wird an der Position x/y in Benutzereinheiten platziert (standardmäßig Millimeter). Wenn Sie nur width übergeben, wird die Höhe so berechnet, dass das Seitenverhältnis erhalten bleibt. Wenn Sie sowohl width als auch height übergeben, wird das Bild exakt auf diese Abmessungen skaliert. Das eingebettete Objekt ist ein externes Objekt, das in den Seiteninhalt gemalt wird (ISO 32000-2 §8.8).

API-Fläche

Werkzeug	Rolle	Risikostufe
`create_pdf`	Sitzung öffnen	Sicher
`add_image`	Ein Bild aus einem Pfad oder einem Daten-URI einbetten	Vorsicht
`output_pdf`	Das PDF rendern und zurückgeben	Genehmigung erforderlich / Prüfung (Base64)

Der Werkzeugkatalog ist maßgeblich. Welche Tools Ihnen zur Verfügung stehen, hängt von der installierten Stufe ab.

Codebeispiel – Schnellstart

create_pdf (A4 Hochformat, Titel) → document_id.
add_image mit source, das auf einen absoluten Pfad gesetzt ist, sowie x, y, width.
add_image mit source, das auf einen data:image/png;base64,...-URI gesetzt ist, sowie expliziten width- und height-Werten.
output_pdf → Base64.

Codebeispiel – Produktion

Verwenden Sie einen Daten-URI für ein Bild, das der Host im Speicher erzeugt hat, etwa ein gerendertes Diagramm oder einen Screenshot. Verwenden Sie einen Dateipfad für ein Asset, das bereits auf dem Server liegt. Verwenden Sie immer absolute Pfade. Ein relativer Pfad wird relativ zum Arbeitsverzeichnis des Servers aufgelöst, das in der Regel nicht dem des Hosts entspricht. Prüfen Sie vor dem Fortfahren, dass die add_image-Antwort das Bild auf der erwarteten Seite meldet.

Grenzfälle & Stolperfallen

Pfad nicht gefunden. Ein fehlender Dateipfad führt zu einem Bild-nicht-gefunden-Fehler.
Nicht unterstütztes Format. SVG, BMP und WebP werden abgelehnt. Konvertieren Sie das Bild zuerst.
Fehlerhaftes Base64 / Daten-URI. Eine fehlerhafte Nutzlast oder ein Daten-URI, dem das Kommatrennzeichen fehlt, führt zu einem Dekodierungsfehler.
Übergroßes Bild. Ein Bild, das größer als die Seite ist, wird an den Rändern beschnitten, nicht abgelehnt. Berechnen Sie width/height anhand der Seite abzüglich ihrer Ränder (A4-Hochformat ist 210×297 mm).

Performance

Die Ausgabegröße skaliert mit dem Bildinhalt. Zwei kleine Bilder sind typischerweise 10–50 KB groß. Das Budget für die Bildeinbettung ist großzügiger bemessen als das reine Textbudget. Das Profil ist structural.

Sicherheitshinweise

Der Dateipfadmodus liest mit den Berechtigungen des Serverprozesses aus dem Dateisystem des Servers. Schränken Sie ein, welche Pfade der Host übergeben darf. Lassen Sie nicht zu, dass nicht vertrauenswürdige Aufrufer source auf beliebige Serverdateien richten. Der Base64-Modus übergibt die Bytes eingebettet und vermeidet dadurch eine Offenlegung von Serverpfaden.

Konformität

Aussage	Spezifikation	Klausel	reference_id
Ein Bild ist ein Bild-XObject, das mit `Do` gemalt wird.	ISO 32000-2	§8.9
Bilder sind externe Objekte, die in den Seiteninhalt gemalt werden.	ISO 32000-2	§8.8

Kommerzieller Kontext

Nicht anwendbar — alle Tools sind Teil von Core.

Transportverfügbarkeit

Transport	Verfügbar	Hinweise
MCP (stdio)	Ja	Große Base64-Nutzlasten vergrößern den stdio-Frame.
REST	Ja	Bevorzugen Sie für große Assets Multipart oder einen Serverpfad.
gRPC	Ja	Unär; Nachrichtengrößenbeschränkungen gelten für eingebettetes Base64.

HITL-Risikostufe

create_pdf hat die Stufe Sicher, add_image die Stufe Vorsicht und output_pdf die Stufe Genehmigung erforderlich — im Base64-Modus auf Prüfung herabgestuft. Der Lesevorgang im Pfadmodus erfolgt serverseitig und ist nicht separat gesperrt; beschränken Sie ihn daher auf Richtlinienebene (HITL-Risikostufen).

JSON-Umschlag des Bestätigungstors

Base64-Ausgabe in diesem Fall:

{ "allowed": true }