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:

  1. Embed an existing image — image node with a URL or base64.
  2. Generate a code — qr or barcode node, 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 data includes 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.

Something unclear or missing on this page?