Auto-Upload and Fetch are two options for automatically fetching (retrieving) files from existing remote locations and delivering them using dynamic URLs. In both cases, the files are delivered through a powerful CDN network, greatly improving your users’ browsing experience, reducing load on your servers and lowering hosting costs, while you also benefit from on-the-fly image transformation and optimization, and all of this with minimum changes on your side.
The main difference between these two features is how the remote image is handled:
Fetch enables on-the-fly transformation of remote images and optimized delivery via a CDN. Fetched images are cached on your Cloudinary account for performance reasons. Paid Cloudinary customers can request to have the remote images checked on a regular basis (every 7 days by default) and if the remote image has changed, the cached image is updated accordingly. This feature supports only image assets.
Auto-Upload also enables on-the-fly transformation of existing remote assets with optimized delivery via a CDN, while simultaneously uploading the fetched media asset to your Cloudinary account for further management, and thus benefiting from a variety of additional features (just like any other asset uploaded to your Cloudinary account). After an asset has been auto-uploaded from the remote location, all requests for the asset will reference the asset stored in your Cloudinary account. This feature supports all assets: image, video and raw.
The following table summarizes how these differences can impact different elements of the media management process:
Managed by Cloudinary just like any other uploaded asset (thus benefiting from additional features).
Managed on your side and just transformed and delivered by Cloudinary
Supports any asset type; just make sure the resource_type value matches the type of asset you are retrieving.
Supports images only
You can use eager transformations to create multiple versions of the same asset during auto-upload rather than on-the-fly. This is especially valuable for transforming videos, large image files, and complex transformations (e.g. transforming animated GIFs).
You can use upload presets to automatically apply actions to all images uploaded to a specific auto-upload mapped folder by creating an upload preset with the same name as an auto-upload mapped folder. This enables you to eagerly create derived/transformed assets, request notifications, apply tagging, moderation and more.
SEO-friendly short URLs
Auto-uploaded URLs do not contain the lengthy URL of the original file.
The fetch feature is a quick way to deliver images from remote URLs. The image can be transformed and optimized on-the-fly, before being cached and delivered through fast, localized CDNs and not via local web servers. To create a fetch URL, simply prepend the following prefix to the URL of the image:
Both URLs return the exact same image, only the second one is cached and delivered through fast, localized CDNs and not via the local web server.
Although you can technically also use the fetch delivery type to deliver profile pictures from various social media applications like Facebook, Twitter and others, you can accomplish this task more easily using specially defined social media delivery types along with the profile picture ID or name to accomplish this. For details, see Social media profile pictures.
You can also use the fetch feature to apply any of Cloudinary’s image transformations to the delivered image. Simply add the transformation parameters to the URL directly after the fetch prefix and before the URL of the image.
For example, the following Cloudinary URL delivers an image of Benedict Cumberbatch from Wikipedia that has been transformed as follows: the width and height parameters are both set to 300 pixels, the image is cropped to fill in the new dimensions, retaining the original proportions and setting gravity to the detected face; the image is also made circular by setting the radius parameter to maximum, and finally, depending on the browser/device, the best image format is automatically delivered, optimized and cached via CDN:
If the image referenced by the original URL changes, Cloudinary will not automatically update the fetched image embedded in your site and all its transformed versions. For details, see Refreshing or deleting fetched images.
Cloudinary’s SDKs make it easy to build URLs and include methods for creating generic HTML image tags. To use the fetch feature via code, set the delivery type (type) parameter of the image tag method to fetch. For example, the following code snippet creates an image tag to the same transformed image as shown above:
URLs containing special characters (particularly the ? character) need to be modified (or escaped) for use with the fetch feature. This is relevant for any special characters that are not allowed “as is” in a valid URL path, as well as other special unicode characters. These URLs should be escaped using % based URL encoding to ensure the URL is valid. Either escape the individual special characters themselves within the URL (for example, replacing ? with %3F) or escape the whole URL.
Note that the methods within Cloudinary’s client libraries (e.g. the Ruby on Rails cl_image_tag method) automatically perform smart escaping, leaving the URL as simple as possible while escaping certain special characters. Manually escaping URLs as explained here is only relevant when simply adding the fetch prefix to existing URLs.
You can restrict the list of allowed domains that can be used with the fetch feature in the Allowed fetch domains section on the Security tab of the Settings page in Cloudinary's Management Console.
You can disable fetching by ticking the Fetched URL box in the Restricted media types section of the Security tab. This is also done automatically if fetch is not used within 7 days of account creation, in order to prevent abuse of the system for customers not using the functionality.
When you fetch a remote image, a copy of that image as well as all transformations derived from the remote image, are cached on your Cloudinary account for performance reasons.
By default, Cloudinary checks one time after 7 days to see whether the remote image has changed (by comparing the etag value). If it has changed, the cached image is replaced with the new one, and the next time that image, or a transformation of that image, is requested, the updated version is delivered.
Cloudinary customers with a paid account can request to change this default from a single 7-day refresh to any desired repeating interval.
Additionally, paid customers can request a separate time interval setting for full cleanups of all fetched images. When a cleanup interval is defined, all of your fetched images are completely deleted every X days. If one of these images is requested again after the cleanup, it is fetched again from the remote source. This option is useful for cleaning up your storage in cases where many of your fetched images become obsolete after a short time period, for example, banner ads.
You can request to set a custom fetch refresh interval and/or cleanup interval by submitting a support request.
When your refresh interval gets updated, that setting is applied only to assets fetched after the setting change.
If you need to apply the new setting to fetched assets that have already been delivered, you'll need to delete the relevant fetched assets from your account. Then, the next time any of those fetched assets is requested, it will be re-fetched and the new refresh interval settings will be applied to it.
The auto-upload feature combines the advantages of dynamic fetching from existing online locations, with the advantages of managing media assets directly in your account (listing, editing, browsing, tagging, transforming, moderating, dynamically transforming, viewing reports, and more) via the Cloudinary Management Console. The auto-upload feature enables on-the-fly transformation of existing remote media assets and optimized delivery via a CDN, while automatically uploading the file to your Cloudinary account for further management and transformation.
The auto-upload feature is implemented by mapping a base remote URL to a specified folder in your Cloudinary account. Then, whenever accessing a Cloudinary delivery URL containing the folder prefix, the media assets are automatically retrieved from the mapped URL if they are not already uploaded to the folder, and are available for further transformation, management and CDN delivery like any other asset uploaded to Cloudinary.
Mapping a remote URL prefix also allows your Cloudinary delivery URLs to be shorter and more SEO friendly, gives you fine-grained control on which remote domains are allowed for automatic uploads, enables lazy migration of all your existing assets to the cloud as well as other powerful origin pulling options. After an asset has been auto-uploaded from the remote location, all requests for the asset will reference the asset stored in your Cloudinary account.
The standard auto-upload URL takes the following structure:
For example: Creating a folder called remote_media and then mapping it to the URL prefix https://upload.wikimedia.org/wikipedia/ allows you to generate a Cloudinary delivery URL that substitutes the remote_media folder prefix for the URL prefix. When the Cloudinary delivery URL is accessed for the first time, Cloudinary automatically retrieves the remote asset from https://upload.wikimedia.org/wikipedia/ and stores it in your Cloudinary account.
To retrieve the following Olympic flag image from Wikimedia commons, and automatically upload it to your Cloudinary account:
The auto-upload feature is configured in the auto-upload mapping section on the Upload tab of the Settings page in Cloudinary's Management Console as follows:
Fill in the Folder name or path for the auto-upload mapping e.g. remote_media/remote_assets. The folder path can be up to 3 folders deep.
Fill in a URL prefix that will be mapped to the specified folder e.g. https://upload.wikimedia.org/wikipedia/ or s3://my-bucket/my-path/
To use a private storage (Amazon S3 or Google Storage) bucket as the remote URL prefix, you must makesure your bucket is whitelisted for your Cloudinary account. This is especially useful for lazy migration.
Click the Save button at the bottom of the page.
Once saved, any media stored under the directory you set as the URL prefix and requested by a Cloudinary URL that contains the remote_media folder in the Public ID, will automatically be retrieved and stored in your Cloudinary account. This asset is treated just like any other asset that was uploaded to your Cloudinary account.
Notes and guidelines for auto-uploading
You can map multiple folder names, each to a different remote URL prefix, by clicking the Add another mapping link in the Auto-upload mapping settings.
Instead of specifying an account sub-folder, you can optionally map your root Cloudinary folder to a URL prefix by filling in a backslash for the folder name (/).
You can also use the auto-upload feature to apply any of Cloudinary’s image or video transformations on-the-fly to the delivered media asset. Simply add the transformation parameters to the URL directly before the mapped folder name.
For example, the following Cloudinary delivery URL retrieves an image from Wikimedia and stores it in Cloudinary’s demo account, then crops a thumbnail of the original image to a width of 200 pixels and a height of 200 pixels, centers the image on the detected face, makes it circular, applies a sharpen effect - and then delivers that modified image optimized and cached via CDN:
Auto-uploading from within your code can be easily accomplished using Cloudinary's SDKs for all popular development frameworks. The principle is exactly the same as with any URL/tag building of an uploaded asset, except in this case the public ID does not have to match an existing asset, but can match a mapped folder name of a remote existing asset that will be implicitly fetched on first access. For example, the following code snippet retrieves the same transformed image as shown above:
Generally, when migrating to Cloudinary, customers upload all their media files via Cloudinary's upload API and then update their web or mobile app to upload new files to Cloudinary.
The auto-upload feature offers a powerful alternative method to migrate media files within your own existing web application to your Cloudinary account, by dynamically uploading them only when first accessed rather than pre-uploading them. This “lazy migration” is especially useful if your site has lots of media assets, some of which may be very rarely (or never) accessed.
Auto-uploaded URLs share the exact same URL convention as Cloudinary’s regular uploaded asset URLs, which means that for each asset accessed, Cloudinary first checks whether a asset with the given public ID exists in your Cloudinary account, and if it doesn't (and it matches a given auto-upload folder mapping), it is retrieved on-the-fly from the remote host.
The auto-upload examples given so far allow public access to the original asset as well as all its derived versions. As an alternative, you can control access to auto-uploaded remote assets by defining them as delivery type private or authenticated, and including the sign_url parameter set to true (required for authenticated assets).
For example, to auto-upload an image as authenticated, set the delivery type (type parameter) as authenticated and include a signature in the delivery URL. (In SDKs, set the sign_url parameter as true.) This setting prevents access to the image without an authentication signature:
Besides restricting an asset based on its delivery type, you can also globally control the behavior of the auto-upload feature so that auto-uploaded dynamic URLs require a signature in all cases, even for public assets of type upload:
In the Cloudinary Management Console for your account, access the the Security tab of the Settings page and then check the Uploaded option under the Restricted image types section.
For example, if the auto-upload feature is set as restricted, then the following code snippet allows auto-uploading by signing the URL (In SDKs, set the sign_url parameter to true):
When you use Cloudinary's upload API you can leverage many powerful features (eagerly created derived/transformed assets, notifications on upload, adding tags, contextual and structured metadata, requesting moderation and more). To be able to benefit from the same features together with auto-upload, you can use upload presets for defining the automatic upload actions. Upload presets include one or more upload parameters, and any of Cloudinary's upload parameters can be defined and included in a preset.
To instruct a particular upload mapping to use a particular upload preset, set the name of the upload preset to be the same name as the auto-upload mapped folder.
For example, naming an auto-upload mapped folder as remote_media and also naming an upload preset as remote_media will automatically apply all the actions specified in the upload preset when auto-uploading images to the remote_media folder.
Upload preset names cannot contain slashes. Therefore, this option is supported only for auto-uploads mapped to top-level folders.
You can easily display thumbnail images of videos from various public video sites by referencing the unique video identifier used on their site. The cloudinary image delivery URL for the thumbnail follows the format:
You can also pass the full URL of the video instead of just its identifier. The following example delivers a thumbnail of a YouTube video based on a full video URL (https://www.youtube.com/watch?v=aNwnPElsJGE). Note that if the URL includes special characters, they should be escaped (e.g., '%3F' instead of '?'). If you use our client library helper methods then the escaping is done for you automatically.