Programmable Media

Upload

Last updated: Sep-09-2024

Using Cloudinary's upload capabilities, you can upload media assets in bulk with a variety of options for customizing how they will be uploaded.

When you upload to Cloudinary, your asset is not only stored, but Cloudinary also automatically analyzes and saves important data about each asset, such as format, size, resolution, prominent colors, etc. This data is also automatically indexed to enable searching on those attributes.

Cloudinary provides a secure and comprehensive API for easily uploading media files from server-side code, directly from the browser or from a mobile application. When needed, you can also use the API to perform unsigned uploads, but with a limited set of available upload parameters as a security precaution.

New to Cloudinary?

This guide provides an in-depth overview of Cloudinary's Upload API capabilities. To get started with the basics of uploading (and more) in 5 minutes or less, we recommend you first run through one of our backend SDK quick starts.

Each quick start gives you the code to configure your SDK, run your first upload, and then perform a few other common Cloudinary operations, all using your favorite programming language or framework.

If you haven't moved over your existing assets to Cloudinary yet, you may also want to check out our Migration guide.

On this page:

Quick examples
Basic uploading
Upload response
Upload considerations

Quick examples

Example 1: Upload the local hat.jpg image, and use the filename to set the public ID.

Example 2:

Upload a remote image from wikipedia
Set the public ID as "wiki_shirt"
Request color and quality analysis
Run the Google Auto Tagging add-on
Automatically add the detected categories as tags to the asset

Programmatic upload with the Node.js SDK video tutorial

Watch this video on how to quickly upload images, videos and other media files to Cloudinary using Cloudinary's Node.js SDK.

Tutorial contents

Basic uploading

You can upload assets programmatically either by using authenticated uploads that include a signature, or using unauthenticated uploads without a signature but with certain restrictions for security reasons.

The upload API method enables you to upload files with a direct call to Cloudinary by sending an HTTPS POST request to the following Cloudinary REST API URL:

https://api.cloudinary.com/v1_1/<cloud name>/<resource_type>/upload

Where:

cloud name is the name of your Cloudinary product environment.
resource_type is the type of file to upload. Valid values: image, raw, video and auto to automatically detect the file type.

For example, to upload an image file to the Cloudinary 'demo' product environment, send an HTTPS POST request to the following URL:

https://api.cloudinary.com/v1_1/demo/image/upload

The contents of the POST request you send to Cloudinary depends on whether or not you are making an authenticated request or an unauthenticated request.

Uploading is performed synchronously, and once finished, the uploaded asset is immediately available for transformation and delivery.

Tips

Use the auto-upload feature for lazy migration of all your assets from a remote location to Cloudinary with minimal effort on your side.
Enterprise customers can set up their account to use an EU or AP data center with the endpoints becoming api-eu.cloudinary.com or api-ap.cloudinary.com respectively.

Authenticated requests

Authenticated upload requests are performed over HTTPS using a secure protocol and include an authentication signature that is generated based on your product environment's cloud_name, api_key and api_secret parameters. This signature should be generated on your backend, as you should never expose your api_secret in client-side code.

Required parameters for authenticated requests:

file - The file to upload. Can be the actual data (byte array buffer), the Data URI (Base64 encoded), a remote FTP, HTTP or HTTPS URL of an existing file, or a private storage bucket (S3 or Google Storage) URL of a whitelisted bucket. See File source options for more details.
api_key - The unique API Key of your Cloudinary product environment.
timestamp - Unix time in seconds of the current time (e.g., 1315060076).
signature - A signature of all request parameters including the 'timestamp' parameter but excluding the 'api_key', 'resource_type', 'cloud_name' and 'file' parameters, based on your product environment's API secret. The signature is valid for 1 hour.

Cloudinary's backend SDKs wrap the Upload API and greatly simplify using the API methods, including automatically generating the authentication signature based on the product environment credentials provided in your SDK configuration. When using the SDKs to upload, the only parameter that's required is the file parameter: the api_key, timestamp and signature parameters are automatically added by the SDK.

There are also a large number of optional upload parameters available for customizing your upload, including naming, whether to apply manually specified or automatically generated tags and metadata, whether to apply incoming transformations or other AI-based analysis of the uploaded assets, and much more. See the optional upload parameters reference for the full list.

Note

