URL API implementation

Direct implementation using the Cloudimage URL API

If your Web application does not use a CMS (Wordpress, Drupal, ...), e-commerce platform (Prestashop, Magento, ...), or development framework (React, Angular, Django, ...), then you need to adapt your image URLs in your HTML <img> tags.

Basic usage

For example, if your origin image is available at the following URL::

http://sample.li/flat.jpg

Then you need to adapt it to be:

//token.cloudimg.io/http://sample.li/flat.jpg?operations&filters&watermarks

Where:

• token: your Cloudimage token you obtain after registering for a Cloudimage account;

• operations: the resizing operation(s) as listed under Image operations;

• filters: the filter transformation(s) as listed under Image filters;

• watermarks: any image or text overlay(s) as listed under Image watermarking.

In your code, this URL can be used as a normal image in your <img> elements:

<img src="https://token.cloudimg.io/http://sample.li/flat.jpg?operations&filters&watermarks" />

If you have implemented responsive design with the HTML <picture> and <srcset> elements, then you need to change every <srcset>:

<picture>
  <source media="(min-width: 650px)" srcset="/sample.li/flat.jpg">
  <source media="(min-width: 465px)" srcset="/sample.li/flat.jpg">
  <img src="img_orange_flowers.jpg" alt="Flowers" style="width:auto;">
</picture>

Becomes:

<picture>
  <source media="(min-width: 650px)" srcset="token.cloudimg.io/sample.li/flat.jpg?operations1&filters">
  <source media="(min-width: 465px)" srcset="token.cloudimg.io/sample.li/flat.jpg?operations2&filters">
  <img src="img_orange_flowers.jpg" alt="Flowers" style="width:auto;">
</picture>

You need to define the image size with operations1 and operations2 to deliver the lightest possible image. If you want Cloudimage to do the job for you and define the optimal size based on your container width, then look at our JS lib, React, and Angular plugins.

Url-encoding resource URL

ci_url_encoded=1

If a resource is versioned or dynamically generated using query strings, or the filename contains unsupported or reserved characters, you will need to url-encode the URL of the resource. In this case, you need to add the ci_url_encoded=1 parameter to the Cloudimage URL.

For example, in the origin below, the ?w=22 query string is part of the static resource (origin image):

//sample.li/gen.php?w=22

To construct a Cloudimage URL from it, the resource is URL-encoded and the width operation can be now used correctly:

//doc.cloudimg.io/sample.li%2Fgen.php%3Fw%3D22?w=400&ci_url_encoded=1

Spaces in the filename

When using ci_url_encoded=1 to encode URLs with space in the filename, please consider the example: Image: https://freeaccessdemo.blob.core.windows.net/myfiles/Image with space in the name.jpg

Need to be encoded according to RFC-3986 (percent-encoding):

nonehttps://freeaccessdemo.blob.core.windows.net/myfiles/Image%20with%20space%20in%20the%20name.jpg

And if for example, we have extra values added to the origin resource like v=13, the final Cloudimage URL will look like this:

nonehttp://doc.cloudimg.io/https%3A%2F%2Ffreeaccessdemo.blob.core.windows.net%2Fmyfiles%2FImage%2520with%2520space%2520in%2520the%2520name.jpg%3Fv%3D13?w=600&ci_url_encoded=1

The following approach can be used in this case:

encodeURIComponent( path ).replace( /%20/g, '%2520' )