Images API

URL Values

Some parameters like watermark, compose or shape expect a URL value to work as expected.

URL values are specified as a string that identify the image with optional parameters to be applied.

URL values must be URL encoded to avoid problems with URL reserved characters. This is only needed in the case that you are specifying URLs manually, if you are using one of our integration libraries the encoding will be done automatically.

Images from the same source

If both the base image and the image you want to use as a parameter belongs to the same source you can simply write the name of the image as value.

Let's take the following example. You want to render an image named flowers.jpeg that belongs to source with name assets and you want to set width size of the image to be 600 pixels, that image can be rendered with the following URL:


Let's imagine that you want to add a watermark named forest.jpeg that belongs to the same assets source that the base image. You can do that adding watermark=forest.jpeg to the parameters of the previous URL:


So in this case is not necessary to specify a full URL for the watermark parameter because both images belongs to the same source.

The previous URL is equivalent to the following one (using a full URL value for watermark):


Remember that URL values needs to be URL encoded to avoid problems with URLs reserved characters.

Images from different sources

If both base image and the image that you want to use as parameter belongs to different sources it's necessary to write a full URL value.

Let's consider that we need to render a base image named flowers.jpeg from source assets with a width size of 600 pixels, the following URL is required:


If we want to apply a watermark image named star.jpeg that belongs to source masks we need to add the following watermark parameter to the base URL:


After URL encoding the parameter we will have:


And finally add that watermark parameter to the base URL:


Applying parameters to URL values

Apply parameters to change the image specified in a URL value can be done in the same way that it's done with base images.

Let's take as example that you want to compose an image over the base one, both of them belongs to the same source. You want to set an specific size of 500x600 pixels. In order to do that you can use the following parameter:


We need to URL encode the parameter so the value will be:


With that we only need to add it to the base URL:


The same can be applied to full URL values for images from different sources.