Comprehensive file upload functionality for images, videos, and other assets. Supports various upload methods including streaming, chunked uploads for large files, and extensive configuration options for transformations, metadata, and organization.
Upload files to Cloudinary with various source types and options.
/**
* Upload a file to Cloudinary
* @param file - File path, URL, Buffer, or Stream
* @param options - Upload configuration options
* @param callback - Callback function (v1 only)
* @returns Promise with upload result (v2) or undefined (v1 with callback)
*/
function upload(
file: string | Buffer | NodeJS.ReadableStream,
options?: UploadOptions,
callback?: (error: any, result: UploadApiResponse) => void
): Promise<UploadApiResponse>;
interface UploadOptions {
/** Public ID for the uploaded asset */
public_id?: string;
/** Folder to organize the asset */
folder?: string;
/** Use original filename as public ID */
use_filename?: boolean;
/** Ensure filename uniqueness */
unique_filename?: boolean;
/** Resource type: auto-detect or specify */
resource_type?: 'image' | 'video' | 'raw' | 'auto';
/** Asset type/category */
type?: 'upload' | 'private' | 'authenticated';
/** Tags to assign to the asset */
tags?: string | string[];
/** Context metadata */
context?: string | Record<string, string>;
/** Transformations to apply during upload */
transformation?: TransformationOptions | TransformationOptions[];
/** Eager transformations to generate */
eager?: TransformationOptions | TransformationOptions[];
/** Generate eager transformations asynchronously */
eager_async?: boolean;
/** Notification URL for async operations */
notification_url?: string;
/** Upload preset for unsigned uploads */
upload_preset?: string;
/** Overwrite existing asset */
overwrite?: boolean;
/** Invalidate CDN cache */
invalidate?: boolean;
/** Backup the asset */
backup?: boolean;
/** Return deletion token */
return_delete_token?: boolean;
/** Asynchronous upload */
async?: boolean;
/** Custom metadata */
metadata?: Record<string, string>;
[key: string]: any;
}
interface UploadApiResponse {
/** Assigned public ID */
public_id: string;
/** Asset version */
version: number;
/** Upload signature */
signature: string;
/** Image/video width in pixels */
width: number;
/** Image/video height in pixels */
height: number;
/** File format */
format: string;
/** Resource type */
resource_type: string;
/** Creation timestamp */
created_at: string;
/** Assigned tags */
tags: string[];
/** File size in bytes */
bytes: number;
/** Asset type */
type: string;
/** ETag for caching */
etag: string;
/** Placeholder flag */
placeholder: boolean;
/** HTTP delivery URL */
url: string;
/** HTTPS delivery URL */
secure_url: string;
/** Access mode */
access_mode: string;
/** Original filename */
original_filename: string;
/** Moderation results */
moderation?: any[];
/** Access control settings */
access_control?: string[];
/** Context metadata */
context?: Record<string, string>;
/** Custom metadata */
metadata?: Record<string, string>;
/** Deletion token */
delete_token?: string;
[key: string]: any;
}Usage Examples:
const cloudinary = require('cloudinary');
// Basic upload
const result = await cloudinary.v2.uploader.upload('./image.jpg');
console.log(result.public_id, result.secure_url);
// Upload with options
const result = await cloudinary.v2.uploader.upload('./image.jpg', {
public_id: 'my_image',
folder: 'uploads',
tags: ['user_content', 'photos'],
context: { user_id: '123', category: 'profile' },
transformation: [
{ width: 500, height: 500, crop: 'fill' },
{ quality: 'auto', fetch_format: 'auto' }
]
});
// Upload from URL
const result = await cloudinary.v2.uploader.upload('https://example.com/image.jpg', {
public_id: 'remote_image'
});
// Upload with eager transformations
const result = await cloudinary.v2.uploader.upload('./image.jpg', {
eager: [
{ width: 300, height: 300, crop: 'fill' },
{ width: 150, height: 150, crop: 'thumb', gravity: 'face' }
],
eager_async: true
});Upload files using Node.js streams for better memory efficiency.
/**
* Create an upload stream
* @param options - Upload options
* @param callback - Callback function (v1 only)
* @returns Writable stream for piping data
*/
function upload_stream(
options?: UploadOptions,
callback?: (error: any, result: UploadApiResponse) => void
): NodeJS.WritableStream;Usage Examples:
const cloudinary = require('cloudinary');
const fs = require('fs');
// Stream upload
const uploadStream = cloudinary.v2.uploader.upload_stream(
{
public_id: 'streamed_image',
transformation: [{ width: 500, height: 500, crop: 'fill' }]
},
(error, result) => {
if (error) console.error(error);
else console.log(result.secure_url);
}
);
fs.createReadStream('./image.jpg').pipe(uploadStream);
// With promises using util.promisify
const { promisify } = require('util');
const streamUpload = (buffer, options) => {
return new Promise((resolve, reject) => {
const uploadStream = cloudinary.v2.uploader.upload_stream(
options,
(error, result) => {
if (error) reject(error);
else resolve(result);
}
);
uploadStream.end(buffer);
});
};
const result = await streamUpload(imageBuffer, { public_id: 'my_image' });Upload large files using chunked upload for better reliability and progress tracking.
/**
* Upload large files in chunks
* @param file_path - Path to the file
* @param options - Upload options with chunk size
* @param callback - Callback function (v1 only)
* @returns Promise with upload result or stream
*/
function upload_large(
file_path: string,
options?: UploadOptions & { chunk_size?: number },
callback?: (error: any, result: UploadApiResponse) => void
): Promise<UploadApiResponse>;
/**
* Create chunked upload stream
* @param options - Upload options with chunk size
* @param callback - Callback function (v1 only)
* @returns Writable stream for chunked upload
*/
function upload_chunked_stream(
options?: UploadOptions & { chunk_size?: number },
callback?: (error: any, result: UploadApiResponse) => void
): NodeJS.WritableStream;Usage Examples:
const cloudinary = require('cloudinary');
// Upload large file with chunking
const result = await cloudinary.v2.uploader.upload_large('./large_video.mp4', {
resource_type: 'video',
public_id: 'my_large_video',
chunk_size: 6000000, // 6MB chunks
eager: [
{ width: 640, height: 480, crop: 'fill', format: 'mp4' }
]
});
// Chunked stream upload
const chunkStream = cloudinary.v2.uploader.upload_chunked_stream({
resource_type: 'video',
public_id: 'streamed_large_video',
chunk_size: 6000000
}, (error, result) => {
if (error) console.error(error);
else console.log('Upload complete:', result.secure_url);
});
fs.createReadStream('./large_video.mp4').pipe(chunkStream);Upload without API credentials using upload presets.
/**
* Upload without API secret using upload preset
* @param file - File to upload
* @param upload_preset - Upload preset name
* @param options - Additional upload options
* @param callback - Callback function (v1 only)
* @returns Promise with upload result
*/
function unsigned_upload(
file: string | Buffer | NodeJS.ReadableStream,
upload_preset: string,
options?: UploadOptions,
callback?: (error: any, result: UploadApiResponse) => void
): Promise<UploadApiResponse>;
/**
* Create unsigned upload stream
* @param upload_preset - Upload preset name
* @param options - Additional upload options
* @param callback - Callback function (v1 only)
* @returns Writable stream for unsigned upload
*/
function unsigned_upload_stream(
upload_preset: string,
options?: UploadOptions,
callback?: (error: any, result: UploadApiResponse) => void
): NodeJS.WritableStream;Usage Examples:
const cloudinary = require('cloudinary');
// Unsigned upload using preset
const result = await cloudinary.v2.uploader.unsigned_upload('./image.jpg', 'my_upload_preset', {
tags: ['user_upload'],
context: { source: 'web_app' }
});
// Client-side unsigned upload (browser)
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('upload_preset', 'my_upload_preset');
formData.append('tags', 'user_content');
const response = await fetch('https://api.cloudinary.com/v1_1/demo/image/upload', {
method: 'POST',
body: formData
});
const result = await response.json();Apply transformations or update metadata for existing assets.
/**
* Apply explicit transformations to existing asset
* @param public_id - Public ID of existing asset
* @param options - Transformation and update options
* @param callback - Callback function (v1 only)
* @returns Promise with transformation result
*/
function explicit(
public_id: string,
options?: {
type?: string;
resource_type?: 'image' | 'video' | 'raw';
eager?: TransformationOptions | TransformationOptions[];
eager_async?: boolean;
notification_url?: string;
invalidate?: boolean;
[key: string]: any;
},
callback?: (error: any, result: any) => void
): Promise<any>;Usage Examples:
const cloudinary = require('cloudinary');
// Generate eager transformations for existing asset
const result = await cloudinary.v2.uploader.explicit('existing_image', {
type: 'upload',
eager: [
{ width: 300, height: 300, crop: 'fill' },
{ width: 150, height: 150, crop: 'thumb', gravity: 'face' }
]
});
// Update asset with new eager transformations
const result = await cloudinary.v2.uploader.explicit('my_video', {
resource_type: 'video',
eager: [
{ width: 640, height: 480, crop: 'fill', format: 'mp4' },
{ width: 320, height: 240, crop: 'fill', format: 'webm' }
],
eager_async: true
});Upload specific types of content with specialized processing.
/**
* Generate text overlay images
* @param text - Text content to render
* @param options - Text styling and upload options
* @param callback - Callback function (v1 only)
* @returns Promise with text image result
*/
function text(
text: string,
options?: {
public_id?: string;
font_family?: string;
font_size?: number;
font_color?: string;
font_weight?: string;
font_style?: string;
background?: string;
opacity?: number;
text_decoration?: string;
[key: string]: any;
},
callback?: (error: any, result: UploadApiResponse) => void
): Promise<UploadApiResponse>;Usage Examples:
const cloudinary = require('cloudinary');
// Generate text image
const textResult = await cloudinary.v2.uploader.text('Hello World!', {
public_id: 'hello_text',
font_family: 'Arial',
font_size: 48,
font_color: '#FF0000',
background: '#FFFFFF'
});
console.log('Text image URL:', textResult.secure_url);interface UploadOptions {
public_id?: string;
folder?: string;
use_filename?: boolean;
unique_filename?: boolean;
resource_type?: 'image' | 'video' | 'raw' | 'auto';
type?: 'upload' | 'private' | 'authenticated';
tags?: string | string[];
context?: string | Record<string, string>;
transformation?: TransformationOptions | TransformationOptions[];
eager?: TransformationOptions | TransformationOptions[];
eager_async?: boolean;
notification_url?: string;
upload_preset?: string;
overwrite?: boolean;
invalidate?: boolean;
backup?: boolean;
return_delete_token?: boolean;
async?: boolean;
metadata?: Record<string, string>;
chunk_size?: number;
[key: string]: any;
}
interface UploadApiResponse {
public_id: string;
version: number;
signature: string;
width: number;
height: number;
format: string;
resource_type: string;
created_at: string;
tags: string[];
bytes: number;
type: string;
etag: string;
placeholder: boolean;
url: string;
secure_url: string;
access_mode: string;
original_filename: string;
moderation?: any[];
access_control?: string[];
context?: Record<string, string>;
metadata?: Record<string, string>;
delete_token?: string;
[key: string]: any;
}
interface TransformationOptions {
width?: number | string;
height?: number | string;
crop?: string;
gravity?: string;
quality?: number | string;
format?: string;
fetch_format?: string;
effect?: string | string[];
angle?: number | string;
background?: string;
border?: string;
color?: string;
dpr?: number | string;
flags?: string | string[];
overlay?: string;
underlay?: string;
radius?: number | string;
opacity?: number | string;
[key: string]: any;
}