Content Delivery Network

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.

What a group is

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. Each time you use multi-upload with File Uploader v3, a new group is created. For the new 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.

Learn more about 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 Transformations 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.

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.

Gallery from in-group files

A gallery will display a group of images on a single page. The gallery feature is powered by the Fotorama JavaScript library.

Making a gallery is also based on a group processing operation, gallery. Here’s how it works,

/:group_uuid/gallery/

You can customize the layout and behavior of images in a gallery by adding Fotorama options to their URLs. The workflow is pretty much the same as with Image Transformations except for image size, dimensions, and ratio manipulations.

/:group_uuid/gallery/-/nav/thumbs/-/fit/cover/-/autoplay/1000/

The most common use case with gallery is to embed a collection of images into your page via <iframe>:

<iframe
  src="/:group_uuid/gallery/-/nav/thumbs/-/fit/cover/-/loop/true/-/allowfullscreen/native/-/thumbwidth/100/"
  width="100%"
  height="450"
  allowfullscreen="true"
  frameborder="0">
</iframe>html