Format Conversion
Selecting an Output Format
Use the format parameter to convert the image to a different format on the fly.
/format=webp/https://example.com/photo.jpg
If format is not specified, the output format matches the input format - no conversion is applied.
Supported output formats
| Value | Description |
|---|---|
webp | WebP - good compression with transparency support |
jpeg | JPEG - universal compatibility, lossy |
png | PNG - lossless, supports transparency |
avif | AVIF - best compression, slower encoding |
gif | GIF - animated image support |
bmp | BMP - uncompressed bitmap |
tiff | TIFF - high-quality, lossless |
ico | ICO - Windows icon format |
jxl | JPEG XL - next-gen, wide gamut support |
best | Auto-select the smallest format for this image |
See Best Format for details on the best value.
Quality
The q parameter controls lossy compression quality for JPEG and WebP output.
| Param | Type | Range | Default |
|---|---|---|---|
q | integer | 1-100 | Encoder default |
Higher values produce larger files with better quality. Lower values produce smaller files with more compression artifacts.
/webp,q85/https://example.com/photo.jpg
/jpeg,q70/https://example.com/photo.jpg
The q parameter only applies to jpeg and webp output. It has no effect on lossless formats such as png, bmp, or tiff.
Format Comparison
| Format | Compression | Transparency | Animation | Notes |
|---|---|---|---|---|
webp | Good (lossy/lossless) | Yes | Yes | Broad browser support, ideal for web |
avif | Excellent | Yes | Yes | Smaller files than WebP, slower to encode |
jxl | Excellent | Yes | Yes | Next-gen format, wide color gamut |
jpeg | Good (lossy) | No | No | Universal compatibility, best for photos |
png | Moderate (lossless) | Yes | No | Best for graphics, logos, screenshots |
gif | Low | Partial (1-bit) | Yes | Legacy animated format |
bmp | None (uncompressed) | No | No | Raw pixels, large file size |
tiff | Optional (lossless) | Yes | No | High-quality archival use |
ico | - | Yes | No | Resized to standard icon sizes |
For web use, prefer webp or avif. WebP is well-supported across all modern browsers and offers a good balance of quality and file size. AVIF provides better compression but may be slower to generate for large images.
Best Format
Use format=best to let PreviewProxy automatically pick the smallest output format for each image.
/format=best/https://example.com/photo.jpg
How it works
- Complexity measurement - the image is scanned with a Sobel edge detector on a downsampled thumbnail to measure edge density.
- Candidate selection - for complex images (many edges: photos, detailed graphics) the candidates are
jpeg,webp,avif, andjxl. For simple images (flat areas, logos, illustrations)pngis added as a lossless candidate. - Format trial - all candidates are encoded and the one producing the smallest file is returned.
Configuration
| Variable | Default | Description |
|---|---|---|
PP_BEST_FORMAT_PREFERRED_FORMATS | jpeg,webp,png | Formats to trial. Add avif or jxl for better compression at the cost of slower encoding |
PP_BEST_FORMAT_COMPLEXITY_THRESHOLD | 5.5 | Edge density threshold (0-100). Lossless formats (png) are excluded from candidates above this |
PP_BEST_FORMAT_MAX_RESOLUTION | (none) | Above this megapixel count, skip the multi-encode trial and pick one format directly |
PP_BEST_FORMAT_BY_DEFAULT | false | Apply best-format selection when no format param is provided |
PP_BEST_FORMAT_ALLOW_SKIPS | false | Skip re-encoding when best format matches the source format and no other transforms are applied |
Enable by default
To make every image response use the best format without requiring format=best in the URL:
PP_BEST_FORMAT_BY_DEFAULT=true
Interaction with output disallow list
Formats listed in PP_OUTPUT_DISALLOW_LIST are excluded from the candidate set. If all candidates are disallowed, the request returns an error.
format=best works well combined with quality: /best,q85/https://example.com/photo.jpg
ICO Output
When format=ico is specified, the image is resized to standard Windows icon dimensions before encoding. This makes it suitable for use as a favicon or application icon.
/format=ico/https://example.com/logo.png
Examples
Convert JPEG to WebP
/format=webp/https://example.com/photo.jpg
Convert to WebP with quality
/webp,q85/https://example.com/photo.jpg
Resize and convert in one request
/800x600,webp,q80/https://example.com/photo.jpg
Lossless PNG output
/format=png/https://example.com/photo.jpg
Generate a favicon
/32x32,ico/https://example.com/logo.png
High-efficiency AVIF for bandwidth savings
/avif,q75/https://example.com/photo.jpg
Auto-select the best format
/format=best/https://example.com/photo.jpg
Best format with quality
/best,q85/https://example.com/photo.jpg