Images, QR & barcode
Embed JPEG/PNG/SVG, generate QR codes and barcodes, and pick the right size and format for sharp, small PDFs.
Images, QR & barcode
Two ways to get pixels onto a page:
- Embed an existing image —
imagenode with a URL or base64. - Generate a code —
qrorbarcodenode, no image needed.
Embedding an image
{ "image": "https://cdn.example.com/logo.png", "width": "30mm" }
Or with a data URL:
{ "image": "data:image/png;base64,iVBORw0KGgo...", "width": "30mm" }
| Field | Type | Notes |
|---|---|---|
image |
string | URL (https://, http://) or data:image/...;base64,.... |
width |
string | Output width in pt/mm/cm/in. |
height |
string | Output height. If only one of width/height is set, the other is derived from aspect ratio. |
align |
string | left, center, right. |
fit |
string | contain (default), cover, fill. |
Allowed formats
| Format | Notes |
|---|---|
| JPEG | Used as-is. We don't re-encode. Smallest output for photos. |
| PNG | Used as-is, including alpha channel. Best for logos and screenshots. |
| SVG | Rasterised at the output size, then embedded as PNG. The render is exact for the output size you set. |
| GIF | First frame only. Animation is dropped. |
| WebP | Decoded server-side and re-encoded as PNG. Slightly slower than JPEG/PNG. |
Sourcing images by URL
When image is an HTTP(S) URL, the engine fetches it server-side. That means:
- The URL must be reachable from
us-central1(Cloud Run egress). - Redirects are followed up to 5 times.
- Total per-image fetch budget is 4 seconds. Slow CDNs will time out and the render fails with
template_error. - Responses larger than 8 MB per image are rejected.
- The fetcher sends
User-Agent: gpdf-api/<version>and respects standard caching headers.
For repeated logos and signatures, prefer base64 — it's faster (no network hop) and more reliable than relying on a CDN being up.
Picking the right resolution
PDFs are vector containers, but raster images embed at the resolution you give them. Rule of thumb for invoices:
- 96 DPI is fine for screen-only PDFs.
- 150 DPI is the sweet spot for most printed documents.
- 300 DPI for photo-quality print (cover pages, marketing materials).
A 30mm wide logo at 300 DPI is 30 * 300 / 25.4 ≈ 354px. Anything sharper than that wastes file size.
QR codes
{ "qr": "https://gpdf.dev", "size": "20mm" }
Renders a QR code with sane defaults (error correction M, dark #000, light #FFF).
| Field | Type | Notes |
|---|---|---|
qr |
string | Payload — URL, vCard, anything Unicode. |
size |
string | Square side length. Defaults to 15mm. |
errorCorrection |
string | L, M, Q, H. Default M. |
darkColor |
hex | Default #000. |
lightColor |
hex | Default #FFF. |
quietZone |
integer | Modules of margin. Default 4. |
align |
string | left, center, right. |
QR generation is fully in-process; there's no external service hop.
Barcodes (linear)
{ "barcode": { "value": "012345678905", "format": "ean13" }, "width": "60mm", "height": "16mm" }
| Format | Notes |
|---|---|
ean13 |
12-digit input + check digit (or 13 digits — we'll validate). |
ean8 |
7-digit + check digit. |
upca |
UPC-A. |
code128 |
Variable length, alphanumeric. The most common general-purpose barcode. |
code39 |
Older, common in industrial labels. |
itf14 |
13-digit + check, used for shipping cartons. |
The engine renders barcodes as vector paths. They stay sharp at any zoom level.
Backgrounds and overlays
To use an image as a watermark or page background, render it with absolute positioning inside page.background rather than as a body node:
{
"page": {
"size": "A4",
"background": [
{
"image": "https://cdn.example.com/letterhead.png",
"x": 0, "y": 0,
"width": "210mm", "height": "297mm"
}
]
},
"body": [...]
}
x, y, width, height are absolute, anchored to the top-left of the page. Anything in page.background is drawn behind the body and repeats on every page.
A few practical tips
- Cache base64 logos. A 50 KB base64 logo on every request adds up. Build the data URL once on your side and reuse it.
- Don't fetch images you don't trust. The engine fetches whatever URL you send. If your
dataincludes a user-supplied avatar URL, you're effectively asking gpdf-api to make an outbound HTTP call on your behalf — same risk profile as any server-side fetch. - Use SVG for sharp logos. Vector-in, raster-out (at the size you ask for), but the result is sharper than embedding a fixed-DPI PNG and hoping for the best.
- JPEG, not PNG, for photos. A 1500x1000 photo as PNG can be ~3 MB; as JPEG quality 85, often <300 KB. The engine doesn't re-encode either format, so the choice you make is what lands in the output.
Errors
| HTTP | code |
When |
|---|---|---|
| 400 | template_error |
Invalid format, malformed data URL, unsupported barcode value. |
| 413 | payload_too_large |
A fetched image exceeds 8 MB. |
| 504 | timeout |
An image source took longer than 4 s to respond. |
Related
- Templates → — where image nodes live in the template tree.
- Multi-page → — backgrounds and headers per page.
Something unclear or missing on this page?