Customizing uploads

The upload method request of the Upload API must at least include the source of the file to upload, but Cloudinary also supports a wide range of optional parameters, from naming and storage options, to adding tags and metadata, as well as requesting analyses, moderation, and webhook notifications, calling add-ons, and even transforming the asset before storage. This page provides additional information on some of the most commonly used upload customizations.

File sources

Specifying the file to upload is required for all uploads. Cloudinary supports uploading files from various sources, including from a local path, a remote URL, a private storage URL (S3 or Google Cloud storage), a data stream, a Base64 data URI, or an FTP URL.

Upload from a local path

You can upload an asset by specifying the local path of a media file. For example:

Upload from a remote URL

If your assets are already publicly available online, you can specify their remote HTTP or HTTPS URLs instead of uploading the actual file or file data. In this case, Cloudinary will retrieve the file from its remote URL and upload it directly to Cloudinary. This option allows for a much faster migration of your existing media files. For example:

Upload from a private storage URL (Amazon S3 or Google Cloud)

If you have existing media files in a private storage (Amazon S3 or Google Cloud storage) bucket, you can upload files from a storage bucket URL.

To enable this option, your storage bucket must be whitelisted. This requires the following steps:

1. Add an empty file to your bucket with your cloud name as the filename, under the following folder structure: .wellknown/cloudinary/<your_cloud_name>
   

   • By adding this file, you indicate that you have access to this bucket and that you permit Cloudinary to access and modify this bucket's contents.
   • If you want this bucket to be whitelisted for more than one Cloudinary product environment, you can add an appropriately named file for each cloud name.

2. Provide Cloudinary with read access to your bucket:
   - How to set read access on a private Amazon S3 bucket
   - How to set read access on a Google Storage bucket

