Menyematkan gambar dengan NextPDF Connect

Sekilas pandang

Sematkan gambar ke dalam berkas Portable Document Format (PDF) dengan NextPDF Connect. Gunakan path berkas yang dapat dibaca oleh server atau data URI base64 inline sebagai sumbernya. Alurnya menggunakan create_pdf, add_image, dan output_pdf — semuanya merupakan perkakas Core. NextPDF merender gambar tersebut sebagai image XObject yang dilukis oleh operator Do (ISO 32000-2 §8.9).

Pemasangan

composer require nextpdf/server

Ikat sebuah transport. NextPDF mendukung format raster PNG, JPEG, dan GIF.

Gambaran konseptual

add_image menerima source dan memprosesnya menurut urutan tetap berikut:

Data URI — string yang diawali dengan data:. NextPDF mendekode tipe Multipurpose Internet Mail Extensions (MIME) dan muatan base64 ke berkas sementara, menyematkannya, lalu menghapus berkas sementara tersebut.
base64 mentah — NextPDF mendekode string base64 yang panjang dan memperlakukannya sebagai PNG.
Path berkas — NextPDF memperlakukan input lainnya sebagai path pada sistem berkas yang harus dapat dibaca oleh proses server.

Gambar muncul pada x/y, dalam satuan pengguna (milimeter secara baku). Berikan width saja, dan NextPDF menghitung tinggi untuk mempertahankan rasio aspek. Berikan width dan height, dan NextPDF menskalakan gambar ke dimensi persis tersebut. Objek yang disematkan merupakan objek eksternal yang dilukis ke dalam konten halaman (ISO 32000-2 §8.8).

Permukaan API

Perkakas	Peran	Tingkat risiko
`create_pdf`	Membuka sesi	Aman
`add_image`	Menyematkan gambar dari path atau data URI	Perhatian
`output_pdf`	Merender dan mengembalikan PDF	Persetujuan Diperlukan / Tinjauan (base64)

Katalog perkakas adalah katalog rujukan resmi. Perkakas yang tersedia bagi Anda bergantung pada tier yang terpasang.

Contoh kode — Mulai cepat

create_pdf (A4 portrait, judul) → document_id.
add_image dengan source diatur ke path absolut, x, y, width.
add_image dengan source diatur ke URI data:image/png;base64,... serta width dan height yang eksplisit.
output_pdf → base64.

Contoh kode — Produksi

Gunakan data URI untuk gambar yang dihasilkan host di dalam memori, seperti hasil render bagan atau tangkapan layar. Gunakan path berkas untuk aset yang sudah ada di server. Selalu gunakan path absolut. Path relatif diselesaikan terhadap direktori kerja server, yang biasanya bukan direktori milik host. Sebelum melanjutkan, pastikan bahwa respons add_image melaporkan gambar pada halaman yang diharapkan.

Kasus tepi & jebakan

Path tidak ditemukan. Path berkas yang hilang mengembalikan galat gambar tidak ditemukan.
Format tidak didukung. NextPDF menolak SVG, BMP, dan WebP. Konversikan gambar terlebih dahulu.
base64 / data URI yang cacat. Muatan yang tidak valid, atau data URI yang tidak memiliki pemisah koma, mengembalikan galat dekode.
Gambar berukuran terlalu besar. Gambar yang lebih besar daripada halaman dipotong pada tepinya, bukan ditolak. Hitung width/height berdasarkan ukuran halaman setelah dikurangi margin (A4 portrait berukuran 210×297 mm).

Performa

Ukuran keluaran bergantung pada konten gambar. Dua gambar kecil umumnya berukuran 10–50 KB. Anggaran untuk penyematan gambar lebih longgar daripada anggaran untuk teks saja. Halaman ini menggunakan profil structural.

Catatan keamanan

Mode path berkas membaca dari sistem berkas server dengan hak istimewa proses server. Batasi path yang boleh diberikan oleh host. Jangan biarkan pemanggil yang tidak tepercaya mengarahkan source ke sembarang berkas server. Mode base64 membawa byte secara inline, sehingga menghindari paparan path server.

Kesesuaian

Pernyataan	Spesifikasi	Klausa	reference_id
Gambar adalah image XObject yang dilukis oleh `Do`.	ISO 32000-2	§8.9
Gambar merupakan objek eksternal yang dilukis ke dalam konten halaman.	ISO 32000-2	§8.8

Konteks komersial

Tidak berlaku — semua perkakas sudah termasuk dalam Core.

Ketersediaan transport

Transport	Tersedia	Catatan
MCP (stdio)	Ya	Muatan base64 yang besar memperbesar bingkai stdio.
REST	Ya	Multipart atau path server lebih disarankan untuk aset berukuran besar.
gRPC	Ya	Unary; batas ukuran pesan berlaku untuk base64 sebaris.

Tingkat risiko HITL

create_pdf bersifat Aman, add_image bersifat Perhatian, dan output_pdf bersifat Persetujuan Diperlukan — diturunkan menjadi Tinjauan dalam mode base64. Pembacaan dalam mode path terjadi di sisi server dan tidak memiliki gerbang terpisah, jadi batasi pada lapisan kebijakan (tingkat risiko HITL).

Amplop JSON untuk gerbang konfirmasi

Keluaran base64 di sini:

{ "allowed": true }