Blurry images

Understand pixel density and choose the right resolution for your images.

Blurry images are almost always caused by insufficient pixel density for the display they’re viewed on. Modern screens—especially smartphones, tablets, and high-resolution monitors—pack many more pixels into the same physical space than older displays.

The HTML/CSS to Image API automatically generates high-resolution images by default to ensure your images look crisp on all devices. Here’s everything you need to know about creating pixel-perfect images.

Today’s screens vary dramatically in pixel density:

• Standard displays: 1 physical pixel = 1 CSS pixel (1x)
• Retina/High-DPI displays: 2-4 physical pixels = 1 CSS pixel (2x-4x)
• Ultra-high resolution: 3+ physical pixels = 1 CSS pixel (3x+)

When you create an image at standard resolution (1x) and display it on a high-density screen, the browser must stretch those pixels to fill the available space—resulting in a blurry, pixelated appearance.

The 2x rule is simple: create images at double your intended display size.

Example:

• Display size needed: 400×400px
• Image source size: 800×800px (2x)
• Result: Sharp image on all screens

This ensures you have enough pixel data to satisfy high-density displays while still looking great on standard screens.

The HCTI API uses the device_scale parameter to control image resolution:

• HTML images: device_scale: 2 (high resolution by default)
• URL screenshots: device_scale: 1 (standard resolution)

Problem: Your source images are too small for high-DPI rendering.

Example: Using a 200×200px image that needs to display at 200×200px on a 2x display.

Solution: Use source images at 2x your display size:

<!-- Instead of this -->
<img src="logo-200x200.png" width="200" height="200">

<!-- Use this -->
<img src="logo-400x400.png" width="200" height="200">

Problem: URL screenshots default to device_scale: 1.

Solution: Explicitly set device_scale: 2 for URL images:

{
  "url": "https://example.com",
  "device_scale": 2
}

Problem: Some images in your HTML are high-resolution while others are not.

Solution: Ensure ALL images follow the 2x rule:

<!-- Good: All images are 2x their display size -->
<img src="header-800x200.png" width="400" height="100">
<img src="logo-200x200.png" width="100" height="100">
<img src="photo-1200x800.png" width="600" height="400">

For HTML images, verify your API request:

{
  "html": "<div>Your content</div>",
  "device_scale": 2
}

For URL images, always specify device scale:

{
  "url": "https://your-site.com",
  "device_scale": 2
}

Calculate if your images meet the 2x requirement:

1. Intended display size: How big will the image appear? (e.g., 300px wide)
2. Required source size: Multiply by device scale (300px × 2 = 600px wide)
3. Actual source size: Check your image file dimensions

Quick audit checklist:

• All images are 2x their CSS display size
• External images from CDNs have high-res versions
• Icons and logos have sufficient resolution
• Background images are appropriately sized

View your generated image on:

• Standard resolution monitor
• High-DPI laptop screen (MacBook, high-end Windows laptops)
• Mobile device (iPhone, Android phone)
• Tablet (iPad, Android tablet)

The image should look equally sharp on all devices.

Bad approach:

<div style="width: 1200px; height: 630px;">
  <img src="avatar-150x150.jpg" width="150" height="150">
  <!-- Image will be blurry on high-DPI displays -->
</div>

Good approach:

<div style="width: 1200px; height: 630px;">
  <img src="avatar-300x300.jpg" width="150" height="150">
  <!-- Image will be sharp on all displays -->
</div>

Bad approach:

.logo {
  width: 200px;
  height: 60px;
  background-image: url('logo-200x60.png');
}

Good approach:

.logo {
  width: 200px;
  height: 60px;
  background-image: url('logo-400x120.png');
  background-size: 200px 60px; /* Scale down to intended size */
}

For external images, use responsive image techniques:

<img src="photo-600x400.jpg"
     srcset="photo-600x400.jpg 1x, photo-1200x800.jpg 2x"
     width="600" height="400">

Target high-resolution displays specifically:

@media only screen and (-webkit-min-device-pixel-ratio: 2),
       only screen and (min-resolution: 192dpi) {
  .hero-image {
    background-image: url('hero-2x.jpg');
  }
}

Use SVG for logos and icons that scale perfectly at any resolution:

<img src="logo.svg" width="200" height="60">
<!-- SVG automatically scales to any device -->

Higher resolution increases pixel count; compressed file size also depends on content and format:

• device_scale: 1 → Base pixel count
• device_scale: 2 → 4x as many pixels
• device_scale: 3 → 9x as many pixels

1. Use appropriate compression: Balance quality vs. file size
2. Choose the right format:
   • PNG for graphics with transparency
   • JPG for photographs
   • WebP for modern browsers (when supported)
3. Consider bandwidth: Higher resolution may impact load times

When your image still looks blurry:

• Device scale is set to 2 (for HTML) or explicitly specified (for URLs)
• All source images are 2x their display size
• External CDN images have high-resolution versions available
• CSS background images use appropriately sized sources
• Vector graphics (SVG) are used where possible
• The generated image is being displayed at the correct size

Test your images across different scenarios:

<!-- Test HTML - put this in your browser -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
    <h1>Image Quality Test</h1>

    <!-- Your generated image -->
    <img src="your-generated-image.png" width="400" height="300">

    <!-- View at different sizes -->
    <img src="your-generated-image.png" width="200" height="150">
    <img src="your-generated-image.png" width="800" height="600">
</body>
</html>

Still experiencing blurry images? We’re here to help debug your specific case.

Email us: support@htmlcsstoimage.com

Include:

• Your API request (HTML/CSS or URL)
• Expected vs. actual results
• What devices/screens you’re testing on
• Any specific requirements for your use case

We love solving tricky rendering problems and helping you achieve pixel-perfect results.