Image Optimization
Optimize images for faster PDF generation and smaller file sizes without sacrificing quality.
Why Optimize Images?
Images are typically the largest contributor to PDF file size and generation time. Optimizing them has three benefits:
- Faster generation — Smaller images download and embed faster
- Smaller PDFs — Reduced file size for storage and delivery
- Better user experience — Faster downloads for end users
Choosing the Right Format
| Format | Best For | Transparency | File Size |
|---|---|---|---|
| JPEG | Photos, complex images | No | Small |
| PNG | Logos, icons, screenshots | Yes | Medium-Large |
| WebP | Modern alternative to JPEG/PNG | Yes | Smallest |
| SVG | Vector logos, icons | Yes | Tiny (vector) |
General Rule
Use JPEG for photographs and PNG for logos or graphics that need transparency. If your images are already on a CDN, check if it can serve optimized formats automatically.Right-Sizing Images
The most impactful optimization is using correctly sized images:
- If your image element is 200×100px, don't use a 2000×1000px source image
- Resize images to 2× the display size for sharp results on high-DPI displays
- A 200×100px element needs at most a 400×200px source image
| Element Size | Recommended Image Size | Maximum Image Size |
|---|---|---|
| 100×50px | 200×100px | 400×200px |
| 200×100px | 400×200px | 600×300px |
| 300×200px | 600×400px | 900×600px |
Image Compression
- JPEG quality — 80–85% quality is usually indistinguishable from 100% at document sizes
- PNG compression — Use tools like TinyPNG or pngquant to reduce PNG sizes by 50–70%
- Strip metadata — Remove EXIF data and color profiles that add unnecessary bytes
Image Hosting Best Practices
- Use a CDN — Host images on a CDN for fast, global access
- Stable URLs — Use permanent URLs that won't change or expire
- No redirects — Each redirect adds latency; use direct URLs
- HTTPS required — All image URLs must use HTTPS
- Fast response — Images should load in under 500ms
Expiring URLs
Don't use pre-signed URLs with short expiry times for template images. If the URL expires before generation, the image won't appear in the PDF.Logo Optimization
Logos appear on almost every document. Optimize them once for maximum benefit:
- Use PNG with transparency for logos on colored backgrounds
- Keep logo files under 50KB
- Pre-size to the exact dimensions used in templates
- Use the same logo URL across all templates for consistent caching
Dynamic Image Optimization
When passing image URLs in data (e.g., product photos, user avatars):
- Resize on your server before sending to the API
- Use an image processing service (Cloudinary, Imgix, etc.) to resize on-the-fly
- Cache processed images so the same URL is reused
- Validate that URLs are accessible before sending the generation request
Optimization Checklist
- ☐ All images are right-sized for their display dimensions
- ☐ Photos use JPEG at 80–85% quality
- ☐ PNGs are compressed with a tool like TinyPNG
- ☐ EXIF metadata is stripped
- ☐ Images are hosted on a CDN
- ☐ All URLs use HTTPS and respond quickly
- ☐ No unnecessary redirects in image URLs
- ☐ Logo files are under 50KB
Next Steps
- Image Elements — How to use images in templates
- Dynamic Images — Pass images via data
- Performance — General optimization tips