Programmable Media

Upload parameters

Last updated: Feb-26-2024

The upload request must at least include the file to upload, and Cloudinary supports a wide range of optional parameters you can add to the upload request.

Tip
For a full listing of ALL the possible optional parameters (options = {}) available for the upload method, see the Upload API reference.

Required file parameter

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. This option is only available when using Cloudinary's SDKs. 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.

Notes
  • You can also use your private storage bucket for lazy uploading using the auto-upload mapping functionality or for primary and backup storage.
  • When using your own backup storage, the backup location should not be touched or modified in any way. Additionally, no archiving policy should be enforced on that location (such as an archive policy to a glacier on S3 buckets).

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 upload from this bucket to the product environment with the specified cloud name.
    • 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:

Note
Amazon S3 bucket names containing a . character are not supported for this purpose.

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):

Note
The Node.js SDK uses the dedicated upload_stream method.

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:

Optional upload parameters

The upload method supports a large number of optional parameters, from naming and storage options, to adding tags and metadata, as well as requesting analysis or add-ons, or even transforming the asset before storage. This section provides additional information on some of the most commonly used optional parameters:

Tip
For a full listing of ALL the possible optional parameters (options = {}) available for the upload method, see the Upload API reference.

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

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:

Notes
  • The public ID value for image and video asset types should not include the file extension. If you include a . character in a public ID, it's simply another character in the public ID value itself. The format (extension) of a media asset is appended to the public_id when it is delivered. For example, if you specify myname.mp4 as the public_id, then the video would be delivered as myname.mp4.mp4.
  • For raw asset types only, the file extension should be specified as part of the public_id.
  • Public IDs can be up to 255 characters, including non-English characters, periods (.), forward slashes (/), underscores (_), hyphens (-).
  • Public ID values cannot begin or end with a space or forward slash (/). Additionally, they cannot include the following characters: ? & # \ % < > +

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:

Notes
  • You cannot use v followed by numeric characters as the name of a path element in your public ID.
  • You cannot use /images/ or /videos/ as a path element in your public ID. Those names are reserved for use with dynamic SEO suffixes.
  • It's recommended to avoid using public ID path names starting with 1-3 characters followed by an underscore, such as my_path. By default, Cloudinary assumes that URL components following that pattern represent a Cloudinary transformation component. If the first path element of a public_id does follow that pattern, then when delivering assets from that path, you must separate the last transformation component from the path element with a version component. For example:

    https://res.cloudinary.com/my_cloud/image/upload/t_transf1/t_transf2/v1/my_path/sample.jpg
  • For details on delivering Public IDs in a path structure with or without versions, see Asset versions.
  • The effect on the Media Explorer of including path elements in public IDs depends on whether your product environment is using fixed folder mode or dynamic folder mode.
    • If your product environment is using fixed folder mode (most accounts and product environments created before September 2022 are using this mode), then including slashes in a public ID will also create folders in the same structure in the Media Explorer. If an asset is moved to a different folder in the Media Explorer, that results in a change to the asset's public ID.
    • If Dynamic folders mode is enabled on your product environment, slashes in a public ID do not impact how the asset is organized in the Media Explorer. Additionally, if in this mode, you should use the new asset_folder parameter instead of the folder parameter mentioned above to set the Media Explorer folder. Whether or not you define an asset folder for purposes of organizing assets in the Media Explorer, if you also want your public_id to include slashes, make sure to use one of the options available in that mode to set the public ID path.
    • If your product environment is using dynamic folder mode, you'll see a Dynamic Folders indication at the top of the Media Library Preferences in the console, and the response of a Get details of a resource method will include display_name and asset_folder response keys.
    • For more details on dynamic folders mode, see Dynamic folders - New Upload API parameters.

Asset types

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

This section contains the following topics:

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:

Tip
The Cloudinary Video Player provides a feature-rich and customizable interface to present your uploaded videos to your users and allows you to make use of functionality such as adaptive bitrate streaming and much more.

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.

Note
Although the Public IDs of image and video files do not include the file's extension, Public IDs of raw files must include the original file's extension.

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.

Storage 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 storage type.

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

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

Important
This section only shows how to apply the type storage method feature as part of your upload command. See the Media access methods documentation for more information on all the access control methods features and who can access your files and when.

This section contains the following topics:

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

Note
You can make a private original asset temporarily accessible, for example, to enable a customer to access a stock photo on your site after she purchases it. To do this, you need to deliver a time-limited and signed URL. You can do this directly using the API or you can use the private_download_url Utils method, which generates a time-limited, signed URL link to the original asset, which you can then provide to relevant customers. For details, see Providing time-limited access to private assets

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 storage 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

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.

Tip
An alternative method of ensuring that the latest versions of assets are delivered is to include version values in your delivery URLs. This method requires updating your delivery URLs in your production code when new versions of an asset are uploaded, but the change takes effect immediately. For details, see Asset versions.

Notes
  • Depending on your product environment setup, overwriting an asset may clear the tags, contextual, and structured metadata values for that asset. If you have a Master admin role, you can change this behavior for your product environment in the Media Library Preferences pane, so that these field values are retained when new version assets overwrite older ones (unless you specify different values for the tags, context, or metadata parameters as part of your upload).
  • There are a number of important considerations when using the invalidate functionality. For example, if there is no version number in a URL that includes a public ID with slashes, then by default, those URLs are not invalidated. For details on invalidating media assets, see Invalidating cached media assets on the CDN.

See also: Backups and version management

Upload 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:

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_analysis1, asset_folder2, 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, colors1, coordinates, display_name2, duration, etag, exif, faces, filename, format, format_duration, grayscale, has_alpha, has_audio, height, ignore_loop, illustration_score, media_metadata1, nb_audio_pckts, pages, phash1, phash_mh, predominant, public_id,quality_analysis1, 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".
    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).

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}})):

✔️ Feedback sent!

Rate this page: