Content Delivery Network
On this page
Every uploaded file is immediately available on the Uploadcare CDN.
CDN is a geographically distributed system of servers that delivers content to client devices from the servers nearby, which saves time on long-distance data exchange. Uploadcare uses Akamai CDN and a proprietary CDN layer for better performance and reliability.
In addition to faster page load and a better uptime in case some servers become inaccessable, Uploadcare CDN features on-the-fly image processing features and can work as a proxy.
CDN operations
Access files in Uploadcare CDN at ucarecdn.com
over HTTP/HTTPS liks this:
https://ucarecdn.com/:uuid/
You can add CDN operations by including directives in the CDN URL:
https://ucarecdn.com/:uuid/-/:operation/:params/:filename
:uuid
stands for the unique file identifier, UUID, assigned on upload./-/
is a mandatory parsing delimiter to divide operations and other path components.:operation/:params/
is a CDN operation directive with parameters.:filename
is an optional filename you can add after a trailing slash/
.
You can stack two and more operations like this:
-/:operation/:params/-/:operation/:params/
Filenames
Your original filenames can be accessed via REST API.
Make a 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
.
Here are some examples with full CDN URLs:
Safe:
// adding a simple filename
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/image.jpg
// using a char allowed in the pchar definition
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/image@2x.jpg
// allowed in pchar together with Image Transformations
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/resize/550x/image@1x.jpg
// using a sub-delim allowed in pchar together with Image Transformations
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/grayscale/image_black&white@2x.jpg
// using percent-encoded gen-delims that are not allowed in pchar
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/grayscale/image%5Bdesaturated%5D@2x.jpg
html
Unsafe:
// using gen-delims that are not allowed in pchar without encoding
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/grayscale/image[desaturated]@2x.jpg
html
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.
Group API
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
:
: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.
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 supportzip
andtar
.: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
Show or download images
-/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.
/:uuid/-/preview/-/inline/no/
/:uuid/-/inline/yes/
Search engine indexing
Uploadcare adds response headers that tell search engines not to index the content of files in your project to increase the privacy of your and your user's data. You can toggle this behavior separately for each project in Dashboard in Delivery configure page.
File indexing by search engines is disabled by default.
Custom CDN CNAME
Use your own domain for CDN links to your files stored with Uploadcare.
By default, all file URLs use ucarecdn.com
domain. By setting a Custom
CDN CNAME, the file URLs can use cdn.mycompany.com
instead.
Depending on your plan, you can connect Uploadcare CDN to your domain or subdomain with a Let's Encrypt SSL certificate. Enterprise plans let you choose any CDN you prefer.
Pick a domain name you want to use (e.g., cdn.mycompany.com
),
contact us and let us know about your choice.
We'll tell you the domain name your CNAME should point to, e.g.
mycompany.ucarecdn.com
.
Add a CNAME record to your DNS zone, e.g.:
cdn.mycompany.com CNAME mycompany.ucarecdn.com
We'll issue an SSL certificate on our end, so you don't need to provide your one. Then we'll set things up on our side. It usually takes 1-2 business days. Once everything is set up, and DNS changes propagate, you will need to use new URLs with your domain name.
Configure your widgets to return proper URLs, e.g.:
UPLOADCARE_CDN_BASE = "https://cdn.mydomain.com";
html
Replace hostname in URLs of already uploaded files served by your app. We recommend having an easily configurable setting over the hard-coding hostname of your URLs.
Bring your CDN
If you depend on a specific CDN infrastructure or are under contract, you can use your current CDN with our platform. Schedule demo with us.