If you can't or don't want to use the SDKs, you can use Cloudinary's REST API directly, but you will need to manually generate the signature. See the Client-side uploading documentation for an example code explorer to upload multiple files from the client-side while using a backend component to generate the signature.

The Cloudinary upload method performs an authenticated upload API call over HTTPS using the following syntax:

For example, to upload the sample.jpg file to the Cloudinary demo product environment:

Chunked asset upload

To support the upload of large files, the Cloudinary SDKs include a method which offers a degree of tolerance for network issues. The upload_large method uploads a large file to the cloud in chunks, and is required for any files that are larger than 100 MB. This is often relevant for video files, as they tend to have larger files sizes.

Tip

If you can't or don't want to use the SDKs, you can make use of the byte Content-Range entity-header HTTP specification to send the file in multiple calls with the 'upload' endpoint of the REST API. See the Client-side uploading documentation for an example code explorer to upload large files in chunks from the client-side.

By default, when using the upload_large method, files are uploaded as raw files if the resource_type parameter is not specified. For more details about the resource_type option, see Asset types.

Note

Any file larger than 20 GB also needs to be uploaded asynchronously by adding the async parameter set to true. If you need to upload very large files you can contact support to increase your upload limit up to 100 GB. You can see your current usage limits in your Console Account Settings.

For example, uploading a large video file named my_large_video.mp4:

By default, the chunk size is set to 20 MB but can be set to as low as 5 MB by using the chunk_size parameter. For example, uploading a large video file named my_large_video.mp4 and setting chunk size to 6 MB:

Note

There are multiple responses to a chunked upload: one after each chunk that only includes basic information plus the done : false parameter, and a full upload response that is returned after the final chunk is uploaded with done: true included in the response.

Unauthenticated requests

Unauthenticated upload requests are an option for performing upload without the need to generate an authentication signature on your backend. However, for security reasons, not all upload parameters can be specified directly when performing unsigned upload calls.

Unsigned upload options are controlled by an upload preset, so in order to use this feature you first need to enable unsigned uploading from the Upload page of the Console Settings. An upload preset is used to define which upload options will be applied to assets that are uploaded unsigned with that preset specified. You can edit the preset at any point in time (or create additional upload presets), to define the parameters that will be used for all assets that are uploaded unsigned from user browsers or mobile applications. For more information on upload presets, see the upload preset guide.

Required parameters for unauthenticated requests:

file - The file to upload. Can be the actual data (byte array buffer), the Data URI (Base64 encoded), a remote FTP, HTTP or HTTPS URL of an existing file, or a private storage bucket (S3 or Google Storage) URL of a whitelisted bucket. See File source options for more details.
upload_preset - The name of an unsigned upload preset that you defined for unsigned uploading.

There are also a large number of optional upload parameters available for customizing your upload, including naming, whether to apply manually specified or automatically generated tags and metadata, whether to apply incoming transformations or other AI-based analysis of the uploaded assets, and much more. For security reasons, only this restricted set of parameters can be used in an unsigned upload request. However, most upload parameters can be defined as part of your unsigned upload preset.

The Cloudinary backend SDKs also support unsigned upload methods as an option for performing unauthenticated requests without the need to generate an authentication signature on your backend.

To perform an unsigned upload, call the unsigned_upload method of the Cloudinary SDKs while setting the upload_preset and cloud_name parameters. For example, to upload the sample.jpg file with the unsigned_1 upload preset:

Tip

If you can't or don't want to use the SDKs, you can use Cloudinary's REST API directly. See the Client-side uploading documentation for an example code explorer to upload a file from the client-side using a direct call to the REST API.

Upload response

A successful upload API call returns a response that includes the HTTP and HTTPS URLs for accessing the uploaded file, as well as additional information regarding the uploaded asset. Among these are the assigned public ID and current version of the asset (used in the Media Explorer, Admin API, and for building transformation and delivery URLs), the asset's dimensions, the file format and a signature for verifying the response. Depending on the optional parameters passed, the response might also include valuable analysis data such as detected faces, prominent colors, exif and other embedded metadata, quality/accessibility and other sophisticated media analysis data.

Important

Cloudinary may add more fields to API responses and notifications in the future, so please ensure that your response parsing remains backwards compatible and wont be broken by the presence of unknown fields.

The following is an example of the JSON response returned:

Note

Although the URLs returned in the response are given with the version number, including the version in the delivery URL is optional.

Error handling

Once the POST request is received and processed by Cloudinary, the Upload API returns the status of requests using one of the following HTTP status codes:

200 - OK. Successful.
400 - Bad request. Invalid request parameters.
401 - Authorization required.
403 - Not allowed.
404 - Not found.
420 - Rate limited.
500 - Internal error. Contact support.

In the case of wrong usage of the API or an error, Cloudinary's response is returned with a non-OK (not 200) HTTP Status code and a body with the following JSON format:

Upload considerations

There are various ways to upload your resources to your Cloudinary account. Cloudinary supports making both authenticated requests that require a signature generated on your backend, and unauthenticated requests with a restricted set of supported parameters.

The following table summarizes the main options to upload assets and some considerations to take into account for each of them:

Option	Description	Considerations
Cloudinary backend SDKs	The Cloudinary backend SDKs wrap the upload API, including taking care of the upload itself, the signature authentication and the response verification.	✅ Significantly simplifies the upload code compared to directly calling the REST API ✅ Automatically generates an authentication signature and validates the response ✅ Enables you to code in your chosen language ✅ Provides built-in support for uploading large files with chunked uploading
Upload widget	An interactive, feature-rich interface you can embed in your website or application to allow your users to upload assets directly to Cloudinary.	✅ No need to develop an in-house interactive file upload solution ✅ Simple to integrate ✅ Can be used for unauthenticated client-side uploads ✅ Enables uploading directly from a variety of social media & stock photo accounts
'upload' endpoint of the REST API	The `upload` endpoint of the Cloudinary API supports making both authenticated requests that require a signature be generated on your backend, and unauthenticated requests with a restricted set of supported parameters.	✅ Can be used for unauthenticated client-side requests ✅ Useful when coding in a language not covered by Cloudinary's SDKs 💡 Requires manually coding the upload and validating the response 💡 Requires a function on your backend to generate the signature for authenticated calls
Direct upload from a browser	The Cloudinary Backend SDKs can also be used to automatically add a file input field to your form that uploads files directly to Cloudinary, bypassing your own servers.	✅ Uploads directly to your account, bypassing your own servers 💡 Requires additional setup and configuration 💡 Requires the Cloudinary jQuery plugin
The Cloudinary CLI	The Cloudinary CLI (Command Line Interface) enables you to interact with Cloudinary through the command line and provides additional features and helper commands.	✅ Simple to use ✅ Useful for quickly uploading assets without setting up a formal coding environment ✅ Useful for experimenting with upload parameters and behavior ✅ Upload-specific helper functions (e.g., sync) not directly provided via the other upload options
Lazy migration	Cloudinary's lazy migration with the auto-upload feature enables you to migrate files on demand from a remote location, where each asset is automatically uploaded to Cloudinary the first time the delivery URL for that asset is requested.	✅ Simple to implement ✅ Only upload the assets you really need 💡 Not suitable if there's a deadline when the remote content will be unavailable
Media Explorer	The Media Explorer page in the Cloudinary Console lets you upload assets to your account using drag and drop or the built-in upload widget.	✅ Simple to use ✅ Useful for quickly uploading assets without dealing with code ✅ Useful for experimenting with upload preset behavior 💡 Less suitable as a primary means of uploading assets compared to programmatic solutions
Integrations	Cloudinary has developed built-in integrations with many leading eCommerce, CMS and PIM platforms.	✅ Enables platform users to upload to Cloudinary from directly within the platform UI 💡 Requires initial set up and configuration by a platform administrator 💡 Less suitable as a primary means of uploading assets compared to programmatic solutions
Media Library widget	The Media Library widget enables embedding all the Cloudinary Media Library UI capabilities, including upload, into another application's UI.	✅ Useful for implementing your own Cloudinary integration 💡 Less suitable as a primary means of uploading assets at scale compared to programmatic solutions

Tips:

MediaFlows, Cloudinary’s drag-and-drop workflow builder for image and video, offers the option to automate image upload with a low-code implementation. See MediaFlow’s documentation on media upload here.
Usage limits for uploading, transforming and delivering files depend on your Cloudinary plan. For details, check the Account tab in your Cloudinary Console Settings.

Error

Unfortunately there's been an error sending your feedback.

Rate this page: