Docs / Parameters / dpi parameter | HTML to Image Docs

DPI Parameter

The dpi parameter (Device Pixel Ratio) controls the resolution of the generated image.

Specifications

Property	Value
Type	integer
Required	No
Default	1 (Screenshot API), 2 (HTML API)
Range	1-4
API	Both HTML/CSS and Screenshot APIs

Description

The DPI parameter:

Controls the image resolution
Affects the final image size
Impacts processing time and memory usage
Determines the clarity of text and graphics

Higher DPI values significantly increase processing time and memory usage. For most use cases, a DPI of 1 or 2 provides sufficient quality.

When setting fullpage to true the DPI value will be forced to 1. If you need a larger DPI then use set dimensions.

When using DPI values greater than 1, remember that the actual rendered dimensions will be multiplied by the DPI value. For example, a canvas with width=800 and DPI=2 will be rendered at 1600px wide. If you specify width and height parameters, you should either:

Increase your dimensions proportionally with DPI (e.g., double them for DPI=2)
Or omit width/height to let the image scale naturally with DPI

Examples

Basic Screenshot (Default DPI)

{
    "url": "https://example.com"
}

High Resolution HTML Capture

{
    "html": "<div>High Quality Text</div>",
    "dpi": 2
}

Maximum Quality Screenshot

{
    "url": "https://example.com",
    "dpi": 4,
    "webhook_url": "https://your-domain.com/webhook"
}

DPI Value Guide

DPI	Use Case	Notes
1	Quick screenshots, previews	Fastest processing, smallest file size
2	Standard quality, most use cases	Good balance of quality and performance
3	High quality, printing	Larger files, slower processing
4	Maximum quality	Very large files, significantly slower

When using DPI values of 3 or 4:

Always use the webhook_url parameter
Expect longer processing times
Be prepared for larger file sizes

Best Practices

Choose the Right DPI

Use DPI 1 for thumbnails and previews
Use DPI 2 for standard web use
Use DPI 3-4 only when high resolution is required

Optimize Performance

Combine with appropriate viewport dimensions
Use webhooks for high DPI captures
Consider file size requirements

Testing

Test different DPI values with your content
Check file sizes and quality
Monitor processing times

The HTML API defaults to DPI 2 for sharper text rendering, while the Screenshot API defaults to DPI 1 for faster processing.

Common values

1 - default for screenshots. Fastest, smallest files, plenty for thumbnails and previews.
2 - retina output. Doubles memory and time, but produces files sized for high-DPI displays without manual scaling.
3 - rare, only for print. Use webhook_url to avoid the 30 second sync timeout.

When to use

Default to 1 unless you are rendering for a retina display target. Use 2 for any image that will appear in a UI on modern phones or laptops. Reach for 3 only for printed output or marketing assets that need to scale beyond a standard screen.

Common mistakes

Combining dpi: 3 with sync requests. The render usually exceeds the 30 second budget. Always pair high DPI with webhook_url.
Forgetting that DPI multiplies dimensions. A width: 1200, dpi: 2 produces a 2400px wide PNG. See dimensions for sizing guidance.

Documentation