After your storage bucket is whitelisted, you can pass the Amazon S3 (s3://my-bucket/...) or Google Storage (gs://mybucket/...) URL in your upload method.

S3 example:

Google Cloud example:

How to set read access on a private Amazon S3 bucket

1. In Amazon's AWS S3 Console, select the relevant bucket.
2. In the Bucket Policy properties, paste the following policy text.
   Keep the Version value as shown below, but change BUCKETNAME to the name of your bucket.
   If a policy already exists, append this text to the existing policy:

How to set read access on a Google Storage bucket

1. In your GCP console, go to your Google bucket's main page.
2. Select to edit bucket permissions.
3. Add service@cloudinary-gcs-production.iam.gserviceaccount.com as a member and give it the Storage Object Viewer role.

Upload data stream

You can upload an actual data stream (byte array buffer):

Upload via a Base64 data URI

You can upload a file by specifying the Data URI of the file in Base64 encoding (no larger than 60 MB). For example:

Upload from an FTP URL

You can upload a media file by specifying a remote FTP URL. For private FTP servers, the username and password must be included as parameters with the FTP URL syntax taking the form: ftp://<user>:<password>@<host>:<port>/<url-path>. For example:

Identification

Cloudinary provides various identifiers to help you identify and then deliver your asset.

• Public ID - The primary unique identifier that is used to reference the asset as well as for building dynamic delivery and transformation URLs. If you don't specify a public_id, Cloudinary will randomly assign a public ID in the response from the upload API call, although you would generally want to specify a more readable and SEO-friendly public ID.
• Asset ID - Cloudinary randomly assigns an asset ID to every uploaded asset, and returns this value in the upload response. This is an automatically generated immutable asset identifier that is fully unique and enables developers to reliably reference the asset programmatically, even if the public ID value changes.

On product environments using dynamic folder mode, you have 2 more identifiers:

• Asset folder - The folder where the asset is located. You can move assets between asset folders and rename an asset folders without affecting the asset's public ID value and delivery URL path.
• Display name - You can change the display name without affecting the asset's public ID value and delivery URL path.

Public ID

Every asset uploaded to Cloudinary is assigned a unique identifier in the form of a public ID, which is a URL-safe string that is used to reference the uploaded resource as well as for building dynamic delivery and transformation URLs. You can also browse and search resources by public IDs in Cloudinary's Media Explorer web interface.

If you don't supply a public ID in the upload API call, you will receive a randomly assigned public ID in the response from the upload API call. A randomly generated public_id looks something like this: 8jsb1xofxdqamu2rzwt9q. The resulting delivery URL for such an asset would be something like:

https://res.cloudinary.com/demo/image/upload/8jsb1xofxdqamu2rzwt9q.jpg

You can set the public_id parameter when you upload an asset, which is useful when you want your delivery URLs to be more readable and SEO-friendly. For example:

This section contains the following topics:

• Public ID naming preferences
• Including a path in the public ID

Public ID naming preferences

To tell Cloudinary to use the original name of the uploaded file as its public ID, include the use_filename parameter and set it to true. The file name will be normalized to include only URL-safe characters, and a set of random characters will also be appended to ensure the uniqueness of the public ID. By also including the unique_filename parameter and setting it to false, you can tell Cloudinary not to attempt to make the public ID unique, and just use the normalized file name. The following code example will upload the image file with the filename, sample_file.jpg and ensure that the public ID of the asset is set to sample_file:

Including a path in the public ID

The public ID value can include path elements (slashes) for more structured delivery URLs and to assist with SEO. For example:

This can also be done by splitting the public ID into 2 parts, specifying only the last element of the public ID in the public_id parameter, and specifying the public ID path in the folder parameter. Using the same example as above, but this time with the folder parameter:

Replacing existing assets

An existing image or video asset will be replaced by a newly uploaded file when overwrite is set to true and:

• You upload a new media asset while specifying its public_id to be the same as an existing asset
• The asset gets the same public ID as an existing one via the use_filename=true upload option
• You use an upload preset where one of the above options is applied

If backups are enabled for your product environment, then when an asset is replaced, the previous version is backed up and can be restored if needed.

However, if the original (older) asset has already been generated and accessed, it might already be cached on the CDN. If an end-user accesses the identical URL soon after you overwrote the asset, they will still be accessing a CDN cached version rather than the new updated one.

You can ensure that a new version of an asset is delivered by setting the optional invalidate parameter to true when you overwrite an existing asset. This invalidates the previous media asset throughout the CDN. Note that it usually takes between a few seconds and a few minutes for the invalidation to fully propagate through the CDN.

See also: Backups and version management

Storage

Cloudinary stores your assets in storage buckets (S3 or Google Cloud Storage) according to its asset type, and also allows you to restrict access to your assets as necessary.

• Asset types: Assets are uploaded as type image, video, or raw. You can manually set the type or let Cloudinary automatically do it for you based on the source file.
• Delivery types: Access to your assets can be restricted based on the asset's delivery type: upload (public), private, or authenticated.

Asset types

Cloudinary supports many different file formats, which are categorized into three different asset types (resource_type in the API):

• image (including animated images, PDFs and 3D models). For supported file formats, see Supported image formats and Uploading 3D models.
• video: All video and audio files. For supported file formats, see Supported video formats and Supported audio formats.
• raw (any other file type).

This section contains the following topics:

• Passing the resource_type parameter to your upload call
• The 'auto' resource_type
• Uploading videos
• Uploading 3D models
• Uploading non-media files as raw files

Passing the resource_type parameter to your upload call

• When uploading using the REST API, the resource_type is part of your upload endpoint.
• When uploading using a backend SDK, image is the default resource_type. When uploading video or raw file types, you must pass the resource_type option either with the value auto or with the relevant specific asset type.
• When using direct image uploading from the browser, resource type is set to auto by default.
• Uploading a password-protected PDF as an image asset is not supported. If necessary, you can upload a password-protected PDF by setting the resource_type to raw in the upload command. However, keep in mind that like any other raw file, you can deliver a raw PDF as is, but PDF transformations are not supported for raw assets.

Note that for simplicity, many of the examples in this guide demonstrate uploading an image file. If you use these code examples as the basis for your own video or raw file uploads, don't forget to add the resource_type option.

The 'auto' resource_type

The upload method also supports supplying auto as a value for the resource_type parameter. When you send this value, Cloudinary automatically detects the asset type of the uploaded file and automatically sets the relevant resource_type value for the stored asset.

For example:

The auto value is especially useful when you don't know what type of files your users will upload, or if you are uploading multiple files of different asset types with the same settings. When using auto as the resource_type along with other upload options, only the upload options relevant to a particular asset type are applied. Any options that work only with a different asset type are silently ignored.

Uploading videos

Uploading videos generally works the same and supports the same options as uploading images. However, when uploading videos, keep the following guidelines in mind:

• The default value for the upload method resource_type parameter in SDKs is image, so you must set the resource_type parameter when uploading videos. You can set the resource_type parameter to auto to instruct Cloudinary to automatically detect the asset type, or you can set the parameter to video if you know in advance that you are uploading a video file.
• By default, uploading is performed synchronously, and once finished, the uploaded video is immediately available for transformations and delivery. For videos larger than 100 MB, you will need to use chunked uploading.
• There are also file-size limits for transforming larger videos on the fly. The exact limits depend on your account plan. Therefore, it's best practice to generate your video transformations eagerly on upload.

Here's a simple video upload example:

Audio files (such as MP3s) can also be uploaded as a video resource. Audio files are treated as video files without a visual element and thus are uploaded in the same way as videos, using video as the resource_type. For example, uploading a local audio file named audio_sample.mp3:

Uploading 3D models

Cloudinary supports 3D models in various formats. Where the format requires a set of files (for example, textures or other images used in the model), you should zip the entire folder and upload the single ZIP file to Cloudinary.

In order to use 3D models in the Product Gallery and perform transformations on them, the 3D model needs to be uploaded as an image asset type to Cloudinary.

ZIP files are normally uploaded as raw files if the asset type is not specified. However, Cloudinary is able to detect some 3D models and upload them as image types, which is especially useful if uploading manually from within your Media Explorer.

If you are uploading a 3D model programmatically, you can explicitly set resource_type to image. For example, to upload the 3D model archived in the sample_3D.zip file:

Uploading non-media files as raw files

Any file that is not an image or video file is treated as a 'raw' file. Raw files are stored as-is when uploaded to Cloudinary. No transformations on uploaded raw files are available. However, you can deliver your raw assets through a dynamic CDN URL in the same way you deliver image and video assets.

Here's a sample response of a raw upload call, which is slightly different from an image or video upload response:

Converting raw files

The raw_convert upload parameter enables you to perform certain asynchronous operations on uploaded files. Depending on the option specified for this parameter, you can either convert certain raw files to other formats or generate related raw files that can be used in conjunction with the image or video file you uploaded.

For example:

• Specify aspose as the value for your raw_convert parameter when uploading an Office document to instruct the Aspose Document Conversion add-on to generate a PDF image file from your raw office document.
• Specify google_speech when uploading a video to instruct the Google AI Video Transcription add-on to generate an automatic transcript raw file from your uploaded video.

• Specify extract_text when uploading a PDF file to extract all the text from the PDF file and store it in a raw file. The public ID of the generated file will be in the format: [pdf_public_id].extract_text.json.

  Note

  The text extraction result using the extract_text option may be different than the result you get if you use the OCR text detection and extraction add-on. For example, the OCR add-on includes exact coordinates of each line of text. Additionally, if your PDF contains images with text, the OCR add-on will capture this text, but the raw_convert:"extract_text" option will not.

Delivery types

By default, when uploading assets to Cloudinary, both the original asset and its transformed versions are publicly available through a CDN. One way to restrict access to your assets is based on the asset's delivery type.

Cloudinary supports three different delivery types (type in the API):

• upload - The asset is publicly available. This is the default type when uploading files.
• private - Original assets are only accessible by a signed URL.
• authenticated - Original assets and all their asset derivations are only accessible through signed URLs.

This section contains the following topics:

• Private assets
• Authenticated assets

Private assets

You can upload assets as private to restrict access to the original asset and only allow access to derived (transformed) versions of the asset. The original asset can be accessed only with a signed URL, but by default, all derived versions of the asset are accessible. You can further restrict access to the derived asset by activating the Strict Transformations mode. This mode also prevents access to the derived versions of the asset, except for those that have been specifically enabled (e.g., with watermarks) that are then available for public delivery to your users. With Strict Transformations enabled, you need to either eagerly generate all derived assets, mark specific transformations as allowed or use signed URLs.

To upload an asset as a private asset, you set the type parameter to private (instead of the default upload) when uploading the asset to Cloudinary. For example:

An asset that was uploaded as 'private' cannot be accessed publicly without a signed URL. For example, the following URL returns an error:

https://res.cloudinary.com/demo/image/private/sample.jpg

Authenticated assets

You can upload assets as authenticated to even further restrict access to both the original asset and to the derived (transformed) versions of the asset. Authenticated assets and their derived versions cannot be accessed without some form of authentication. For more information see Authenticated access to media assets.

To upload an asset as an authenticated asset, you set the type (type parameter) to authenticated (instead of the default upload) when uploading the asset to Cloudinary. For example:

If an asset was uploaded as 'authenticated', neither the asset nor any of its derived resources can be accessed without authentication. For example, the following URL returns an error:

https://res.cloudinary.com/demo/image/authenticated/sample.jpg

Transformations

Cloudinary's transformations can be used while uploading an asset in one of two ways:

• Eager transformations: Generate transformed assets after the upload completes, so that those transformations will already be available for delivery before your users access them for the first time.
• Incoming transformations: Transform the original asset as part of the upload and before storing it in Cloudinary.

Eager transformations

You can eagerly generate transformed assets after the upload completes, so that those transformations will already be available for delivery before your users access them for the first time. These transformations are generated in addition to storing the original asset as is. Eager transformations are useful for pre-generating transformations:

• For large images or videos that can take a while to generate.
• For AI analyses, or other asynchronous operations, such as those performed by some Cloudinary add-ons.
• In the case that you want to enable Strict Transformations and limit access to dynamic URLs.

For example, you can eagerly generate transformed assets while uploading them by also specifying the eager parameter in the upload method. The following code uploads the sample.jpg image and then additionally generates two transformed images:

1. Pad to a width of 400 pixels and height of 300 pixels.
2. Crop to a width of 260 pixels and a height of 200 pixels with north gravity.

The delivery URLs for these eagerly generated transformations:

Incoming transformations

Transform the original asset as part of the upload and before storing it in Cloudinary. This is especially useful to normalize user-generated content, for example to limit the resolution size or clip a long video to a maximum duration.

For example, you can transform an asset while uploading, and before storing, by also specifying the transformation parameter in the upload method. The following code limits the dimensions of an uploaded image to a width of 2000 pixels and a height of 1000 pixels:

Metadata

There are three types of metadata that can be stored with your assets: structured metadata, contextual metadata, and tags. These types of metadata are useful for searching assets based on a value or field value pair, or as a method of marking assets for a particular purpose in your end-user application.

This enables other users to decide which assets get which field values or tags, while you use custom metadata API methods to implement the application side based on the values they set. Available metadata options include:

• Tags: Tags are used to categorize and organize your assets, and can also be used to bulk delete assets, create sprites, ZIP files, JSON lists, and generate PDFs and animated GIFs. Cloudinary also provides various AI-based add-ons to help you automatically tag your assets, where assets are automatically assigned resource tags based on the detected scene categories.
• Contextual metadata: custom key-value pairs that you can assign to individual assets.
• Structured metadata: custom fields are defined, along with data types and validations, at a global level, and are added to all assets in the product environment. You assign their values per asset.

The following example demonstrates using the Google Auto Tagging to automatically tag an uploaded image with all detected categories that have a confidence score higher than 0.6.

Moderation

It's sometimes important to moderate assets that are uploaded to Cloudinary: to keep out inappropriate or offensive content, reject assets that do not answer your website's needs, or make sure that photos are of high enough quality before making them available on your website. You can manually mark an uploading image or video for moderation or use one of the AI-based add-ons to automatically moderate your assets.

Assets added to the moderation queue can then be reviewed in the Media Library.

For example, you can moderate assets while uploading them by specifying the moderation parameter in the upload method. The following code marks an image for moderation by the WebPurify's Image Moderation add-on and the Cloudinary Duplicate Image Detection add-on:

Analysis

When uploading assets to your Cloudinary product environment, you can request different types of analysis to be performed on the assets. In addition to Image quality analysis, Accessibility analysis, and Semantic data extraction, Cloudinary has a number of add-ons that enable various types of AI-based analyses.

For example, you can request quality and accessibility analysis on assets while uploading them by specifying the quality_analysis and accessibility_analysis parameters in the upload method. The following code uploads the user_photo.jpg image and requests analysis:

The following is an example of the response returned:

Webhook notifications

Cloudinary provides a webhook notification feature for informing your backend about uploads. When the upload is completed, an HTTP POST request can be sent to a public notification URL you provide. The payload contains all the results pertinent to the upload.

For example, you can ask Cloudinary to send a notification when an asset finishes uploading, by specifying the notification_url parameter in the upload method. The following code uploads the sample.jpg image and then sends a notification to https://mysite.example.com/my_notification_endpoint.

For example, to add a notification_url to a specific upload call:

Asynchronous processing

By default, Cloudinary's upload works synchronously. Assets are uploaded and the requested processing from most of the added optional parameters is completed synchronously during an upload API call, and then the upload response is returned.

However, in some cases you may want to process the upload asynchronously in the background, especially uploads that require a relatively long time to process and may require your users to actively wait for the processing to finish. As the complete response may not be immediate, it is good practice to use asynchronous handling for these calls.

To make the call asynchronous, set the async parameter of the upload method to true. Cloudinary will return a short response immediately that the upload is pending together with a batch ID to track the upload. Once the upload and all processing completes, a notification is sent to the specified notification_url parameter or the global webhook Notification URL in the Webhook Notifications page of your Cloudinary Console Settings.

For example, to asynchronously upload an image, request the Content Analysis add-on to analyze the image and suggest a caption, and then send a notification to "https://mysite.example.com/upload_endpoint" when the processing is complete with the full upload response:

The immediate response to an asynchronous upload call is short and looks similar to this:

When the processing is finished, the complete upload response is sent to the notification URL that you specified.

Events

You can inject your own JavaScript code to be evaluated as part of the upload. The upload method offers the following parameters to pass your custom code:

• eval - For evaluating and modifying upload parameters. Your code will be evaluated before the file itself is uploaded.
• on_success - For executing an update script. Your code will be evaluated after the file itself is uploaded.

Evaluating and modifying upload parameters

The eval parameter allows you to modify upload parameters by specifying custom logic with JavaScript code that is evaluated when uploading a file to Cloudinary. This can be useful for conditionally adding tags, contextual metadata and structured metadata depending on specific criteria of the uploaded file.

The eval parameter accepts a string containing the JavaScript code to be evaluated. There are two variables that can be used within the context of the JavaScript code snippet as follows:

• resource_info - to reference the resource info as it would be received in an upload response. For example, resource_info.width returns the width of the uploaded resource.
  The currently supported list of queryable resource info fields includes: accessibility_analysis¹, asset_folder², audio_bit_rate, audio_codec, audio_codec_tag, audio_duration, audio_frequency, audio_profile, audio_start_time, bit_rate, bytes, channel_layout, channels, cinemagraph_analysis, compatible, colors¹, coordinates, display_name², duration, etag, exif, faces, filename, format, format_duration, grayscale, has_alpha, has_audio, height, ignore_loop, illustration_score, media_metadata¹, nb_audio_pckts, pages, phash¹, phash_mh, predominant, public_id,quality_analysis¹, quality_score, semi_transparent, start_time, width
  
  
  Footnotes

  1. Available when also requesting Semantic data extraction and/or Accessability analysis.
  2. Available on product environments using dynamic folder mode.
• upload_options - to assign amended upload parameters as they would be specified in an upload request. For example upload_options.tags = "new_tag". You can also assign values that would be returned in the response. For example upload_options.tags = "${resource_info.quality_score}
  The following upload options can NOT be amended: eager, eager_async, upload_preset, resource_type, and type.

For example, to add a tag of 'blurry' to any image uploaded with a quality analysis focus of less than 0.5:

Notes
• If using the eval parameter in an upload preset and you also want to set the unique_filename parameter to be false, you need to explicitly set it as false in the eval, and not as a separate parameter in the preset (e.g., upload_options['unique_filename']=false).
• If using the eval parameter and you also want the upload response to include face coordinates (by adding faces=true), you need to explicitly set the parameter to true in the eval (upload_options['faces'] = true).
• You can update multiple metadata fields by separating the values with a pipe (|). For example upload_options.metadata = "quality = ${resource_info.quality_score} | resolution = ${resource_info.quality_analysis.resolution"

On Success update script

The on_success parameter allows you to update an asset using custom JavaScript that is executed after the upload to Cloudinary is completed successfully. This can be useful for adding tags, contextual metadata and structured metadata, depending on the results of using the detection and categorization add-ons, which are only available after the file has already been successfully uploaded.

The on_success parameter accepts a string containing the JavaScript code to be executed. There are two variables that can be used within the context of the JavaScript code snippet as follows:

• event or e - an object that encapsulates all the incoming data as follows:

  • upload_info - an object with all the resource info as it would be received in an upload response. For example, e.upload_info?.width returns the width of the uploaded resource.
  • status - either 'success' or 'failure'

• current_asset - an object that references the asset and currently holds a single method:

  • update - the method to update that receives a hash of the data to update (data is replaced as a result of the update, not added to). The currently supported data fields include: tags, context, and metadata

For example, to upload an asset and update its contextual metadata (context) with the caption returned from the Cloudinary AI Content Analysis add-on, and add the tag 'autocaption' (current_asset.update({tags: ['autocaption'], context: {caption: e.upload_info?.info?.detection?.captioning?.data?.caption}})):