CDN or Content Delivery Network is a system of servers deployed in multiple data centers across the world. Such approach provides for faster content delivery. Uploadcare CDN does not simply deliver files, it also provides URL-based API for on-the-fly processing of the uploaded content.
Normally, all requests should be made to
Either HTTP or HTTPS protocol can be used.
While on paid plans, you can connect our CDN to a domain or a subdomain of your own. (Let's Encrypt SSL certificate included). On High volume plans you get an option of using your own CDN on top of our infrastructure.
Please note that all of the file-related URLs should begin with the assigned UUIDs. This link, for instance, returns just the original uploaded file:
You can apply operations (transformations, etc.) by
appending them to the URL and using
/-/ as a separator.
Operations consist of names and arguments, separated by forward slashes (
Here, take a look at the example:
In this example there are two invoked operations:
resize with argument
You can arrange operations in sequences (i.e. "pipe" them). Such sequences also specify the execution order of operations. Please note that you can use any operation several times.
Finally, you can complete the URL with any chunk you wish, make sure not to add a slash in the end! It can be useful if your content editing system checks links for "extensions" or if you want to provide your users with nicer links. It might also be useful in terms of SEO.
It often happens that you need several versions of some image, say of different sizes or with effects applied. There are multiple on-the-fly processing routines in CDN API for that purpose.
Note that even though there are multiple input image formats supported by the CDN (such as
BMP and more), the output format is set to
PNG for images with transparency and
JPEG for others.
CDN supports the following image operations:
Converting an image to one of the following formats:
Setting the level of image quality.
Image quality affects file sizes and hence loading speeds and amounts of generated traffic.
This operation does not affect non-JPEG images
(and is applied without forcing image format to
normal– the default setting, is fine in most cases.
better– can be used to render relatively small and detailed previews. ≈125% file size compared to the normal quality.
best– useful for hi-res images such as photos in case you want to get perfect quality without paying attention to file size. ≈170% file size.
lighter– is especially useful when applied to relatively large images in order to save traffic without significant losses in quality. ≈80% file size.
lightest— useful for retina resolutions, when you don't have to worry about the quality of each individual pixel. ≈50% file size.
Blurry on retina displays.
Still a good fit for all screens.
Perfect for retina.
Returns a progressive image.
In progressive images, data is compressed in multiple passes of progressively higher detail.
This is ideal for large images that will be displayed while downloading over a slow connection,
allowing a reasonable preview after receiving only a portion of the data.
The operation has no effect on non-JPEG images; does not force an image format to
Reduces an image proportionally in order for it to fit into the given dimensions (in pixels).
If dimensions are not specified then the default limits will be used (
Resizes an image to fit into the specified dimensions. If only a single linear dimension is specified, resizing is performed according to the specified size (aspect ratio is preserved).
Crops an image to specified dimensions, with specified offset. If no offset value is passed into the operation, the top-left corner of an image is used.
If given dimensions are greater than the ones of the original image, then the whole image will be rendered inside a color-filled box. The color can be changed using the setfill method.
Scales down an image until one of the dimensions gets equal to the specified one, the rest is cropped. This is really useful when your goal is to fit into a box as much of an image as possible. Let us compare the two resizing methods:
Sets the behavior of the resize operation if a source image is smaller than the specified (resulting) dimensions. The following modes might be used to set the behavior:
on– stretches an image up. Default.
off– forbids stretching of an image along any dimension that exceeds the one of an image in size.
fill– the image isn't stretched, but the color-filled frame is rendered around it (default fill color is used).
Sets the fill color used with
crop or when
converting an image with alpha channel to JPEG.
The operation uses hexadecimal notation to define colors.
Auto-enhances an image by performing the following operations:
auto levels, auto contrast, and saturation sharpening.
:strength parameter values should be in the range from 0 to 100.
The default value is 50.
Original image. 28Kb
Sharpens an image, might be especially useful in case of post-downscale images.
:strength can be in the range from 0 to 20 and defaults to the value of 5.
The downscaled image. 13Kb
Blurs an image by the
:strength factor. The filtering mode is Gaussian Blur,
:strength parameter sets the blur radius — effect intensity
:strength controls the Gaussian Blur standard deviation multiplied by ten).
The value of
:strength might come up to 5000, while the default value is 10.
Please note, that the actual
:strength value does not affect the speed of blur operation.
Original image. 16Kb
Desaturates an image. The operation has no additional parameters and simply produces a grayscale image output when applied.
Inverts an image, rendering a 'negative' of the input image.
The default behavior of our CDN is to parse EXIF tags of the
original images and rotate them accordingly to the value of the "Orientation" tag.
This is what we call autorotation.
/autorotate/no/ allows to turn off the default behavior.
Right-angle image rotation, counterclockwise.
The value of
:angle parameter must be a multiple of 90.
Flips an image.
Mirrors an image.
This operation allows for a superimposement (or layering) of images. One of the most common uses of the operation are watermarks (i.e. semi-transparent images layered over opaque ones in order to complicate their unauthorized usage, etc.).
:uuid— UUID of the overlay image, a unique internal identifier of an image subjected to processing. Please note, that in order to be recognized by
:uuidyour image should be related to your account (any project of your account);
:relative_dimensions— linear dimensions of the overlay image. Please note that the aspect ratio of the overlay image is preserved. Hence, what you set is a maximum linear size along one of the axes (for example,
-/overlay/:uuid/50%x50%/means that any linear dimension of the overlay can not exceed 50% in size). Default size setting is 100%;
:relative_coordinates— position of the overlay over an input image. By default, the overlay is positioned in the top-left corner of an input. Coordinates represent an offset along each of the axes in either pixel or percent format. In general the coordinate system is designed in similarity with CSS background-position;
:opacity— opacity of the overlay in percent format. Please note, that overlay data might be initially semi-transparent or made to be so by tuning the opacity parameter.
% is an escape char in URLs, it can't be used as-is and
should be replaced with either
%25 escape sequence or a
(which is a more readable and concise option).
Moreover, every overlay setting is optional and can be omitted (make sure not to alter the sequence of settings, though)!
An example with specified size and opacity, positioning is omitted.
Here, size and position are specified while opacity setting is omitted.
As you see, multiple overlays can be added to an image,
here's an example where similar overlays are added with varying position.
This set of operations can be applied to both images and other file types. Please note that you can mix the operations from this set with the others (non-image operations should be placed last in a chain).
By default CDN instructs browsers to show images and to download other file types. By using this setting one can change the default behavior.
Returns image-related information (such as image dimensions or geotagging data) in JSON format.
In last case json response will contain
original key with information about
Same as the above, but returns data as
Callback name should always be
It should receive the two following arguments:
id and response object.
For original files,
id is equivalent to the file UUID.
For processed files
id is equivalent to the path excluding last operation (JSONP).
In the first case
id will be
c5b7dd84-c0e2-48ff-babc-d23939f2c6b4, in the second —
This section describes the limitations one should consider using the CDN API.
previewcontrol with no arguments;
Groups are how you can organize files in a project. For instance, a group is created when you select multiple files to upload using our widget. A single file in a group can still be addressed using it's UUID, the same is also working for groups — those can be invoked via a group UUID.
You can request any file in a group by using it's index (zero based):
Please note that there is no
/-/ separator after a group UUID (
/nth/ is not an operation).
Group UUID always includes a number of files within this group,
this way you can iterate through all of the files in a group.
Files stored within a group still have support for all the operations.
If CDN operations have already been applied to a file before it was added to a group — the list of such operations is added to a group together with the file itself. So that if you request the file from a group, it's going to be invoked with all of the stored operations. Hence, adding more controls to such file will result in combining them with the existing ones.
You can customize the layout and behavior of images in a gallery by adding operations to its URL (the workflow is pretty much the same as with files, see Fotorama options, except that we don't support size, width/height and ratio manipulations here).
One of the great applications of the gallery feature might be
embedding a collection of images right into your page via
<iframe src="/:group_uuid/gallery/-/nav/thumbs/-/fit/cover/-/loop/true/-/allowfullscreen/native/-/thumbwidth/100/" width="100%" height="450" allowfullscreen="true" frameborder="0"></iframe>