Managing upload presets for developers

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:

• Define how the assets will be stored and accessed, such as the way the public ID value will be determined (use_filename), which folders they'll be stored in (asset_folder), and whether existing assets can be replaced by those uploaded with the preset (overwrite).
• Generate eager transformations for uploaded files (eager). 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.
• Apply incoming transformations while uploading a file (transformation), for example to limit format types or file size before storing uploaded files in Cloudinary.
• Apply add-on capabilities, such as auto-tagging (categorization) or automatic moderation (moderation), to your uploads.
• Update the behavior of user-generated content uploads without modifying your website or mobile app code.
• Set up default upload behavior for uploads via the Media Library or via upload method commands.
• Use 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 tab in the Upload page of the Console Settings or programmatically using the upload_presets method of the Admin API.

Managing upload presets using the settings UI

To create or modify an upload preset using the Upload Preset UI, navigate to the Upload Presets page of the Console Settings.

• To create a new upload preset, click Add Upload Preset.
• To modify an existing preset, select Edit from the preset's (3-dots) option menu.
• To base a new upload preset on an existing one, select Duplicate from the (3-dots) option menu for the desired upload preset. The duplicate will appear at the top of the list with a random name. You can then select Edit to rename it and adjust the settings as needed.

  

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. Conversely, 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 method 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.

• The options relating to asset naming and folders differ depending on whether your product environment uses dynamic or fixed folder mode. For more information, see Naming, storage and folder mode options.

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

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 backend SDKs. If you don't have a server-side application, you can manage upload presets programmatically using the Cloudinary CLI. For the most part, you can apply the same set of options for an upload preset as you can in an Upload method call.

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:

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.

Upload preset video tutorial

This video tutorial walks you through the steps of creating signed upload presets using the Admin API.

Tutorial contents

Naming, storage, and folder mode options

You may want to pay special attention to the following options that impact how your assets are named and stored. Some of these options differ between dynamic and fixed folder mode.

Set them either from the settings UI, or programmatically using the upload_presets endpoint of the Admin API. You can find the specific parameters that implement these options in the Upload method call.

Upload preset precedence

When you use both an upload preset and pass request parameters directly in the same upload call, Cloudinary follows these precedence rules if you include the same parameter in both:

Signed uploads

For signed uploads, all parameters provided directly in the upload request take precedence over the same parameters defined in the upload preset, except eager and incoming transformation parameters, where Cloudinary merges the values (applies the values from both the preset and the request).

Unsigned uploads

Unsigned uploads support a limited set of parameters passed directly in the request.

When you include one of the supported parameters in both the unsigned upload preset and in the unsigned upload request, the parameter in the preset takes precedence, except:

• Merged parameters (applies values from both preset and request): context, metadata
• Request takes precedence: filename_override, public_id (unless disallow_public_id is true in the preset)

Best practices for upload presets

When configuring upload presets consider these best practices to optimize performance and avoid common issues:

Eager and incoming transformations

Avoid using the same transformation in both incoming and eager transformations

Choose one approach based on your use case. Using the same transformation in both incoming and eager can lead to unexpected results or redundant processing.

Don't use f_auto - use specific formats instead

The f_auto parameter works by detecting the requesting browser at delivery time to serve the optimal format. Since there is no requesting browser during upload, f_auto is meaningless in both eager and incoming transformation contexts.

For eager transformations, explicitly specify the exact format(s) you need to pre-generate. This applies to both images and videos. When configuring video eager transformations, eagerly generate the specific format and codec combinations you need for delivery to ensure all required variants are ready immediately.

For example, to create an upload preset with video eager transformations, specify the following:

• f_webm with vc_vp9 (VP9 codec in WebM format)
• f_mp4 with vc_av1 (AV1 codec in MP4 format)
  Note

  avi is a premium feature for Enterprise customers, contact support to check availability.
• f_mp4 with vc_h265 (H.265/HEVC codec in MP4 format)
• f_mp4 with vc_h264 (H.264/AVC codec in MP4 format)

For incoming transformations, specify a concrete target format if format conversion is needed, such as f_jpg to convert all uploaded images to JPEG, or f_mp4 with a specific video codec to normalize video formats before storage.

For example, to normalize user-uploaded images to JPEG format:

Use asynchronous processing for time-intensive transformations

Video transformations and other time-intensive processes, such as moderating large files, can benefit from asynchronous processing. When configuring presets for videos or large files, set eager_async to true and provide an eager_notification_url to process transformations in the background and receive a notification when complete. See Eager asynchronous transformations.

Example:

Signed and unsigned upload preset security

Choose signed vs unsigned based on use case

Upload presets can be configured as either signed or unsigned:

• Signed presets: Use for authenticated uploads from your backend. They support all upload parameters and require generating an authentication signature in the upload request.

• Unsigned presets: Use for unauthenticated uploads from client-side applications (browser/mobile) without requiring signature generation. However, they have restrictions:

  • Upload requests using unsigned presets can only pass a limited set of parameters directly in the request
  • All other configuration must be predefined in the preset itself
  • The preset name will be visible in client-side code

For more information on authenticated vs unauthenticated uploads, see Authenticated requests and Unauthenticated requests.

Protect unsigned presets

Unsigned preset names can be discovered in client-side code. Apply protective measures in your unsigned presets such as:

• Restrict allowed file formats with allowed_formats.
• Limit file size with the max_file_size parameter.
• Set disallow_public_id to prevent users from specifying public IDs.
• Apply incoming transformations to normalize asset dimensions/duration before storage.

For example, here's an unsigned preset with security measures:

Optimization and performance

Balance storage vs delivery performance

• Use incoming transformations to reduce storage costs by normalizing user-generated content (e.g., limit resolution, strip metadata).
• Use eager transformations to pre-generate frequently accessed derivatives and improve first-time delivery performance.
• Avoid generating unnecessary eager transformations that increase storage without meaningful benefit.

Test before production

Always test new upload presets with sample assets before deploying to production, especially when using eager or incoming transformations. Verify that:

• Eager transformations generate the expected formats and quality.
• Incoming transformations don't over-compress or degrade asset quality.
• Delivery URLs use the exact same parameter order as the eager transformations (e.g., if you eagerly generate c_fill,h_400,w_600, your delivery URL must use that exact order, not c_fill,w_600,h_400).

Naming and organization

Use descriptive preset names

Choose clear names that indicate purpose and settings (e.g., video-social-hls, user-profile-photos, product-images-ecommerce).

Document your presets

Maintain documentation for your team about what each preset does and when to use it, especially if you have multiple presets for similar use cases.

Default upload presets

From the Upload page of the Console 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 of default presets 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, in your Upload widget code, or via the Advanced options of the upload widget in the Media Library.