Image and screenshot options

Image renders use the same render request as PDFs, with output.format set to an image format and settings in output.image. The input can be a stored template, HTML you send with the request, or a URL to screenshot.

{
  "input": { "type": "html", "html": "<div class=\"card\">Hello {{ name }}</div>" },
  "data": { "name": "World" },
  "output": {
    "format": "png",
    "filename": "card.png",
    "image": { "viewport": { "width": 1200, "height": 630 }, "scale": 2 }
  }
}

Formats

Options

The output size is the viewport (or the clipped element, or the full page) multiplied by scale, unless you resize it with width and height.

Screenshot HTML

POST /v1/images/from-html takes the markup, optional head, data and image options at the top level. This example renders a social preview image at 1200 × 630 CSS pixels and a scale factor of 2, so the PNG is 2400 × 1260 pixels:

curl https://api-eu.dynamicdocumentapi.com/v1/images/from-html \
  -H "Authorization: Bearer $DYNAMIC_DOCUMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<div class=\"card\"><h1>{{ title }}</h1><p>{{ author }}</p></div>",
    "head": "<style>body{margin:0} .card{box-sizing:border-box;width:1200px;height:630px;padding:64px;display:flex;flex-direction:column;justify-content:center;background:#0f172a;color:#fff;font-family:Inter,sans-serif}</style>",
    "data": { "title": "How we generate documents", "author": "Alex Example" },
    "image": { "viewport": { "width": 1200, "height": 630 }, "scale": 2 },
    "filename": "og-image.png",
    "delivery": { "type": "binary" }
  }' \
  -o og-image.png

The image endpoints produce PNG by default. For JPEG or WebP, add "format": "jpeg" or "format": "webp" to the body.

Screenshot a URL

curl https://api-eu.dynamicdocumentapi.com/v1/renders \
  -H "Authorization: Bearer $DYNAMIC_DOCUMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "type": "url", "url": "https://example.com/pricing" },
    "output": {
      "format": "jpeg",
      "filename": "pricing.jpg",
      "image": {
        "viewport": { "width": 1440, "height": 900 },
        "full_page": true,
        "format_options": { "quality": 80 },
        "wait": { "until": "networkidle", "timeout_ms": 20000 }
      }
    }
  }'

The same rules as for URL input to PDF apply: the page must be publicly reachable, and you can pass headers, cookies, basic authentication and a user agent in input.http. See input types.

Crop, resize and transparency

Capture one element instead of the whole viewport:

{ "image": { "clip_selector": "#invoice-summary", "scale": 2 } }

Produce a transparent PNG or WebP by leaving out the page background. Make sure your CSS doesn't paint a background on html or body:

{ "image": { "clip_selector": ".badge", "omit_background": true, "scale": 3 } }

Resize the finished image, for example to fit a fixed slot in an email:

{ "image": { "width": 600, "height": 315, "fit": "cover" } }

Image templates

You can store an image design as a template today: create a code template, size the outer element (for example 1080 × 1080 pixels), and render it with output.format: "png". Set the viewport to the same size, or use clip_selector to capture exactly the element you designed. Data binding, filters and the whole template language work as they do for PDFs, including QR codes and barcodes.

{
  "input": { "type": "template", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" },
  "data": { "title": "Summer sale", "discount": 0.25 },
  "output": {
    "format": "png",
    "image": { "viewport": { "width": 1080, "height": 1080 }, "scale": 2 }
  }
}

You can also design images in the dashboard's canvas editor: choose New template → Blank image, or start from an image template in the gallery. Frames can use auto layout, and images can be cropped with smart crop or around a focal point. Make the properties you want to change per render dynamic, such as title.text, hero.src or badge.visible; a key defaults to element.property. Renders set them through data, flat as below or nested per element ({"title": {"text": "Summer Sale"}}), with POST /v1/renders or, as here, POST /v1/images/from-template:

{
  "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C",
  "data": { "title.text": "Summer Sale", "hero.src": "https://example.com/beach.jpg", "badge.visible": false },
  "format": "webp"
}

GET /v1/templates/{id}/schema lists a canvas template's dynamic_properties. Canvas templates render to PNG (the default), JPEG, WebP or PDF. Size variants, several sizes from one design, are planned. To let a web page or email request an image by URL without an API key, use signed links, served from https://img.dynamicdocumentapi.com.

Billed renders

An image render is 1 render, whatever its size. Test renders and failed renders are free. See Plans and limits.