Upload presets

Upload presets enable you to centrally define a set of asset upload options instead of specifying them in each upload call. You can define multiple upload presets and apply different presets in different upload scenarios.

You can set your presets as signed or unsigned. Unsigned presets can be used with unsigned upload calls, such as uploading directly from the browser, in the upload widget or for Auto Upload settings.

Use cases

Some use-cases for using upload presets include:

  • Generating eager transformations for uploaded files. This is especially valuable for video transformations that may take longer to generate and helps to ensure your uploaded files will be ready for delivery.
  • Applying incoming transformations while uploading a file, for example to limit format types or file size before storing uploaded files in your Cloudinary account.
  • Pre-defining eager transformations that should be prepared for all assets uploaded with a particular preset, so they are ready for fast delivery.
  • Applying add-on capabilities, such as auto-tagging or automatic moderation, to your uploads.
  • Managing the behavior of user-generated content uploads without modifying the website or mobile app code.
  • Setting up default upload behavior for uploads via the Media Library or via Upload commands.
  • As upload preferences for uploads via the Upload widget.

Creating and managing upload presets

You can create, modify, or delete upload presets using the Upload Preset UI in the Management Console or programmatically using the upload_presets method of the Admin API.

Note
When defining an upload preset that may be used for both image and video uploads, you can include both image-specific and video-specific upload options (e.g., for moderation or tagging add-ons) and only the relevant options will be used when a file is uploaded with that preset. Any upload options in your preset that apply to a different format are silently ignored. However, if you also supply incoming or eager transformations as part of an upload call, make sure that all the transformation parameters included in the call are relevant for both images and videos.

Managing upload presets using the settings UI

To create or modify an upload preset using the Upload Preset UI, log into the Management Console and select Settings > Upload and then scroll to the Upload presets section.

  • Create a new upload preset by clicking Add upload preset at the bottom of the upload preset list.
  • Click Edit to modify an existing preset.
  • To base a new upload preset on an existing one, click Duplicate on the relevant upload preset. The new copy is added to the bottom of the list with a random name. You can then click Edit on the newly created upload preset to modify its name and update the settings as needed.

Upload preset console UI

The upload preset page includes several sections where you can set a variety of upload options.

  • The most important thing to consider when creating a new upload preset is whether you want the upload preset to be signed or unsigned. For example, only signed presets can be used as the default upload preset for the Upload API or Media Library or if you are implementing signed uploads for your application. Conversly, in most cases, you will need to use unsigned upload presets when implementing unsigned upload capabilities from your client-side app or when using the upload widget within a client-side app.

  • In general, the options in the Upload Preset interface parallel the parameters you can set in an Upload API command. However, there are some options that may be available only programmatically. Those that are unavailable usually relate to specific sub-options of some of the add-ons or those related to complex transformation options, which might be relevant if you are defining eager or incoming transformations for your upload preset.

When you finish and Save your upload preset definition, the upload preset and its settings are displayed in the Upload Settings page:

Upload preset definition

Upload preset video tutorial

This video walks you through the steps of registering for several automatic tagging and image analysis add-ons, and then creating an upload preset in the Management console that applies these add-ons, so that you can automatically tag and analyze every image that is uploaded using that preset.

Managing upload presets programmatically

You can use the upload_preset method of the Admin API to create, manage, or delete upload presets, either via a REST API call, any of our server-side SDKs. If you don't have a server-side application, you can manage upload presets programmatically using the Cloudinary CLI.

For example, the following code creates a new unsigned upload preset called my_preset, requests automatic-tagging using the Google tagging add-on engines for both images and videos, removes the backgrounds for images, and uploads to a folder called new-products:

Ruby:
Copy to clipboard
Cloudinary::Api.create_upload_preset(
  :name => "my_preset",
  :unsigned => true, 
  :categorization => "google_tagging,google_video_tagging",
  :auto_tagging => 0.75,
  :background_removal => "cloudinary_ai",  
  :folder => "new-products")
PHP:
Copy to clipboard
$api->create_upload_preset(
  array(
    "name" => "my_preset", 
    "unsigned" => true, 
    "categorization" => "google_tagging,google_video_tagging",
    "auto_tagging" => 0.75,
    "background_removal" => "cloudinary_ai",  
    "folder" => "new-products"));
Python:
Copy to clipboard
cloudinary.api.create_upload_preset(
  name = "my_preset",
  unsigned = True, 
  categorization = "google_tagging,google_video_tagging",
  auto_tagging = 0.75,
  background_removal = "cloudinary_ai",  
  folder = "new-products")
Node.js:
Copy to clipboard
cloudinary.v2.api.create_upload_preset(
  { name: "my_preset", 
    unsigned: true, 
    categorization: "google_tagging,google_video_tagging",
    auto_tagging: 0.75,
    background_removal: "cloudinary_ai",  
    folder: "new-products" },
  function(error, result){console.log(result);});
Java:
Copy to clipboard
api.createUploadPreset(
  ObjectUtils.asMap(
    "name", "my_preset",
    "unsigned", true, 
    "categorization", "google_tagging,google_video_tagging",
    "auto_tagging", 0.75,
    "background_removal", "cloudinary_ai",  
    "folder", "new-products"));
.Net:
Copy to clipboard
var uploadPresetParams = new UploadPresetParams(){
  Name = "my_preset",
  Unsigned = true,
  Categorization = "google_tagging,google_video_tagging",
  AutoTagging = 0.75,
  BackgroundRemoval = "cloudinary_ai",  
  Folder = "new-products"};
cloudinary.CreateUploadPreset(uploadPresetParams);
cURL:
Copy to clipboard
curl \
  -d "name=my_preset&unsigned=true&tags=remote&allowed_formats=jpg,png" \
  -X POST \
  https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<cloud_name>/upload_presets
CLI:
Copy to clipboard
cld admin create_upload_preset name="my_preset" unsigned="true" categorization="google_tagging,google_video_tagging" auto_tagging=0.75 background_removal="cloudinary_ai" folder="new-products"

You can similarly use the Admin API to list, modify or delete existing upload presets. For complete details, see the upload_preset method in the Admin API Reference.

Default upload presets

From the Upload settings, you can also individually select signed upload presets that will act as the Default upload presets for images, videos, and raw files respectively. You can select one set of presets for API calls and another set for uploads via the Media Library. The settings in these default presets are applied to all uploads of the relevant asset type whenever no other upload preset is specified directly in an upload call or via the upload widget in the Media Library.

Default upload preset settings

Tip
The default Media Library presets apply to any assets that are dragged to a folder in your Media Library. They are also used by default when you select files from any source via the built-in Upload Widget in the Media Library. However, if enabled for your account, then you can select a different signed upload preset for selected files in the Advanced options of the Media Library Upload Widget. For details, see Media Library Upload Widget.

✔️ Feedback sent!

Rate this page: