HTML to Image

Render an HTML fragment or full page into a hosted PNG or JPG image.

POST/v1/render

Parameters

Name	Type	Default	Description
html	String	—	HTML to render. Required unless `template_id` is provided.
template_id	String	—	ID of a saved template. Use instead of `html`. See Templates.
variables	Object	`{}`	Key-value pairs to replace `{{key}}` placeholders in the HTML.
width	Integer	1080	Viewport width in pixels.
height	Integer	1350	Viewport height in pixels.
format	String	"png"	Output format: `"png"` or `"jpg"`.
selector	String	—	CSS selector to crop to a specific element (e.g. `"#card"`). Works for off-viewport elements.
device_scale	Float	1	Resolution multiplier. `2` produces a 2× retina image (double the pixel dimensions).
ms_delay	Integer	500	Extra wait in milliseconds after the page loads. Useful for animations or lazy renders. Max 30000.
transparent	Boolean	false	When `true`, removes the page background for a transparent PNG. Forces `format: "png"`.
image_url	String	—	URL that replaces the placeholder `DYNAMIC_IMAGE_URL` (or `URL_DA_IMAGEM_DINAMICA`) in the HTML before rendering.
full_page	Boolean	false	When `true`, captures the full scrollable height of the page instead of the viewport.
render_when_ready	Boolean	false	When `true`, ignores `ms_delay` and waits until `window.screenshotReady === true` (timeout 30s). Set this flag in your HTML when all async content is loaded.
viewport_landscape	Boolean	false	When `true`, swaps `width` and `height` to render in landscape orientation.
timezone	String	—	IANA timezone for the browser context (e.g. `"America/Sao_Paulo"`). Affects `Date` and time display in the rendered HTML.
crop_x, crop_y	Integer	0	Top-left corner (in pixels) of a custom crop region. Requires `crop_width` and `crop_height`.
crop_width, crop_height	Integer	0	Dimensions of the crop region in pixels. When both are set, captures only that rectangle.

ℹ️

Either html or template_id is required, but not both.

Response

JSON

{
  "url": "https://api.starkrender.com/v1/image/uuid",
  "id":  "uuid"
}

Examples

Basic PNG

cURL

curl -X POST https://api.starkrender.com/v1/render \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html":   "<div style=\"background:#0f172a;width:1080px;height:1080px;color:#fff\">Hello</div>",
    "width":  1080,
    "height": 1080
  }'

JPG with retina resolution

JSON Body

{
  "html":         "...",
  "width":        1080,
  "height":       1080,
  "format":       "jpg",
  "device_scale": 2
}

Crop to a specific element

JSON Body

{
  "html":     "<div id='card' style='...'>My Card</div><footer>Not captured</footer>",
  "selector": "#card",
  "width":    1080,
  "height":   1350
}

Transparent background

JSON Body

{
  "html":        "<div style='padding:30px;background:rgba(99,102,241,0.9);color:#fff;border-radius:12px'>Badge</div>",
  "width":       400,
  "height":      120,
  "transparent": true
}

Dynamic image placeholder

Use the placeholder DYNAMIC_IMAGE_URL (or URL_DA_IMAGEM_DINAMICA) as the src of any <img> and pass the real URL in image_url. This lets you reuse the same HTML template with different images.

JSON Body

{
  "html":      "<div><img src='URL_DA_IMAGEM_DINAMICA' style='width:100%'><h1>Breaking News</h1></div>",
  "image_url": "https://example.com/photo.jpg",
  "width":     1080,
  "height":    1350
}

Fonts

StarkRender automatically detects font-family declarations in your HTML and loads them before rendering.

Bundled fonts (fastest): Montserrat, Inter, Playfair Display
Google Fonts: any other family is fetched from Google Fonts, cached locally, and served from the same server on subsequent requests
Rendering waits for document.fonts.ready — no font flash or fallback glyphs