Render options

Every field the render endpoints accept — source, output format, viewport, page timing, image settings, and PDF settings.

Both /v1/render and /v1/render/template take the same options, apart from the source fields. Everything below is optional unless marked required, and unknown fields are rejected.

Source

PropType

html?string

Complete HTML document to render. /v1/render only. Required unless url is given; wins if both are sent. Max 5 MB.

Typestring

url?string

Publicly reachable URL to render. /v1/render only. Required unless html is given.

Typestring

templateIdstring

ID of a saved template. /v1/render/template only, where it replaces html and url.

Typestring

variables?Record<string, string | number | boolean | null>

Values substituted into the template's {{ placeholders }}. /v1/render/template only.

TypeRecord<string, string | number | boolean | null>

Default{}

Output

PropType

format?"png" | "webp" | "jpg" | "pdf"

Output format, which also picks the response content-type.

Type"png" | "webp" | "jpg" | "pdf"

Default"png"

quality?number

Compression quality from 1 to 100. Applies to jpg and webp; ignored for png and pdf.

Typenumber

Default100

fileName?string

Attachment filename without the extension, used in content-disposition. Slugified, capped at 80 characters. Max 160 characters in.

Typestring

PNG is lossless and supports transparency — good for previews and social images with a transparent background. WebP at quality: 80 is usually a third the size of the same PNG. JPG is the safest choice for old email clients. PDF is the only paged format, and the only one that uses the PDF settings below.

Viewport

PropType

width?number

Viewport width in pixels. For PDFs without pdfFormat, this is also the page width.

Typenumber

Default1024

height?number

Viewport height in pixels. For PDFs without pdfFormat, this is also the page height.

Typenumber

Default768

deviceScaleFactor?number

Pixel density from 1 to 4. The default renders at 2x, so images stay sharp on high-DPI screens.

Typenumber

Default2

A 1024 × 768 viewport at deviceScaleFactor: 2 produces a 2048 × 1536 image. Drop it to 1 when file size matters more than sharpness.

Page timing

PropType

waitUntil?"load" | "domcontentloaded" | "networkidle"

How long to wait before capturing. domcontentloaded is fastest; networkidle waits for the network to settle, which matters for pages that fetch their own data.

Type"load" | "domcontentloaded" | "networkidle"

Default"domcontentloaded"

waitForTimeout?number

Extra delay in milliseconds after waitUntil, up to 10,000. Use it for animations, web fonts, or charts that draw after load.

Typenumber

Default0

media?"screen" | "print"

Which CSS media type the page is rendered with. Use print to apply your @media print rules.

Type"screen" | "print"

Default"screen"

reducedMotion?"reduce" | "no-preference"

Motion preference reported to the page. Accepted for compatibility; the current renderer does not apply it.

Type"reduce" | "no-preference"

Default"reduce"

Image settings

Ignored when format is pdf.

PropType

fullPage?boolean

Capture the entire scrollable page instead of just the viewport. Width still comes from width.

Typeboolean

Defaultfalse

transparentBackground?boolean

Render without the default white backdrop, so uncovered areas stay transparent. PNG and WebP only.

Typeboolean

Defaultfalse

omitBackground?boolean

Alias for transparentBackground. Either one turns it on.

Typeboolean

Defaultfalse

PDF settings

Ignored for image formats.

PropType

pdfFormat?string

Paper size, such as "A4" or "Letter". When set, it replaces width and height as the page size.

Typestring

printBackground?boolean

Include CSS backgrounds and background images. On by default, unlike a browser's print dialog.

Typeboolean

Defaulttrue

margin?{ top?: string; right?: string; bottom?: string; left?: string }

Page margins as CSS lengths, e.g. { "top": "20mm", "bottom": "20mm" }.

Type{ top?: string; right?: string; bottom?: string; left?: string }

scale?number

Scale of the rendered content, from 0.1 to 2.

Typenumber

Default1

preferCSSPageSize?boolean

Let the page's CSS @page size win over pdfFormat, width, and height.

Typeboolean

Defaultfalse

Worked examples

{
  "html": "<!doctype html><html>…</html>",
  "format": "pdf",
  "pdfFormat": "A4",
  "printBackground": true,
  "margin": { "top": "18mm", "bottom": "18mm", "left": "14mm", "right": "14mm" },
  "media": "print",
  "fileName": "invoice-1842"
}

{
  "html": "<!doctype html><html>…</html>",
  "format": "png",
  "width": 1200,
  "height": 630,
  "deviceScaleFactor": 1,
  "fileName": "og-launch-week"
}

{
  "url": "https://example.com/pricing",
  "format": "webp",
  "quality": 80,
  "width": 1440,
  "height": 900,
  "fullPage": true,
  "waitUntil": "networkidle",
  "waitForTimeout": 500
}

{
  "html": "<div class=\"badge\">Pro</div>",
  "format": "png",
  "width": 400,
  "height": 120,
  "transparentBackground": true
}