Imageproxy
All you need to know to implement your super fast image proxy into your next application.
Implementation
Implementing our image proxy is incredibly simple. All you need is the ID (UUID) of the asset you want to distribute through the proxy.
The benefit of our solution lies in the fact that any changes to the status of the file (such as licenses, copyrights, etc.) will be reflected within 60 seconds. During this time, the files will be cached, ensuring efficiency and up-to-date content delivery.
Example:
The following link delivers the original image. By adding a few query params you can adjust that.
Resize
Allowed properties:
Width and height. Both values must be integers.
Resize and Crop
You can easy crop an image by adding width and height.
Focal point
Sometimes, our automatic focal point detection may not focus on the areas you need. By adding a focal point (which can also be done via the web UI), you can easily adjust this. Please ensure that you provide both width and height in this case—otherwise, setting a focal point will need to be done on the frontend (e.g., via CSS).
Format
While we believe WebP is currently the best image format, there are use cases where JPG or PNG is required.
In such cases, you can change the output format by adding the format query string parameter to the URL.
Controlling Compression with the quality Parameter
Another way to optimize image delivery is by adjusting the compression level using the quality query parameter.
This allows you to control the file size of the image.
Values range from 0 to 100, where 100 represents the best possible quality.
However, be cautious—setting the quality too low may introduce visible artifacts in the image.
As a rule of thumb, a quality setting between 75 and 90 is usually more than sufficient.
Proxy Support for All File Types
Here’s another useful feature:
Our proxy can be used to optimize the delivery of all file types—not just images.
This includes PDFs, Word documents, and especially video files, all of which can be served in an optimized format.
Keep in mind, however, that features like resizing and focal points are image-specific and won’t apply to these file types.
Special Case: Videos
For video files, the proxy automatically generates a screenshot, which can then be processed like a regular image.
This is especially helpful for creating optimized video thumbnails.
To achieve this you need to pass to the proxy url at least a width value.
Video Compression
The image proxy also acts as a gateway for delivering optimized videos.
These optimized versions can be accessed using the version query string parameter.
Currently, the following options are available: low, medium, and high.
The low version has the smallest file size.
Note that high is not the original file — it simply represents the largest available file size.
If the version parameter is used but the background optimization process has not yet finished,
the original format will be delivered.
Once the background processing is complete, the optimized version will automatically be served instead.
HLS
HLS videos (HTTP Live Streaming) are video content streamed using the HLS protocol, which divides videos into small segments and delivers them over HTTP. This protocol is known for its adaptive playback, where the video quality automatically adjusts to the user's internet speed to prevent buffering.
To enable video streaming with adaptive quality, where the video automatically adjusts to the client's available bandwidth, the HLS add-on must be used. This can be done within the settings of the tenant.
An HLS-compatible player is required to play such videos.
Once set up, you can access the playlist using the following URL:
Please be aware that the transformation of a video file into a HLS structure might depends on the size of the original video file.
Extra
For all statamic users: The implementation fits the standard focal point logic you already familiar with.