On-the-fly CDN operations

Uploadcare CDN features on-the-fly image optimization, a large set of image transformations, and non-image file operations, such as getting file information or changing file delivery behavior.

https://ucarecdn.com/:uuid/

You can find detailed specifications of all CDN operations in the URL API reference.

Image processing operations

Key types of image operations are:

When applying any image operation, a new file is created (cached on our CDN, and not counted towards your storage limits). If not set, this file is encoded with the default quality and original format. However, you can adjust them to meet your requirements better.

Limitations

Image processing operations have limits that you should consider.

Input image formats

List of supported image formats:

  • AVIF
  • BMP
  • GIF
  • HEIC
  • JPEG
  • PCX
  • PNG
  • TGA
  • TIFF
  • WEBP

Some formats have several variations, and we support the most popular ones. If you require additional formats or variations, contact our sales team .

Without any image processing operation in the URL, CDN instructs browsers to show images (Content-Disposition: inline) and download other file types (Content-Disposition: attachment). Browsers may not show all image formats, such as TIFF and HEIC formats. If you need to display an image, add any image processing operation, -/preview/ for instance.

Core operations

When processing images, you must add at least one of the following operations via their respective URL directives:

File size

Image processing operations can be applied to files smaller than 100 MB.

The file size limit can be increased individually. To do this, contact our sales team.

Output image dimensions

The dimensions you specify for the last operation should not exceed 3000x3000 pixels. You can go up to 5000x5000 pixels by explicitly setting your image format to JPEG, /format/jpeg/.

You can extend the output max resolution up to 8192x8192, and up to 16384x16384 for JPEGs in trade-off for increased latency. Contact our sales team to learn more about this option.

SVG files

Any image transformation CDN URL is valid with an SVG file. Most operations don't affect the response SVG body, while geometric operations (crop, preview, resize, scale_crop) change SVG attributes and work as expected. To apply full range of operations on SVG file, it should be rasterized by applying /rasterize/ operation. Read more about SVGs.

SVGs uploaded before May 26, 2021 still have is_image: false and adding processing operations to them will result in error. Contact support to batch process previously uploaded files.

Image resolution

We don’t provide on-the-fly image processing for images greater than 75 Mpx in resolution: those are tagged as non-image files and can only be delivered via CDN as-is. Adding processing operations to non-image files will result in an error.

Simple rotation

When the only image transformation you want is rotating, consider using the preview control without any arguments. When you use any of the transformations, we automatically rotate images according to their EXIF orientation.

Animated images

Animated images are treated as static by the transformations engine. Learn more about animated images optimization.

Show or download

-/inline/yes/ -/inline/no/

By default, CDN instructs browsers to show images and download other file types. The inline control allows you to change this behavior.

Change filename

Your original filenames can be accessed via REST API. Request to receive a JSON response with file parameters including original_filename.

You can set an optional filename that users will see instead of the original name:

https://ucarecdn.com/:uuid/:filename

:filename should comply with file name conventions and it should be a valid part of a URL. For example, filename.ext.

File information

Get file info as JSON

-/json/

Returns file-related information, such as image dimensions or geotagging data in the JSON format.

/:uuid/-/json/
/:uuid/-/preview/-/json/

In the second option, json response will contain the original key with the info on your original image.

Get file info as application/javascript

-/jsonp/

Same as the example above, but it returns data as the application/javascript type. The callback name should always be uploadcare_callback. It should receive the two following arguments: id and a response object. For original files, id is equivalent to their UUIDs. For processed files, id is equivalent to their URLs, excluding the last operation, jsonp.

/:uuid/-/jsonp/
/:uuid/-/preview/-/jsonp/

In the first case id will be c5b7dd84-c0e2-48ff-babc-d23939f2c6b4, in the second: /c5b7dd84-c0e2-48ff-babc-d23939f2c6b4/-/preview/.

Perceptual hash

File info response includes a value of a perceptual hash calculated using pixel contents of an image. Perceptual hashing is a common fingerprinting technique to quickly compare images and find duplicates or similar images.

Uploadcare automatically calculates a 64-bit long perceptual hash value and returns it as a HEX string. In this example, the perceptual hash value is 940f5fd09aa48ddc:

{
  "id": "1b192edb-212d-401a-ad9b-529047272e1b",
  "datetime_original":null,
  "orientation":null,
  "height":1600,
  "width":2400,
  "geo_location":null,
  "format":"JPEG",
  "hash":"940f5fd09aa48ddc"
}

It’s easy to find image duplicates by quickly comparing their perceptual hash values. To find similar images, it's important to compare perceptual hash values bitwise (Hamming distance). A small number of unmatched bits (e.g., up to 8 bits) will correspond to subtle changes in the visual contents, while non-similar images will usually have more than 8 different bits.

File groups operations

Groups are file collections. Use them to organize content in your Uploadcare project. A common use case is to use them in the single content upload or delivery transactions.

For instance, you can create groups when you upload multiple files. For the File Uploader this option is turned off by default. When it's turned on, it stores UUIDs of uploaded files. You can access file collections via :group_uuid:

https://ucarecdn.com/cd334b26-c641-4393-bcce-b5041546430d~11/

:group_uuid is similar to a single file UUID, but it has the file number ~N at the end. A group can contain up to 1000 files.

A group URL will show a list of individual file URLs with their UUIDs, and index numbers in that group.

Check out our API refs for creating and managing groups.

Accessing single files in a group

Request a specific file in a group by adding /nth/i/, where i is a file index, starting from 0:

/:group_uuid/nth/0/
/:group_uuid/nth/1/
/:group_uuid/nth/2/

Note, there is no /-/ separator after a group UUID. It's required for transformations only.

By the way, you can apply image processing operations to indivitual files within a group:

/:group_uuid/nth/0/-/resize/256x/

You can also group the processed files with the respective operation sequences. When you request a file by its group URL, it'll include all operations before adding it to that group. Adding more operations after /-/ will apply them over the existing ones.

Get a group as an archive

Getting a group as an archive is done via the archive group processing operation.

The operation limits are:

  • A total size of uncompressed files ≤ 2 GB.
  • Processing operations will be discarded. Only original files will be archived. Note: If you add an image with a transformation to a group, then only the original images will be loaded when exporting the archive of this group. At the same time, the image with the transformation is saved if you request the group element from the CDN (/nth/N/) directly.

Here's how to get an archived file group:

/:group_uuid/archive/:format/:filename
  • :group_uuid — UUID of a file group you want to get as an archive.
  • :format — the format of that output archive, we support zip and tar.
  • :filename (optional) — output archive filename.

Note: If the group contains a removed file, the archive operation will fail with a 404 error code.