# Image and screenshot options

> Render PNG, JPEG and WebP images from templates, HTML or URLs, with viewport, scale, cropping, transparency and quality settings.



Image renders use the same [render request](/docs/renders) 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.

```json
{
  "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 [#formats]

| Format | Status    | Notes                                                                                                     |
| ------ | --------- | --------------------------------------------------------------------------------------------------------- |
| `png`  | Available | Lossless, supports transparency, the default for the image endpoints                                      |
| `jpeg` | Available | Smaller files for photographic content; `quality` and `progressive` apply                                 |
| `webp` | Available | Lossy with `quality`, or lossless with `lossless`; supports transparency. At most 16,383 pixels per side. |

## Options [#options]

| Option                              | Type    | Default                  | Description                                                                                                                                   |
| ----------------------------------- | ------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `format_options.quality`            | number  | `85` (JPEG), `80` (WebP) | Quality from 1 to 100 for JPEG and lossy WebP                                                                                                 |
| `format_options.progressive`        | boolean | `false`                  | Encode JPEG progressively                                                                                                                     |
| `format_options.lossless`           | boolean | `false`                  | Lossless WebP; `quality` doesn't apply                                                                                                        |
| `transparent`                       | boolean | `false`                  | Keep transparency instead of a white background (PNG and WebP)                                                                                |
| `scale`                             | number  | `1`                      | Device scale factor from 1 to 3. `2` doubles the pixel dimensions, like a high-resolution screen.                                             |
| `width`, `height`                   | number  | none                     | Resize the finished image in pixels. With only one of them set, the aspect ratio is kept.                                                     |
| `fit`                               | string  | `"contain"`              | How the image fits into `width` × `height`: `contain` scales it to fit, `cover` scales it to fill and crops the overflow, `fill` stretches it |
| `viewport.width`, `viewport.height` | number  | `1280` × `720`           | Browser viewport in CSS pixels, from 16 to 8192 each, for HTML and URL input                                                                  |
| `full_page`                         | boolean | `false`                  | Capture the whole scrollable page instead of just the viewport                                                                                |
| `clip_selector`                     | string  | none                     | Capture only the element matching this CSS selector                                                                                           |
| `omit_background`                   | boolean | `false`                  | Leave out the page's default white background, so transparent areas stay transparent                                                          |
| `wait.until`                        | string  | `"load"`                 | Wait strategy: `load`, `networkidle`, `selector`, `ready_flag` or `delay`, as in [PDF options](/docs/pdf-options#waiting-and-scripting)       |
| `wait.selector`                     | string  | none                     | CSS selector to wait for, with `until: "selector"`                                                                                            |
| `wait.delay_ms`                     | number  | `0`                      | Extra delay in milliseconds, up to 10000                                                                                                      |
| `wait.timeout_ms`                   | number  | `30000`                  | Maximum time for each wait step                                                                                                               |

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 [#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:

```bash
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 [#screenshot-a-url]

```bash
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](/docs/renders#input-types).

## Crop, resize and transparency [#crop-resize-and-transparency]

Capture one element instead of the whole viewport:

```json
{ "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`:

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

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

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

## Image templates [#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](/docs/template-language) work as they do for PDFs, including QR codes and barcodes.

```json
{
  "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`:

```json
{
  "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](/docs/signed-links), served from `https://img.dynamicdocumentapi.com`.

## Billed renders [#billed-renders]

An image render is 1 render, whatever its size. Test renders and failed renders are free. See [Plans and limits](/docs/plans-and-limits#what-counts-as-a-render).