Node.js image and video upload

Image & Video APIs

Last updated: Sep-25-2025

Cloudinary provides an API for uploading images, videos, and any other kind of file to the cloud. Files uploaded to Cloudinary are stored safely in the cloud with secure backups and revision history. Cloudinary's APIs allow secure uploading from your servers, directly from your visitors' browsers or mobile applications, or fetched via remote public URLs.

Cloudinary's Node.js SDK wraps Cloudinary's upload API and simplifies the integration. Node.js methods are available for easily performing Node.js image and video uploads to the cloud and Node.js helper methods are available for uploading directly from a browser to Cloudinary.

This page covers common usage patterns for Node.js image and video upload with Cloudinary.

For details on all available upload functionality, see the Upload guide, and the upload method of the Upload API Reference.

Tip

Cloudinary's Upload widget provides an alternative to using a Cloudinary SDK to add upload functionality to your application, eliminating the need to develop in-house interactive upload capabilities. The upload widget is an interactive, feature rich, simple-to-integrate user interface that enables you to add Cloudinary upload support to your website. The widget can be easily embedded in your web application with just a few lines of JavaScript code. See the Upload widget documentation for detailed information.

On this page:

Server-side upload
Direct uploading from the browser

Server-side upload

You can upload images, videos, or any other raw file to Cloudinary from your Node.js code. Uploading is done over HTTPS using a secure protocol based on your api_key and api_secret parameters.

Programmatic upload video tutorial

Watch this demo on how to quickly upload images, videos and other media files to Cloudinary for immediate deliverability using Cloudinary's Upload API in your development environment.

This video is brought to you by Cloudinary's video player - embed your own!
Use the controls to set the playback speed, navigate to chapters of interest and select subtitles in your preferred language.

View the code

You can find the code from this tutorial in GitHub.

Tutorial contents

You may find these Dev Hints videos useful too:

Node.js upload methods

There are several different methods that you can use to upload files to your product environment:

Method	Description
upload	This method wraps the upload method of the Upload API. You can use it for signed uploads to upload files up to 100 MB.
unsigned_upload	This method is similar to the `upload` method, but requires you to define an unsigned upload preset. You can use it for unsigned uploads to upload files up to 100 MB. Unsigned uploads are useful for low-security use cases, prototyping and testing.
upload_stream	This method takes advantage of Node.js's stream functionality. It's useful when you receive a file as a stream from your users or if the file in your storage is large and you don't want to load it all to memory.
unsigned_upload_stream	This method is similar to the `upload_stream` method, but requires you to define an unsigned upload preset. Unsigned uploads are useful for low-security use cases, prototyping and testing.
upload_chunked	This method uploads a large file in chunks, offering a degree of tolerance for network issues.
upload_chunked_stream	This method is similar to the `upload_chunked` method, but also takes advantage of Node.js's stream functionality.
upload_large	This method is similar to the `upload_chunked` method, but automatically sets the `resource_type` parameter to `raw`.

Note

Unless stated otherwise, all the methods assume that you are uploading an image. If you are uploading a video or a raw file, you need to set the resource_type parameter accordingly.

Tip

Take a look at the Photo Album sample project for examples of using different upload methods.

The `upload` method

Use the upload method to upload a file to your product environment:

For example, uploading a local image file named my_image.jpg:

To upload a video, you need to set the resource_type parameter to video. In this example, we're also setting other parameters: the public ID to dog_closeup, two eager transformations that resize the video to a square and a small rectangle, and a notification URL to catch the webhook to say that the asynchronously processed transformations are ready.

You can specify the file to upload as a local path, a remote HTTP or HTTPS URL, an allowlisted storage bucket (S3 or Google Storage) URL, a base64 data URI, or an FTP URL.

For details and code examples of uploading using each of these data source types, see Required upload parameters.

For details on all available upload functionality, see the Upload guide, and the upload method of the Upload API Reference.

Tips:

If your code is listening for the global event process.on('unhandledRejection'), you can disable the Cloudinary internal promises by also including the disable_promise parameter set to true.
The upload method supports uploading files up to 100 MB (subject to account limitations). To upload larger files, use one of the other methods, which use streaming or chunking functionality.

