The Dynamic Image API allows you to modify and optimize images in real time with minimal effort. By appending query parameters to your image URIs, you can easily transform, crop, resize, adjust colors, and more—enabling seamless, on-the-fly image manipulation for web pages, applications, and other digital content. The API is backed by the Bunny Optimizer service, which optimizes images for improved loading times and bandwidth savings.

What you'll need

Before you dive in, make sure you have the following prerequisites in place:

A bunny.net account ( Log in or sign up for a free trial).
An active Pull Zone set up.
Bunny Optimizer enabled.
Dynamic Image API is enabled in the Bunny Optimizer settings. To enable that option, go to [Your Pull Zone] -> Optimizer -> enable Dynamic Image API.

Using the Dynamic Image API

The core principle of the Dynamic Image API is that all transformations are performed on the fly. You simply add parameters to the image’s URL, and Bunny Optimizer processes these parameters, delivering a transformed output image.

The API supports a wide array of filters and transformations. Common resizing methods include adjusting the width and height while maintaining proportions (you can adjust one dimension at a time—either width or height—and the other will be set as a result). To emphasize particular elements within the frame, you can crop images or use focus cropping to highlight specific areas. Additional options allow for luminosity adjustments, color manipulation, and changes to image geometry, such as flipping, flopping, or rotating. Enhancements like sharpening, gamma correction, saturation, tinting, and contrast adjustments further empower you to refine the final look and feel of your images.

Let's say you have this original:

For a simple thumbnail with a 16:9 aspect ratio, attach ?aspect_ratio=16:9&width=256 to the source image URI. This ensures a properly cropped thumbnail, ready for use in various layouts such as a thumbnail wall:

If a vertical orientation is required, ?height=700&aspect_ratio=10:16 can be used to produce a tall, portrait-style image:

In some cases, you might want to change the composition of your image completely to present a different focus point or mood. From the original image below, we will focus on the bunnies separately and touch up the end results slightly.

By attaching ?crop=800,1270,1100,2695&width=500&sharpen=true&gamma=25&contrast=4&brightness=4&saturation=20 to the source image, you isolate and enhance a section of the image:

Another example can be achieved by using ?focus_crop=1550,1150,1.0,0.74&width=700&gamma=15&tint=ffeeee&flop=true, which not only highlights a specific area but also applies color and orientation adjustments:

By combining the parameters, you can achieve countless variations of output to meet the need for your projects.

Common use cases

The Dynamic Image API is frequently used to generate thumbnails on-the-fly, ensuring that images are appropriately scaled and cropped to fit various designs without manually editing or storing multiple image versions. It is equally well suited to supplying multiple resolutions of the same image, accommodating everything from mobile devices to large desktop displays. Additionally, the API’s functions for adjusting brightness, contrast, and color, as well as its ability to blur or sharpen images, simplify the process of achieving the visual style desired for any given image or project.

API functionalities

Resizing
Cropping
Luminosity
Color manipulation
Translations
Blur & Sharpen
Face detection
Quality
Formats