{"id":2893,"date":"2026-04-28T12:56:07","date_gmt":"2026-04-28T12:56:07","guid":{"rendered":"https:\/\/kb.shortpixel.com\/?post_type=docs&p=2893"},"modified":"2026-04-28T12:57:04","modified_gmt":"2026-04-28T12:57:04","password":"","slug":"using-the-adaptive-images-api-with-images-on-amazon-s3","status":"publish","type":"docs","link":"https:\/\/kb.shortpixel.com\/knowledge-base\/article\/using-the-adaptive-images-api-with-images-on-amazon-s3\/","title":{"rendered":"Using the Adaptive Images API with images on Amazon S3"},"content":{"rendered":"\n

ShortPixel\u2019s Adaptive Images API<\/a> 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.<\/p>\n\n\n\n

The Adaptive Images API URL generally has this structure:<\/p>\n\n\n\n

https:\/\/cdn.shortpixel.ai\/client\/parameters\/original-image-url<\/pre>\n\n\n\n
For example:<\/p>\n\n\n\n
https:\/\/cdn.shortpixel.ai\/client\/w_800,q_lossy,ret_wait\/https:\/\/example.com\/image.jpg<\/pre>\n\n\n\n
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.<\/p>\n\n\n\n
\n\n\n\n
1. Add your S3 domain to your ShortPixel account<\/h2>\n\n\n\n
Before using the Adaptive Images API with your own images, you need to associate the image domain with your ShortPixel account.<\/p>\n\n\n\n
To use the API key, please first add your domain to your account.<\/p>\n\n\n\n
Log in to your ShortPixel account, go to Associate Domains<\/a><\/strong>, and add the domain where your images are hosted.<\/p>\n\n\n\n
For Amazon S3 images, this usually means adding the full S3 bucket domain, for example:<\/p>\n\n\n\n
eblocks-dev.s3.ap-northeast-1.amazonaws.com<\/pre>\n\n\n\n
Do not add only your website\u2019s 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.<\/p>\n\n\n\n
\n\n\n\n
2. Use the correct Amazon S3 URL format<\/h2>\n\n\n\n
For ShortPixel\u2019s system to process the image correctly, the S3 bucket should be placed before the AWS region URL.<\/p>\n\n\n\n
Recommended format<\/h3>\n\n\n\n
Use this format:<\/p>\n\n\n\n
https:\/\/bucket-name.s3.region.amazonaws.com\/path\/to\/image.jpg<\/pre>\n\n\n\n
Example:<\/p>\n\n\n\n
https:\/\/eblocks-dev.s3.ap-northeast-1.amazonaws.com\/properties\/Ep4LKXshc1-1777018949134.jpg<\/pre>\n\n\n\n
ShortPixel expects the bucket-specific domain format when using the Adaptive Images API.<\/p>\n\n\n\n
\n\n\n\n
3. Build the Adaptive Images API URL<\/h2>\n\n\n\n
Once the S3 image URL is using the correct format, you can add it to the Adaptive Images API URL.<\/p>\n\n\n\n
Original S3 image:<\/p>\n\n\n\n
https:\/\/eblocks-dev.s3.ap-northeast-1.amazonaws.com\/properties\/Ep4LKXshc1-1777018949134.jpg<\/pre>\n\n\n\n
Adaptive Images API URL:<\/p>\n\n\n\n
https:\/\/cdn.shortpixel.ai\/client\/w_800,q_lossy,ret_wait\/https:\/\/eblocks-dev.s3.ap-northeast-1.amazonaws.com\/properties\/Ep4LKXshc1-1777018949134.jpg<\/pre>\n\n\n\n
In this example:<\/p>\n\n\n\n
w_800<\/pre>\n\n\n\n
resizes the image to 800px wide.<\/p>\n\n\n\n
q_lossy<\/pre>\n\n\n\n
applies lossy optimization.<\/p>\n\n\n\n
ret_wait<\/pre>\n\n\n\n
waits until the optimized image is ready before returning it.<\/p>\n\n\n\n
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<\/a>.<\/p>\n\n\n\n
\n\n\n\n
Troubleshooting<\/h2>\n\n\n\n
The image does not load through the ShortPixel CDN<\/h3>\n\n\n\n
Check that:<\/p>\n\n\n\n
    \n
  1. The original S3 image URL is publicly accessible and there’s no hotlinking protection.<\/li>\n\n\n\n
  2. The image URL uses this format:<\/li>\n<\/ol>\n\n\n\n
    https:\/\/bucket-name.s3.region.amazonaws.com\/path\/to\/image.jpg<\/pre>\n\n\n\n
      \n
    1. The S3 domain is associated with your ShortPixel account:<\/li>\n<\/ol>\n\n\n\n
      bucket-name.s3.region.amazonaws.com<\/pre>\n\n\n\n
        \n
      1. The ShortPixel CDN URL includes the full original image URL after the parameters.<\/li>\n<\/ol>\n\n\n\n
        \n\n\n\n
        The domain is already associated, but it still does not work<\/h3>\n\n\n\n
        Make sure you associated the exact domain used in the image URL.<\/p>\n\n\n\n
        For example, if your image is loaded from:<\/p>\n\n\n\n
        https:\/\/eblocks-dev.s3.ap-northeast-1.amazonaws.com\/properties\/image.jpg<\/pre>\n\n\n\n
        then the associated domain should be:<\/p>\n\n\n\n
        eblocks-dev.s3.ap-northeast-1.amazonaws.com<\/pre>\n\n\n\n
        Associating only your website domain, beta domain, or staging domain will not be enough if the images are served directly from Amazon S3.<\/p>\n","protected":false},"excerpt":{"rendered":"
        ShortPixel\u2019s 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 […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","template":"","meta":{"footnotes":""},"doc_category":[61],"glossaries":[],"doc_tag":[],"class_list":["post-2893","docs","type-docs","status-publish","hentry","doc_category-tools-developer-api"],"blocksy_meta":[],"year_month":"2026-05","word_count":543,"total_views":"9","reactions":{"happy":"0","normal":"0","sad":"0"},"author_info":{"name":"admin","author_nicename":"admin_mdli53m5","author_url":"https:\/\/kb.shortpixel.com\/author\/admin_mdli53m5\/"},"doc_category_info":[{"term_name":"Tools & Developer API","term_url":"https:\/\/kb.shortpixel.com\/knowledge-base\/category\/tools-developer-api\/"}],"doc_tag_info":[],"knowledge_base_info":[],"knowledge_base_slug":[],"_links":{"self":[{"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/docs\/2893","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/types\/docs"}],"author":[{"embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/comments?post=2893"}],"version-history":[{"count":2,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/docs\/2893\/revisions"}],"predecessor-version":[{"id":2895,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/docs\/2893\/revisions\/2895"}],"wp:attachment":[{"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/media?parent=2893"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/doc_category?post=2893"},{"taxonomy":"glossaries","embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/glossaries?post=2893"},{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/doc_tag?post=2893"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}