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.
Default High Resolution
The HCTI API defaults to 2x resolution (device_scale: 2) for HTML images to prioritize image quality. This ensures your images look sharp on both standard and high-DPI displays.
Understanding Pixel Density
The Modern Display Challenge
Today’s screens vary dramatically in pixel density:
Standard displays: 1 physical pixel = 1 CSS pixel (1x)
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 Explained
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.
Device Scale Settings
The HCTI API uses the device_scale parameter to control image resolution:
Setting
Resolution
Use Case
File Size
1
Standard (1x)
Legacy screens, thumbnails
Smallest
2
High (2x)
Recommended for web
Medium
3
Maximum (3x)
Print, premium displays
Largest
Default Behavior
HTML images: device_scale: 2 (high resolution by default)
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
Step 3: Test on Different Displays
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.
Real-World Examples
Example 1: Social Media Card
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>
@media only screen and (-webkit-min-device-pixel-ratio: 2),
only screen and (min-resolution: 192dpi) {
.hero-image {
background-image: url('hero-2x.jpg');
}
}
Vector Graphics for Perfect Scaling
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 -->
Performance Considerations
File Size Impact
Higher resolution means larger files:
device_scale: 1 → Base file size
device_scale: 2 → ~4x larger files
device_scale: 3 → ~9x larger files
Optimization Strategies
Use appropriate compression: Balance quality vs. file size
Choose the right format:
PNG for graphics with transparency
JPG for photographs
WebP for modern browsers (when supported)
Consider bandwidth: Higher resolution may impact load times
Performance Tip
Use device_scale: 2 as the sweet spot for web usage. It provides excellent quality on all displays while keeping file sizes reasonable.
Troubleshooting Checklist
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
Browser Testing
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>
Need Help?
Still experiencing blurry images? We’re here to help debug your specific case.