ShortPixel’s Adaptive Images API can be used directly with images hosted on Amazon S3, as long as the image URL is formatted correctly and the S3 domain is associated with your ShortPixel account.
The Adaptive Images API URL generally has this structure:
https://cdn.shortpixel.ai/client/parameters/original-image-url
For example:
https://cdn.shortpixel.ai/client/w_800,q_lossy,ret_wait/https://example.com/image.jpg
The API URL contains the ShortPixel CDN URL, a client section, the optimization parameters, and the original image URL. The original URL must be an absolute URL pointing to the image.
1. Add your S3 domain to your ShortPixel account #
Before using the Adaptive Images API with your own images, you need to associate the image domain with your ShortPixel account.
To use the API key, please first add your domain to your account.
Log in to your ShortPixel account, go to Associate Domains, and add the domain where your images are hosted.
For Amazon S3 images, this usually means adding the full S3 bucket domain, for example:
eblocks-dev.s3.ap-northeast-1.amazonaws.com
Do not add only your website’s staging or production domain if the actual images are loaded directly from Amazon S3. The domain that needs to be associated is the one used in the original image URL.
2. Use the correct Amazon S3 URL format #
For ShortPixel’s system to process the image correctly, the S3 bucket should be placed before the AWS region URL.
Recommended format #
Use this format:
https://bucket-name.s3.region.amazonaws.com/path/to/image.jpg
Example:
https://eblocks-dev.s3.ap-northeast-1.amazonaws.com/properties/Ep4LKXshc1-1777018949134.jpg
ShortPixel expects the bucket-specific domain format when using the Adaptive Images API.
3. Build the Adaptive Images API URL #
Once the S3 image URL is using the correct format, you can add it to the Adaptive Images API URL.
Original S3 image:
https://eblocks-dev.s3.ap-northeast-1.amazonaws.com/properties/Ep4LKXshc1-1777018949134.jpg
Adaptive Images API URL:
https://cdn.shortpixel.ai/client/w_800,q_lossy,ret_wait/https://eblocks-dev.s3.ap-northeast-1.amazonaws.com/properties/Ep4LKXshc1-1777018949134.jpg
In this example:
w_800
resizes the image to 800px wide.
q_lossy
applies lossy optimization.
ret_wait
waits until the optimized image is ready before returning it.
ShortPixel also supports other parameters, including width, height, crop style, quality level, WebP/AVIF conversion, EXIF handling, and return behavior. For more information please see this article.
Troubleshooting #
The image does not load through the ShortPixel CDN #
Check that:
- The original S3 image URL is publicly accessible and there’s no hotlinking protection.
- The image URL uses this format:
https://bucket-name.s3.region.amazonaws.com/path/to/image.jpg
- The S3 domain is associated with your ShortPixel account:
bucket-name.s3.region.amazonaws.com
- The ShortPixel CDN URL includes the full original image URL after the parameters.
The domain is already associated, but it still does not work #
Make sure you associated the exact domain used in the image URL.
For example, if your image is loaded from:
https://eblocks-dev.s3.ap-northeast-1.amazonaws.com/properties/image.jpg
then the associated domain should be:
eblocks-dev.s3.ap-northeast-1.amazonaws.com
Associating only your website domain, beta domain, or staging domain will not be enough if the images are served directly from Amazon S3.