The `unsigned_upload` method

Use the unsigned_upload method to upload a file to your product environment when you don't require the security that a signed upload provides. You need to pass the name of an unsigned upload preset.

For example, uploading a local image file named my_image.jpg, using an upload preset named my_upload_preset:

To upload a video, you need to set the resource_type parameter to video.

Other details are the same as for the upload method.

The `upload_stream` method

The upload_stream method takes advantage of Node.js's stream functionality. It's useful when you receive a file as a stream from your users or if the file in your storage is large and you don't want to load it all to memory.

The method returns a stream, so for simplicity we wrap it in a Promise:

Using await:

For a video, set the resource_type parameter to video:

Using await:

The `unsigned_upload_stream` method

The unsigned_upload_stream method takes advantage of Node.js's stream functionality. It's useful when you receive a file as a stream from your users or if the file in your storage is large and you don't want to load it all to memory.

Use the unsigned_upload_stream method to upload a large file or stream to your product environment when you don't require the security that a signed upload provides. You need to pass the name of an unsigned upload preset.

The method returns a stream, so for simplicity we wrap it in a Promise:

Using await:

For a video, set the resource_type parameter to video:

Using await:

The `upload_chunked` method

The upload_chunked method uploads a file to the cloud in chunks, which offers a degree of tolerance for network issues, particularly when uploading large files, like videos.

This method automatically sets to the resource_type parameter to image if you don't specify it.

Note

For any file larger than 20 GB you also need to set the async parameter 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.

The method returns a stream, so for simplicity we wrap it in a Promise:

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

You can change the chunk size using the chunk_size parameter. It's 20 MB by default, but you can set it as low as 5 MB. 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's returned after the final chunk is uploaded with done: true included in the response.

The `upload_chunked_stream` method

The upload_chunked_stream method uploads a file to the cloud in chunks, which offers a degree of tolerance for network issues, particularly when uploading large files, like videos. You can set the size of the chunks using the chunk_size parameter. This method also takes advantage of Node.js's stream functionality.

This method automatically sets to the resource_type parameter to image if you don't specify it.

The method returns a stream, so for simplicity we wrap it in a Promise:

The `upload_large` method

The upload_large method uploads a file to the cloud in chunks, which offers a degree of tolerance for network issues, particularly when uploading large files, like videos.

This method automatically sets to the resource_type parameter to raw if you don't specify it.

The method's return type depends on the input:

Remote URL: Returns a Promise<UploadApiResponse>
Local file path: Returns an UploadStream (already piped internally)

Note

Uploading from a remote URL (returns a Promise):

Uploading from a local file path (returns a Stream):

You can change the chunk size using the chunk_size parameter. It's 20 MB by default, but you can set it as low as 5 MB. For example, uploading a local video file with a custom chunk size:

Note

Upload response

By default, uploading is performed synchronously. Once finished, the uploaded image or video is immediately available for transformation and delivery. An upload call returns a Hash with content similar to the following:

The response includes HTTP and HTTPS URLs for accessing the uploaded media asset as well as additional information regarding the uploaded asset: The public ID, resource type, width and height, file format, file size in bytes, a signature for verifying the response and more.

Direct uploading from the browser

The upload methods mentioned above allow your server-side Node.js code to upload media assets to Cloudinary. In this flow, if you have a web form that allows your users to upload images or videos, the media file's data is first sent to your server and only then uploaded to Cloudinary.

A more efficient and powerful option is to allow your users to upload images and videos in your client-side code directly from the browser to Cloudinary instead of going through your servers. This method allows for faster uploading and a better user experience. It also reduces load from your servers and reduces the complexity of your Node.js applications.

You can upload directly from the browser using signed or unsigned calls to the upload endpoint, as shown in the Upload multiple files using a form examples.

For signed uploads from your client-side code, a secure signature must be generated in your server-side Node.js code. You can use the api_sign_request method to generate SHA signatures:

Error

Unfortunately there's been an error sending your feedback.

Rate this page: