Formats

The Dynamic Image API supports a wide range of input and output image formats, allowing you to convert between different formats on-the-fly.

Format Parameter

Parameter: format
Example: ?format=png

Supported Input Formats

The API can process images in the following input formats:

JPEG - Standard web image format
WebP - Modern web format with better compression
GIF - Graphics Interchange Format (including animated)
PNG - Portable Network Graphics (with transparency support)
TGA - Truevision TGA format
BMP - Bitmap image format
PBM - Portable Bitmap format
TIFF - Tagged Image File Format
HEIC (beta) - High Efficiency Image Container
HEIF (beta) - High Efficiency Image Format

Supported Output Formats

You can convert images to these output formats:

JPEG - Widely compatible, good for photos
WebP - Modern format with excellent compression (maximum 16k pixels on either dimension)
PNG - Best for images requiring transparency
GIF - Suitable for simple graphics and animations

Animation Formats (Preview)

Note: Animation manipulation is still being developed, some features might change.

The API supports manipulation of animated images in these formats:

WebP - Animated WebP images
GIF - Traditional animated GIFs
PNG - Animated PNG (APNG)

Usage Examples

Format Conversion


# Convert any supported input to PNG
https://cdn.filezen.dev/image.jpg?format=png

# Convert to WebP for better compression
https://cdn.filezen.dev/image.png?format=webp

# Convert to JPEG for universal compatibility
https://cdn.filezen.dev/image.webp?format=jpeg

Combining with Other Parameters


# Convert to WebP with quality adjustment
https://cdn.filezen.dev/image.jpg?format=webp&quality=80

# Convert to PNG with resizing
https://cdn.filezen.dev/image.jpg?format=png&width=800

# Convert to JPEG with cropping
https://cdn.filezen.dev/image.png?format=jpeg&crop=500,500,0,0

Best Practices

Choose the Right Format

JPEG

Best for: Photographs, images with many colors
Pros: Universal compatibility, good compression for photos
Cons: No transparency support, lossy compression

WebP

Best for: Modern web applications, when file size matters
Pros: Superior compression, supports transparency and animation
Cons: Limited older browser support

PNG

Best for: Images requiring transparency, logos, simple graphics
Pros: Lossless compression, transparency support
Cons: Larger file sizes for complex images

GIF

Best for: Simple animations, very basic graphics
Pros: Universal animation support
Cons: Limited color palette, larger files than modern formats

Automatic Format Selection

Instead of specifying a format, you can let the API choose the best format based on the client’s browser capabilities by omitting the format parameter. The API will automatically serve:

WebP to supporting browsers for better compression
JPEG/PNG fallbacks for older browsers

Common Pitfalls

WebP Settings

Images will only be encoded in WebP format if you have WebP enabled in your optimizer settings.

Transparency Handling

When converting from a format that supports transparency (PNG, WebP) to one that doesn’t (JPEG), all transparent elements will become opaque (usually white or black background).

Size Limitations

WebP output images have a maximum dimension limit of 16,000 pixels on either width or height.

Animation Considerations

When converting animated formats:

Converting animated GIF to JPEG will only output the first frame
Converting to static formats loses animation data
Animation features are still in preview and may change

Format-Specific Examples


# Optimize a photo for web (JPEG to WebP)
https://cdn.filezen.dev/photo.jpg?format=webp&quality=85

# Preserve transparency (PNG to PNG with optimization)
https://cdn.filezen.dev/logo.png?format=png&quality=90

# Create thumbnails (any format to JPEG)
https://cdn.filezen.dev/image.heic?format=jpeg&width=300&height=300

# Optimize animated content
https://cdn.filezen.dev/animation.gif?format=webp&quality=80