Adaptive Images API

Our Adaptive Images plugin's API can be used directly and integrated into any website, regardless of the technology used. There is also a JavaScript Adaptive Images library available, that you may want to consider.

API URL sections:

1. The CDN URL: https://cdn.shortpixel.ai/
   • both http and https protocols can be used
   • cdn.shortpixel.ai means our CDN is used. Any other CDN can be used if you point to http://no-cdn.shortpixel.ai. If you use a different CDN then image optimization credits will be used.
   
   
2. Client section: /client/
   • any alphanumeric string can be used
   • this string is used as a caching key so these URLs are considered different:
     https://cdn.shortpixel.ai/client/w_300,q_lossy,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg
https://cdn.shortpixel.ai/other-client/w_300,q_lossy,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg
   
   
3. Parameters: /w_300,q_lossy,ret_wait/
   The image is optimized, converted, etc, based on these parameters. The parameters can be separated by comma (,) like you see in the examples on this page or by plus (+): /w_300+q_lossy+ret_wait/. All the possible parameters are explained in detail below.
   
   
4. The original URL: https://shortpixel.com/img/tests/beautiful-woman.jpg
   • The URL needs to be absolute and to point to an image, PDF, CSS or JS file
   • both http and https protocols can be used
   • in case http(s) is missing then https will be assumed

Parameters in detail

• w - Width in pixels, it can be specified or left blank. If only width is specified, the image will keep the original ratio, adjusting the height accordingly.
  Example: https://cdn.shortpixel.ai/client/w_300,q_lossy,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg


• h - Height in pixels, it can be specified or left blank. If only height is specified, the image will keep the original ratio, adjusting the width accordingly.
  Example: https://cdn.shortpixel.ai/client/h_300,q_lossy,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg


• c - Crop style, useful when both width and height are specified. Available options: top, right, bottom, left, center. The default is "smart" cropping which means the cropping is performed taking into account each picture's "subject".
  Examples:
  https://cdn.shortpixel.ai/client/w_300,h_300,c_bottom,q_lossy,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg
  https://cdn.shortpixel.ai/client/w_300,h_300,q_lossy,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg


• sc - Special crop. In the example below, 700x1000 is the offset from the upper left corner of the image, and 2400x1000 is the width & height of the section that is cropped. 480x200 is optional and it returns a resized image with a width of 480px and a height of 200px. Please note that the resizing isn't done at scale, which means that images can be "squeezed" as in the third example (400x100).
  Examples:
  https://cdn.shortpixel.ai/client/sc_700x1000:2400x1000,q_lossy,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg
  https://cdn.shortpixel.ai/client/sc_700x1000:2400x1000:480x200,q_lossy,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg
  https://cdn.shortpixel.ai/client/sc_700x1000:2400x1000:400x100,q_lossy,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg


• q - Quality setting. It can be lqip, lossless, glossy or lossy. lqip returns a low quality SVG placeholder.
  Examples:
  https://cdn.shortpixel.ai/client/w_300,h_300,q_lossless,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg
  https://cdn.shortpixel.ai/client/w_300,h_300,q_glossy,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg
  https://cdn.shortpixel.ai/client/w_300,h_300, q_lossy,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg
  https://cdn.shortpixel.ai/client/w_300,h_300,q_lqip,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg


• to - Conversion setting. It supports WebP, AVIF and auto. It converts the image to WebP, to AVIF and to both WebP and AVIF. If the original image is an animated GIF, then the converted file can be an animated WebP or MP4.
  Important: the image is returned in WebP or AVIF format only if the browser supports that image format. If it doesn't, then the original image format is automatically returned.
  to_auto returns an AVIF image if the browser supports it. If not, it returns a WebP image if the browser supports it. If the visitor's browser supports neither, then the image is returned in its original format.
  Examples:
  https://cdn.shortpixel.ai/client/to_webp,w_300,h_300,q_lossless,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg
  https://cdn.shortpixel.ai/client/to_avif,w_300,h_300,q_lossless,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg
  https://cdn.shortpixel.ai/client/to_webp,q_glossy,h_110,w_250,ret_wait/https://shortpixel.com/img/tests/fox.gif
  https://cdn.shortpixel.ai/client/to_avif,q_glossy,h_110,w_250,ret_wait/https://shortpixel.com/img/tests/fox.gif
  Note: The generation of AVIF images takes more time than other formats as it is a more CPU intensive process.


• ex - It can be 0 or 1; EXIF data is kept (1) or not (0).
  Example:
  https://cdn.shortpixel.ai/client/ex_0,w_300,h_300,q_lossless,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg


• ret - Possible values are blank, img, wait. The value blank immediately returns a blank placeholder and img redirects to the original image while the image is being processed. Once the image is processed the new image is displayed. When wait it used, the image waits to be displayed until the new processed image is ready.
  Examples:
  https://cdn.shortpixel.ai/client/w_300,h_300,q_lossless,ret_blank/https://shortpixel.com/img/tests/beautiful-woman.jpg
  https://cdn.shortpixel.ai/client/w_300,h_300,q_lossless,ret_img/https://shortpixel.com/img/tests/beautiful-woman.jpg
  https://cdn.shortpixel.ai/client/w_300,h_300,q_lossless,ret_wait/https://shortpixel.com/img/tests/beautiful-woman.jpg


• You can also minimize and serve CDN-hosted, minimized versions of your CSS or JS files. Ret is the only parameter used here, and it's recommended to have the value img as in the examples below:
  https://cdn.shortpixel.ai/client/ret_img/http://shortpixel.com/img/tests/test.css
  https://cdn.shortpixel.ai/client/ret_img/http://shortpixel.com/img/tests/test.js