Format Conversion
Selecting an Output Format
Section titled “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.jpgIf format is not specified, the output format matches the input format - no conversion is applied.
Supported output formats
Section titled “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
Section titled “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.jpgFormat Comparison
Section titled “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 |
Best Format
Section titled “Best Format”Use format=best to let PreviewProxy automatically pick the smallest output format for each image.
/format=best/https://example.com/photo.jpgHow it works
Section titled “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
Section titled “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
Section titled “Enable by default”To make every image response use the best format without requiring format=best in the URL:
PP_BEST_FORMAT_BY_DEFAULT=trueInteraction with output disallow list
Section titled “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.
ICO Output
Section titled “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.pngExamples
Section titled “Examples”Convert JPEG to WebP
Section titled “Convert JPEG to WebP”/format=webp/https://example.com/photo.jpgConvert to WebP with quality
Section titled “Convert to WebP with quality”/webp,q85/https://example.com/photo.jpgResize and convert in one request
Section titled “Resize and convert in one request”/800x600,webp,q80/https://example.com/photo.jpgLossless PNG output
Section titled “Lossless PNG output”/format=png/https://example.com/photo.jpgGenerate a favicon
Section titled “Generate a favicon”/32x32,ico/https://example.com/logo.pngHigh-efficiency AVIF for bandwidth savings
Section titled “High-efficiency AVIF for bandwidth savings”/avif,q75/https://example.com/photo.jpgAuto-select the best format
Section titled “Auto-select the best format”/format=best/https://example.com/photo.jpgBest format with quality
Section titled “Best format with quality”/best,q85/https://example.com/photo.jpg