### Install Cloudinary Node SDK

Source: https://github.com/cloudinary/cloudinary_npm/blob/master/README.md

Install the Cloudinary Node.js SDK using npm.

```bash
npm install cloudinary
```

--------------------------------

### Setup and Configuration

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Configure the Cloudinary SDK using environment variables or by directly calling `cloudinary.config()` with your cloud credentials. You can also read or override individual configuration values.

```APIDOC
## Setup and Configuration

Configure the SDK using the `CLOUDINARY_URL` environment variable or by calling `cloudinary.config()` directly with `cloud_name`, `api_key`, and `api_secret`.

```js
const cloudinary = require('cloudinary').v2;

// Option 1: environment variable (recommended)
// CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME

// Option 2: programmatic config
cloudinary.config({
  cloud_name: 'my_cloud',
  api_key: '123456789012345',
  api_secret: 'abcdefghijklmnopqrstuvwxyz01',
  secure: true // always use HTTPS URLs
});

// Read a single config value
console.log(cloudinary.config().cloud_name); // 'my_cloud'

// Override a single value
cloudinary.config('secure', true);
```
```

--------------------------------

### Setup Cloudinary SDK

Source: https://github.com/cloudinary/cloudinary_npm/blob/master/README.md

Require the Cloudinary library to use its functionalities in your Node.js application.

```javascript
const cloudinary = require('cloudinary').v2
```

--------------------------------

### Get Asset Details using api.resource

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Retrieves detailed metadata for a single asset. Specify resource type and other options like colors, faces, and image metadata.

```javascript
const cloudinary = require('cloudinary').v2;

const info = await cloudinary.api.resource('sample', {
  resource_type: 'image',
  type: 'upload',
  colors: true,
  faces: true,
  image_metadata: true,
  exif: true,
  phash: true
});

console.log('Format:', info.format);
console.log('Dimensions:', info.width, 'x', info.height);
console.log('File size:', info.bytes, 'bytes');
console.log('Dominant colors:', info.colors);
```

--------------------------------

### Retrieve Account Usage Statistics with Cloudinary API

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Call `cloudinary.api.usage()` to get current account statistics for storage, bandwidth, and transformations. An optional `date` parameter can be provided to fetch historic usage for a specific day.

```javascript
const cloudinary = require('cloudinary').v2;

const usage = await cloudinary.api.usage();
console.log('Storage used:', usage.storage.usage, 'bytes');
console.log('Bandwidth used:', usage.bandwidth.usage, 'bytes');
console.log('Transformations:', usage.transformations.usage);

// Usage for a specific date
const historicUsage = await cloudinary.api.usage({ date: '2024-06-01' });
```

--------------------------------

### api.resource — Get Asset Details

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Retrieves detailed metadata for a single asset using its public ID. Supports fetching additional information like dominant colors, faces, image metadata, and EXIF data.

```APIDOC
## api.resource — Get Asset Details

### Description
Retrieves detailed metadata for a single asset.

### Method
`api.resource(public_id, options)`

### Parameters
#### Path Parameters
- **public_id** (string) - Required - The public ID of the asset.

#### Query Parameters
- **resource_type** (string) - Optional - The type of resource (e.g., 'image', 'video', 'raw'). Defaults to 'image'.
- **type** (string) - Optional - The type of upload (e.g., 'upload', 'private', 'authenticated'). Defaults to 'upload'.
- **colors** (boolean) - Optional - If true, analyzes and returns dominant colors.
- **faces** (boolean) - Optional - If true, detects and returns faces.
- **image_metadata** (boolean) - Optional - If true, returns image metadata.
- **exif** (boolean) - Optional - If true, returns EXIF data.
- **phash** (boolean) - Optional - If true, returns perceptual hash.

### Response
#### Success Response (200)
- **format** (string) - The format of the asset (e.g., 'jpg', 'png').
- **width** (integer) - The width of the asset in pixels.
- **height** (integer) - The height of the asset in pixels.
- **bytes** (integer) - The file size in bytes.
- **colors** (array) - An array of dominant colors if requested.

### Request Example
```javascript
const cloudinary = require('cloudinary').v2;

const info = await cloudinary.api.resource('sample', {
  resource_type: 'image',
  type: 'upload',
  colors: true,
  faces: true,
  image_metadata: true,
  exif: true,
  phash: true
});

console.log('Format:', info.format);
console.log('Dimensions:', info.width, 'x', info.height);
console.log('File size:', info.bytes, 'bytes');
console.log('Dominant colors:', info.colors);
```
```

--------------------------------

### Manage Cloudinary Sub-Accounts with Provisioning API

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Configures the SDK for multi-account provisioning and demonstrates creating sub-accounts, users, and user groups. Also shows how to list enabled sub-accounts.

```javascript
const cloudinary = require('cloudinary').v2;

// Configure with provisioning credentials
cloudinary.config({
  account_id: 'my_account_id',
  provisioning_api_key: 'prov_key',
  provisioning_api_secret: 'prov_secret'
});

const { account } = cloudinary.provisioning;

// Create a sub-account
const sub = await account.create_sub_account(
  'Acme Corp',         // display name
  'acme_corp_cloud',   // cloud name
  { plan: 'enterprise' },
  true                 // enabled
);
console.log('Sub-account ID:', sub.id);

// Create a user and assign to sub-account
const user = await account.create_user(
  'Jane Smith',
  'jane@acme.com',
  'technical_admin',
  [sub.id]
);

// Create a user group
const group = await account.create_user_group('Media Editors');
await account.add_user_to_group(group.id, user.id);

// List all sub-accounts
const { sub_accounts } = await account.sub_accounts(true); // enabled only
console.log(sub_accounts.map(s => s.cloud_name));
```

--------------------------------

### Configure Cloudinary Node SDK

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Configure the SDK using either the CLOUDINARY_URL environment variable or by directly calling cloudinary.config() with your cloud credentials. Programmatic configuration is useful for overriding specific settings like secure HTTPS usage.

```javascript
const cloudinary = require('cloudinary').v2;

// Option 1: environment variable (recommended)
// CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME

// Option 2: programmatic config
cloudinary.config({
  cloud_name: 'my_cloud',
  api_key: '123456789012345',
  api_secret: 'abcdefghijklmnopqrstuvwxyz01',
  secure: true // always use HTTPS URLs
});

// Read a single config value
console.log(cloudinary.config().cloud_name); // 'my_cloud'

// Override a single value
cloudinary.config('secure', true);
```

--------------------------------

### Folder Management

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Provides methods for listing, creating, renaming, and deleting folders in the media library.

```APIDOC
## api.root_folders / sub_folders / create_folder / delete_folder — Folder Management

### Description
Lists, creates, renames, and deletes folders in your media library.

### Method
`api.root_folders()`
`api.sub_folders(folder_path)`
`api.create_folder(path)`
`api.rename_folder(from_path, to_path)`
`api.delete_folder(path)`

### Parameters
#### `root_folders`
No parameters.

#### `sub_folders`
- **folder_path** (string) - Required - The path of the parent folder.

#### `create_folder`
- **path** (string) - Required - The path of the folder to create.

#### `rename_folder`
- **from_path** (string) - Required - The current path of the folder.
- **to_path** (string) - Required - The new path for the folder.

#### `delete_folder`
- **path** (string) - Required - The path of the folder to delete. Must be empty.

### Response
#### Success Response (200)
- **folders** (array) - An array of folder objects, each with `name` and `path` properties.

### Request Example
```javascript
const cloudinary = require('cloudinary').v2;

// List all root folders
const { folders } = await cloudinary.api.root_folders();
folders.forEach(f => console.log(f.name, f.path));

// List subfolders
const { folders: sub } = await cloudinary.api.sub_folders('products');

// Create a new empty folder
await cloudinary.api.create_folder('campaigns/2024/q1');

// Rename a folder
await cloudinary.api.rename_folder('campaigns/2024/q1', 'campaigns/2024/q1_archive');

// Delete a folder (must be empty)
await cloudinary.api.delete_folder('temp/scratch');
```
```

--------------------------------

### Create Video Slideshow using uploader.create_slideshow

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Generates a video slideshow from a set of images defined by a manifest. Ensure the manifest_json is correctly formatted with image media identifiers.

```javascript
const cloudinary = require('cloudinary').v2;

cloudinary.uploader.create_slideshow({
  manifest_json: {
    w: 640, h: 480,
    du: 6,
    slides: [
      { media: 'i:slide1' },
      { media: 'i:slide2' },
      { media: 'i:slide3' }
    ]
  },
  public_id: 'slideshows/intro_2024',
  overwrite: true,
  notification_url: 'https://myapp.com/webhooks/slideshow'
}, (result) => {
  if (result.error) console.error(result.error);
  else console.log('Slideshow public_id:', result.public_id);
});
```

--------------------------------

### Configure and Use Cloudinary Cache for Responsive Breakpoints

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Sets up a file-backed cache adapter for storing responsive image breakpoints. Uploads images with responsive breakpoints enabled and then retrieves cached breakpoint data.

```javascript
const cloudinary = require('cloudinary').v2;
const { Cache } = cloudinary;
const { KeyValueCacheAdapter } = require('cloudinary/lib/cache/KeyValueCacheAdapter');
const { FileKeyValueStorage } = require('cloudinary/lib/cache/FileKeyValueStorage');

// Set up a file-backed cache adapter
const storage = new FileKeyValueStorage('/tmp/cld_breakpoints_cache');
const adapter = new KeyValueCacheAdapter(storage);
Cache.setAdapter(adapter);

// Upload with responsive breakpoints; they are auto-cached
cloudinary.uploader.upload('hero.jpg', {
  responsive_breakpoints: [{
    create_derived: true,
    bytes_step: 20000,
    min_width: 200,
    max_width: 1000,
    max_images: 5
  }]
}).then(result => {
  // Retrieve cached breakpoints
  const cached = Cache.get('hero', { resource_type: 'image', type: 'upload' });
  console.log('Cached widths:', cached);
});
```

--------------------------------

### Generate Signed Archive Download URLs

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Create signed URLs for downloading ZIP archives of assets using `cloudinary.utils.download_zip_url` (for tags) or `cloudinary.utils.download_folder` (for folders). Set `expires_at` for time-limited access and configure options like `use_original_filename` and `flatten_folders`.

```javascript
const cloudinary = require('cloudinary').v2;

// ZIP by tag
const zipUrl = cloudinary.utils.download_zip_url({
  tags: ['campaign_assets'],
  resource_type: 'image',
  use_original_filename: true,
  flatten_folders: false,
  expires_at: Math.floor(Date.now() / 1000) + 3600
});
console.log('Download:', zipUrl);

// Download a whole folder
const folderZip = cloudinary.utils.download_folder('marketing/2024', {
  resource_type: 'all',
  target_format: 'zip'
});
```

--------------------------------

### api.create_upload_preset / update_upload_preset — Manage Upload Presets

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Creates centralized upload settings that can be referenced by name at upload time.

```APIDOC
## api.create_upload_preset / update_upload_preset — Manage Upload Presets

### Description
Creates centralized upload settings (transformations, moderation, folder, etc.) that can be referenced by name at upload time.

### Method
`api.create_upload_preset(options)`
`api.update_upload_preset(name, options)`
`api.delete_upload_preset(name)`

### Parameters
#### `create_upload_preset` and `update_upload_preset`
- **name** (string) - Optional (for create, required for update) - The name of the upload preset.
- **options** (object) - Required - Settings for the upload preset.
  - **unsigned** (boolean) - Optional - If true, allows unsigned uploads.
  - **folder** (string) - Optional - The folder to upload assets into.
  - **transformation** (object) - Optional - Default transformation to apply.
    - **width** (integer) - Optional.
    - **height** (integer) - Optional.
    - **crop** (string) - Optional.
    - **gravity** (string) - Optional.
  - **format** (string) - Optional - Default format.
  - **tags** (string/array) - Optional - Default tags.
  - **overwrite** (boolean) - Optional - If true, overwrites existing assets with the same public ID.
  - **moderation** (string) - Optional - Moderation type (e.g., 'manual', 'aws_rek').

#### `delete_upload_preset`
- **name** (string) - Required - The name of the upload preset to delete.

### Request Example
```javascript
const cloudinary = require('cloudinary').v2;

await cloudinary.api.create_upload_preset({
  name: 'profile_avatar',
  unsigned: false,
  folder: 'avatars',
  transformation: { width: 500, height: 500, crop: 'fill', gravity: 'face' },
  format: 'jpg',
  tags: 'avatar',
  overwrite: true,
  moderation: 'manual'
});

// Update it
await cloudinary.api.update_upload_preset('profile_avatar', {
  moderation: 'aws_rek'
});

// Delete it
await cloudinary.api.delete_upload_preset('profile_avatar');
```
```

--------------------------------

### uploader.create_slideshow

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Generates a video slideshow from a set of images defined by a manifest. This method allows for customization of slideshow properties and provides a callback for handling the result.

```APIDOC
## uploader.create_slideshow — Create a Video Slideshow

Generates a video slideshow from a set of images defined by a manifest.

```js
const cloudinary = require('cloudinary').v2;

cloudinary.uploader.create_slideshow({
  manifest_json: {
    w: 640, h: 480,
    du: 6,
    slides: [
      { media: 'i:slide1' },
      { media: 'i:slide2' },
      { media: 'i:slide3' }
    ]
  },
  public_id: 'slideshows/intro_2024',
  overwrite: true,
  notification_url: 'https://myapp.com/webhooks/slideshow'
}, (result) => {
  if (result.error) console.error(result.error);
  else console.log('Slideshow public_id:', result.public_id);
});
```
```

--------------------------------

### Create a ZIP Archive from Assets

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Generates a ZIP archive from assets identified by tags, public IDs, or prefixes. Options include specifying resource type, target public ID, and filename handling.

```javascript
const cloudinary = require('cloudinary').v2;

// Create a ZIP of all images tagged 'product_launch'
cloudinary.uploader.create_zip({
  tags: 'product_launch',
  resource_type: 'image',
  target_public_id: 'archives/product_launch_pack',
  use_original_filename: true,
  flatten_folders: false
})
  .then(result => {
    console.log('Archive URL:', result.url);
    console.log('File count:', result.file_count);
  })
  .catch(console.error);
```

--------------------------------

### Account Usage Stats

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Returns current usage statistics for the account, including storage, bandwidth, and transformations. Can fetch usage for a specific date.

```APIDOC
## api.usage — Account Usage Stats

Returns current usage statistics for the account (storage, bandwidth, transformations, etc.).

```js
const cloudinary = require('cloudinary').v2;

const usage = await cloudinary.api.usage();
console.log('Storage used:', usage.storage.usage, 'bytes');
console.log('Bandwidth used:', usage.bandwidth.usage, 'bytes');
console.log('Transformations:', usage.transformations.usage);

// Usage for a specific date
const historicUsage = await cloudinary.api.usage({ date: '2024-06-01' });
```
```

--------------------------------

### Upload a File using uploader.upload

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Uploads local files, remote URLs, base64 data URIs, or Buffers to Cloudinary. Use the .then() Promise pattern or async/await for handling upload results and errors. Options include public_id, folder, overwrite, tags, and transformations.

```javascript
const cloudinary = require('cloudinary').v2;

// Upload from local path
cloudinary.uploader.upload('/tmp/photo.jpg', {
  public_id: 'profile/user_123',
  folder: 'avatars',
  overwrite: true,
  tags: ['profile', 'user'],
  transformation: { width: 400, height: 400, crop: 'fill', gravity: 'face' }
})
  .then(result => {
    console.log(result.public_id);   // 'avatars/profile/user_123'
    console.log(result.secure_url);  // 'https://res.cloudinary.com/...' 
    console.log(result.width);       // 400
  })
  .catch(err => console.error(err));

// Upload from remote URL with async/await
async function uploadRemote() {
  try {
    const result = await cloudinary.uploader.upload(
      'https://example.com/banner.png',
      { resource_type: 'image', tags: 'banner', format: 'webp' }
    );
    return result.secure_url;
  } catch (err) {
    console.error('Upload failed:', err.message);
  }
}
```

--------------------------------

### Folder Management

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Manages folders in your media library, including listing root and subfolders, creating new folders, renaming existing ones, and deleting empty folders.

```javascript
const cloudinary = require('cloudinary').v2;

// List all root folders
const { folders } = await cloudinary.api.root_folders();
folders.forEach(f => console.log(f.name, f.path));

// List subfolders
const { folders: sub } = await cloudinary.api.sub_folders('products');

// Create a new empty folder
await cloudinary.api.create_folder('campaigns/2024/q1');

// Rename a folder
await cloudinary.api.rename_folder('campaigns/2024/q1', 'campaigns/2024/q1_archive');

// Delete a folder (must be empty)
await cloudinary.api.delete_folder('temp/scratch');
```

--------------------------------

### Manage Upload Presets

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Creates, updates, and deletes upload presets to define centralized upload settings. These presets can be referenced by name during the upload process.

```javascript
const cloudinary = require('cloudinary').v2;

await cloudinary.api.create_upload_preset({
  name: 'profile_avatar',
  unsigned: false,
  folder: 'avatars',
  transformation: { width: 500, height: 500, crop: 'fill', gravity: 'face' },
  format: 'jpg',
  tags: 'avatar',
  overwrite: true,
  moderation: 'manual'
});

// Update it
await cloudinary.api.update_upload_preset('profile_avatar', {
  moderation: 'aws_rek'
});

// Delete it
await cloudinary.api.delete_upload_preset('profile_avatar');
```

--------------------------------

### List Assets using api.resources

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Retrieves a paginated list of assets in your Cloudinary account. Supports filtering by resource type, tag, prefix, or folder, and pagination using next_cursor.

```javascript
const cloudinary = require('cloudinary').v2;

// List the 10 most recently uploaded images
const result = await cloudinary.api.resources({
  resource_type: 'image',
  type: 'upload',
  max_results: 10,
  tags: true,
  context: true,
  direction: 'desc'
});
result.resources.forEach(r => console.log(r.public_id, r.created_at));
```

```javascript
// Paginate with next_cursor
if (result.next_cursor) {
  const page2 = await cloudinary.api.resources({ next_cursor: result.next_cursor, max_results: 10 });
}
```

```javascript
// List resources by tag
const tagged = await cloudinary.api.resources_by_tag('summer', { max_results: 50, tags: true });
```

```javascript
// List resources in a specific asset folder
const folderAssets = await cloudinary.api.resources_by_asset_folder('marketing/2024');
```

--------------------------------

### URL Generation with Transformations

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

The core URL builder. Accepts a public ID and an options hash to produce a fully signed or unsigned delivery URL with any transformation pipeline.

```APIDOC
## utils.url / cloudinary.url — URL Generation with Transformations

The core URL builder. Accepts a public ID and an options hash to produce a fully signed or unsigned delivery URL with any transformation pipeline.

```js
const cloudinary = require('cloudinary').v2;

// Multiple chained transformations
const url = cloudinary.url('sample', {
  transformation: [
    { width: 500, crop: 'scale' },
    { quality: 'auto', fetch_format: 'auto' },
    { effect: 'art:daguerre', border: '3px_solid_rgb:00390b', radius: 20 }
  ],
  secure: true
});

// Signed URL with SHA-256
const signedUrl = cloudinary.url('confidential/doc', {
  resource_type: 'raw',
  sign_url: true,
  long_url_signature: true,  // 32-char SHA-256 signature
  type: 'authenticated',
  expires_at: Math.floor(Date.now() / 1000) + 3600
});

// Private download URL for a raw file
const downloadUrl = cloudinary.utils.private_download_url(
  'reports/q3_2024',
  'pdf',
  { attachment: true, expires_at: Math.floor(Date.now() / 1000) + 3600 }
);
```
```

--------------------------------

### provisioning.account

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Provides an API for managing sub-accounts, users, user groups, and access keys within a Cloudinary account that utilizes the multi-account provisioning feature.

```APIDOC
## provisioning.account — Multi-Account Provisioning API

Manages sub-accounts, users, user groups, and access keys for Cloudinary accounts that use the provisioning (multi-tenant) feature.

```js
const cloudinary = require('cloudinary').v2;

// Configure with provisioning credentials
cloudinary.config({
  account_id: 'my_account_id',
  provisioning_api_key: 'prov_key',
  provisioning_api_secret: 'prov_secret'
});

const { account } = cloudinary.provisioning;

// Create a sub-account
const sub = await account.create_sub_account(
  'Acme Corp',         // display name
  'acme_corp_cloud',   // cloud name
  { plan: 'enterprise' },
  true                 // enabled
);
console.log('Sub-account ID:', sub.id);

// Create a user and assign to sub-account
const user = await account.create_user(
  'Jane Smith',
  'jane@acme.com',
  'technical_admin',
  [sub.id]
);

// Create a user group
const group = await account.create_user_group('Media Editors');
await account.add_user_to_group(group.id, user.id);

// List all sub-accounts
const { sub_accounts } = await account.sub_accounts(true); // enabled only
console.log(sub_accounts.map(s => s.cloud_name));
```
```

--------------------------------

### uploader.create_archive / create_zip

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Generates a ZIP archive (or other specified formats) from a collection of assets. Assets can be identified by tags, public IDs, or prefixes. The archive can be stored or a download URL can be provided.

```APIDOC
## uploader.create_archive / create_zip — Create a ZIP Archive

Generates a ZIP (or other format) archive from a set of assets identified by tags, public IDs, or prefixes, and stores it or returns a download URL.

```js
const cloudinary = require('cloudinary').v2;

// Create a ZIP of all images tagged 'product_launch'
cloudinary.uploader.create_zip({
  tags: 'product_launch',
  resource_type: 'image',
  target_public_id: 'archives/product_launch_pack',
  use_original_filename: true,
  flatten_folders: false
})
  .then(result => {
    console.log('Archive URL:', result.url);
    console.log('File count:', result.file_count);
  })
  .catch(console.error);
```
```

--------------------------------

### api.resources

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Retrieves a paginated list of assets in your Cloudinary account, filtered by resource type, delivery type, tag, prefix, or folder. Supports pagination using `next_cursor`.

```APIDOC
## api.resources — List Assets

Retrieves a paginated list of assets in your Cloudinary account, filtered by resource type, delivery type, tag, prefix, or folder.

```js
const cloudinary = require('cloudinary').v2;

// List the 10 most recently uploaded images
const result = await cloudinary.api.resources({
  resource_type: 'image',
  type: 'upload',
  max_results: 10,
  tags: true,
  context: true,
  direction: 'desc'
});
result.resources.forEach(r => console.log(r.public_id, r.created_at));

// Paginate with next_cursor
if (result.next_cursor) {
  const page2 = await cloudinary.api.resources({ next_cursor: result.next_cursor, max_results: 10 });
}

// List resources by tag
const tagged = await cloudinary.api.resources_by_tag('summer', { max_results: 50, tags: true });

// List resources in a specific asset folder
const folderAssets = await cloudinary.api.resources_by_asset_folder('marketing/2024');
```
```

--------------------------------

### Generate HTML video Tag using cloudinary.video

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Produces an HTML <video> tag with multiple <source> elements for different formats. Includes options for poster images, controls, and fallback content.

```javascript
const cloudinary = require('cloudinary').v2;

const videoTag = cloudinary.video('dog', {
  source_types: ['mp4', 'webm'],
  width: 640, height: 360, crop: 'fill',
  poster: { effect: 'blur:300', quality: 30 },
  controls: true,
  fallback_content: 'Your browser does not support HTML5 video'
});
/*
<video width='640' height='360' controls poster='...'>
  <source src='https://.../dog.mp4' type='video/mp4'>
  <source src='https://.../dog.webm' type='video/webm'>
  Your browser does not support HTML5 video
</video>
*/
```

--------------------------------

### Generate Transformation URL using cloudinary.url

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Builds a Cloudinary delivery URL for an image or video with transformations. Supports chained transformations and signed URLs for private assets.

```javascript
const cloudinary = require('cloudinary').v2;

// Resize and crop to 300×200, convert to WebP
const imageUrl = cloudinary.url('sample', {
  width: 300, height: 200, crop: 'fill', gravity: 'auto',
  fetch_format: 'auto', quality: 'auto',
  secure: true
});
// => https://res.cloudinary.com/mycloud/image/upload/c_fill,g_auto,h_200,w_300/f_auto,q_auto/sample
```

```javascript
// Chained transformations: first scale, then add a text overlay
const bannerUrl = cloudinary.url('hero_bg', {
  transformation: [
    { width: 1200, crop: 'scale' },
    {
      overlay: { font_family: 'Arial', font_size: 48, text: 'Hello World' },
      color: '#FFFFFF', gravity: 'south', y: 30
    }
  ],
  secure: true
});
```

```javascript
// Signed URL
const signedUrl = cloudinary.url('private_doc', {
  resource_type: 'raw',
  sign_url: true,
  type: 'authenticated'
});
```

--------------------------------

### cloudinary.image

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Produces an HTML `<img>` tag with a Cloudinary URL, supporting responsive images and automatic DPR. Allows for various transformations and attributes to be applied.

```APIDOC
## cloudinary.image — Generate an HTML img Tag

Produces an HTML `<img>` tag with a Cloudinary URL, supporting responsive images and automatic DPR.

```js
const cloudinary = require('cloudinary').v2;

// Simple image tag
const tag = cloudinary.image('sample', {
  width: 400, height: 300, crop: 'fill',
  alt: 'A sample image',
  class: 'hero-image'
});
// => <img src='https://res.cloudinary.com/.../sample' width='400' height='300' alt='A sample image' class='hero-image'/>

// Responsive image using srcset
const responsiveTag = cloudinary.image('banner', {
  srcset: { sizes: [320, 640, 1024, 1280], breakpoints: true },
  sizes: '(max-width: 600px) 100vw, 50vw',
  crop: 'fill', gravity: 'auto'
});
```
```

--------------------------------

### Generate Cloudinary URLs with Transformations

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Use `cloudinary.url` to construct delivery URLs for assets, applying chained transformations for image manipulation. For private assets, `sign_url`, `long_url_signature`, `type: 'authenticated'`, and `expires_at` are crucial for security.

```javascript
const cloudinary = require('cloudinary').v2;

// Multiple chained transformations
const url = cloudinary.url('sample', {
  transformation: [
    { width: 500, crop: 'scale' },
    { quality: 'auto', fetch_format: 'auto' },
    { effect: 'art:daguerre', border: '3px_solid_rgb:00390b', radius: 20 }
  ],
  secure: true
});

// Signed URL with SHA-256
const signedUrl = cloudinary.url('confidential/doc', {
  resource_type: 'raw',
  sign_url: true,
  long_url_signature: true,  // 32-char SHA-256 signature
  type: 'authenticated',
  expires_at: Math.floor(Date.now() / 1000) + 3600
});

// Private download URL for a raw file
const downloadUrl = cloudinary.utils.private_download_url(
  'reports/q3_2024',
  'pdf',
  { attachment: true, expires_at: Math.floor(Date.now() / 1000) + 3600 }
);
```

--------------------------------

### Generate Responsive picture Tag using cloudinary.picture

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Generates a <picture> element with <source> tags for different viewport sizes, each with distinct transformations. Useful for art direction.

```javascript
const cloudinary = require('cloudinary').v2;

const pictureHtml = cloudinary.picture('landscape', {
  sources: [
    { min_width: 1600, transformation: { crop: 'fill', width: 1600, aspect_ratio: '16:9' } },
    { min_width: 900,  transformation: { crop: 'fill', width: 900,  aspect_ratio: '4:3' } },
    { transformation:  { crop: 'fill', width: 480, aspect_ratio: '1:1' } }
  ],
  crop: 'fill',
  width: 480
});
```

--------------------------------

### Large/Chunked Upload

Source: https://github.com/cloudinary/cloudinary_npm/blob/master/README.md

Upload large files using chunked uploading. Configure the chunk size for efficient transfer. Errors are logged to the console.

```javascript
   cloudinary.v2.uploader.upload_large(LARGE_RAW_FILE, {
          chunk_size: 7000000
        }, (error, result) => {console.log(error)});
```

--------------------------------

### Advanced Asset Search using api.search

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Executes structured Elasticsearch-style searches using the fluent `Search` builder or `api.search`. Supports sorting, limiting results, and field selection.

```javascript
const cloudinary = require('cloudinary').v2;

// Using the fluent Search API (v2)
const result = await cloudinary.search
  .expression('tags=summer AND resource_type=image AND bytes>500000')
  .sort_by('created_at', 'desc')
  .max_results(25)
  .with_field('tags')
  .with_field('context')
  .aggregate('resource_type')
  .execute();

result.resources.forEach(r => {
  console.log(r.public_id, r.tags, r.context);
});
console.log('Total:', result.total_count);

// Generate a shareable search URL (no credentials required at access time)
const url = cloudinary.search
  .expression('folder=products/*')
  .sort_by('public_id', 'asc')
  .to_url(300); // TTL in seconds
console.log('Search URL:', url);
```

--------------------------------

### cloudinary.video

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Produces an HTML `<video>` tag with multiple `<source>` elements for different formats (mp4, webm, ogv). Supports various video transformations and attributes.

```APIDOC
## cloudinary.video — Generate an HTML video Tag

Produces an HTML `<video>` tag with multiple `<source>` elements for different formats (mp4, webm, ogv).

```js
const cloudinary = require('cloudinary').v2;

const videoTag = cloudinary.video('dog', {
  source_types: ['mp4', 'webm'],
  width: 640, height: 360, crop: 'fill',
  poster: { effect: 'blur:300', quality: 30 },
  controls: true,
  fallback_content: 'Your browser does not support HTML5 video'
});
/*
<video width='640' height='360' controls poster='...'>
  <source src='https://.../dog.mp4' type='video/mp4'>
  <source src='https://.../dog.webm' type='video/webm'>
  Your browser does not support HTML5 video
</video>
*/
```
```

--------------------------------

### uploader.add_context, remove_all_context

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Manage contextual metadata for assets. You can add key-value pairs of context or remove all existing context from multiple assets.

```APIDOC
## uploader.add_context / remove_all_context — Manage Contextual Metadata

Attaches or removes free-form key=value contextual metadata from assets.

```js
const cloudinary = require('cloudinary').v2;

const ids = ['products/shirt_blue', 'products/shirt_red'];

// Add context key/value pairs
await cloudinary.uploader.add_context(
  { photographer: 'Jane Doe', location: 'Studio A', season: 'AW24' },
  ids
);

// Remove all context from the assets
await cloudinary.uploader.remove_all_context(ids);
```
```

--------------------------------

### Signed Archive Download URL

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Generates a signed URL that, when visited, creates and streams a ZIP (or other archive) of specified assets. Supports downloading by tags or entire folders.

```APIDOC
## utils.download_archive_url / download_zip_url — Signed Archive Download URL

Generates a signed URL that, when visited, creates and streams a ZIP (or other archive) of specified assets.

```js
const cloudinary = require('cloudinary').v2;

// ZIP by tag
const zipUrl = cloudinary.utils.download_zip_url({
  tags: ['campaign_assets'],
  resource_type: 'image',
  use_original_filename: true,
  flatten_folders: false,
  expires_at: Math.floor(Date.now() / 1000) + 3600
});
console.log('Download:', zipUrl);

// Download a whole folder
const folderZip = cloudinary.utils.download_folder('marketing/2024', {
  resource_type: 'all',
  target_format: 'zip'
});
```
```

--------------------------------

### api.search / Search class — Advanced Asset Search

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Executes advanced searches across the media library using a fluent search builder or the `api.search` method.

```APIDOC
## api.search / Search class — Advanced Asset Search

### Description
Executes a structured Elasticsearch-style search across your media library using the fluent `Search` builder (v2) or `api.search`.

### Method
`cloudinary.search.expression(expression).sort_by(field, direction).max_results(count).with_field(field).aggregate(field).execute()`
`cloudinary.search.expression(expression).sort_by(field, direction).to_url(ttl)`

### Parameters
#### Expression
- **expression** (string) - Required - The search query string (e.g., 'tags=summer AND resource_type=image').

#### Sorting
- **sort_by(field, direction)**
  - **field** (string) - The field to sort by (e.g., 'created_at', 'public_id').
  - **direction** (string) - The sort direction ('asc' or 'desc').

#### Results Control
- **max_results(count)**
  - **count** (integer) - The maximum number of results to return.

#### Field Selection
- **with_field(field)**
  - **field** (string) - The field to include in the results (e.g., 'tags', 'context').

#### Aggregation
- **aggregate(field)**
  - **field** (string) - The field to aggregate on (e.g., 'resource_type').

#### URL Generation
- **to_url(ttl)**
  - **ttl** (integer) - The time-to-live in seconds for the shareable search URL.

### Response
#### Success Response (200)
- **resources** (array) - An array of asset objects matching the search criteria.
- **total_count** (integer) - The total number of assets matching the search criteria.

### Request Example
```javascript
const cloudinary = require('cloudinary').v2;

// Using the fluent Search API (v2)
const result = await cloudinary.search
  .expression('tags=summer AND resource_type=image AND bytes>500000')
  .sort_by('created_at', 'desc')
  .max_results(25)
  .with_field('tags')
  .with_field('context')
  .aggregate('resource_type')
  .execute();

result.resources.forEach(r => {
  console.log(r.public_id, r.tags, r.context);
});
console.log('Total:', result.total_count);

// Generate a shareable search URL (no credentials required at access time)
const url = cloudinary.search
  .expression('folder=products/*')
  .sort_by('public_id', 'asc')
  .to_url(300); // TTL in seconds
console.log('Search URL:', url);
```
```

--------------------------------

### uploader.add_tag, remove_tag, replace_tag, remove_all_tags

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Manage asset tags in bulk. These methods allow adding new tags, removing specific tags, replacing all existing tags with new ones, or removing all tags from multiple assets.

```APIDOC
## uploader.add_tag / remove_tag / replace_tag — Manage Asset Tags

Bulk-add, remove, or replace tags on multiple assets identified by their public IDs.

```js
const cloudinary = require('cloudinary').v2;

const ids = ['photos/beach_1', 'photos/beach_2', 'photos/beach_3'];

// Add a tag
await cloudinary.uploader.add_tag('summer', ids);

// Remove one tag
await cloudinary.uploader.remove_tag('draft', ids);

// Replace all tags on the assets
await cloudinary.uploader.replace_tag('published,summer', ids);

// Remove every tag
await cloudinary.uploader.remove_all_tags(ids);
```
```

--------------------------------

### Manage Contextual Metadata

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Attaches or removes free-form key=value contextual metadata from assets. Use 'add_context' to add new metadata or update existing values.

```javascript
const cloudinary = require('cloudinary').v2;

const ids = ['products/shirt_blue', 'products/shirt_red'];

// Add context key/value pairs
await cloudinary.uploader.add_context(
  { photographer: 'Jane Doe', location: 'Studio A', season: 'AW24' },
  ids
);

// Remove all context from the assets
await cloudinary.uploader.remove_all_context(ids);
```

--------------------------------

### Apply Eager Transformations and Update Asset Details

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Applies transformations, updates tags, context, or triggers add-ons on an existing asset without re-uploading. The 'eager' option generates transformations on the server.

```javascript
const cloudinary = require('cloudinary').v2;

cloudinary.uploader.explicit('sample_image', {
  type: 'upload',
  eager: [
    { width: 300, height: 300, crop: 'pad', background: 'auto' },
    { width: 160, height: 160, crop: 'fill', gravity: 'face', radius: 'max', format: 'png' }
  ],
  tags: ['processed', 'thumbnail_ready'],
  context: { alt: 'A sample image', caption: 'Demo photo' }
})
  .then(result => console.log(result.eager[0].secure_url))
  .catch(console.error);
```

--------------------------------

### cloudinary.url

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Builds a Cloudinary delivery URL for an image or video with any combination of transformations, without making a network request. Supports chained transformations and signed URLs.

```APIDOC
## cloudinary.url — Generate a Transformation URL

Builds a Cloudinary delivery URL for an image or video with any combination of transformations, without making a network request.

```js
const cloudinary = require('cloudinary').v2;

// Resize and crop to 300×200, convert to WebP
const imageUrl = cloudinary.url('sample', {
  width: 300, height: 200, crop: 'fill', gravity: 'auto',
  fetch_format: 'auto', quality: 'auto',
  secure: true
});
// => https://res.cloudinary.com/mycloud/image/upload/c_fill,g_auto,h_200,w_300/f_auto,q_auto/sample

// Chained transformations: first scale, then add a text overlay
const bannerUrl = cloudinary.url('hero_bg', {
  transformation: [
    { width: 1200, crop: 'scale' },
    {
      overlay: { font_family: 'Arial', font_size: 48, text: 'Hello World' },
      color: '#FFFFFF', gravity: 'south', y: 30
    }
  ],
  secure: true
});

// Signed URL
const signedUrl = cloudinary.url('private_doc', {
  resource_type: 'raw',
  sign_url: true,
  type: 'authenticated'
});
```
```

--------------------------------

### Generate HTML img Tag using cloudinary.image

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Produces an HTML <img> tag with a Cloudinary URL. Supports responsive images using srcset and automatic DPR.

```javascript
const cloudinary = require('cloudinary').v2;

// Simple image tag
const tag = cloudinary.image('sample', {
  width: 400, height: 300, crop: 'fill',
  alt: 'A sample image',
  class: 'hero-image'
});
// => <img src='https://res.cloudinary.com/.../sample' width='400' height='300' alt='A sample image' class='hero-image'/>
```

```javascript
// Responsive image using srcset
const responsiveTag = cloudinary.image('banner', {
  srcset: { sizes: [320, 640, 1024, 1280], breakpoints: true },
  sizes: '(max-width: 600px) 100vw, 50vw',
  crop: 'fill', gravity: 'auto'
});
```

--------------------------------

### Manage Named Transformations

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Creates, updates, and deletes named transformations. These can be referenced by name in delivery URLs for consistent image/video processing.

```javascript
const cloudinary = require('cloudinary').v2;

// Create a named transformation
await cloudinary.api.create_transformation('thumbnail_square', {
  width: 150, height: 150, crop: 'fill', gravity: 'face',
  radius: 'max', format: 'png', background: 'transparent'
});

// Update it to allow strict use
await cloudinary.api.update_transformation('thumbnail_square', {
  allowed_for_strict: true
});

// Use in a URL
console.log(cloudinary.url('user_photo', { transformation: 'thumbnail_square' }));

// Delete it
await cloudinary.api.delete_transformation('thumbnail_square');
```

--------------------------------

### Stream Upload using uploader.upload_stream

Source: https://context7.com/cloudinary/cloudinary_npm/llms.txt

Creates a writable stream for piping file data directly to Cloudinary. This is efficient for in-memory Buffers or when data arrives as a stream. A Promise wrapper can be used for easier async handling.

```javascript
const cloudinary = require('cloudinary').v2;
const fs = require('fs');

// Using a Promise wrapper around the stream
function uploadFromBuffer(buffer, options = {}) {
  return new Promise((resolve, reject) => {
    const stream = cloudinary.uploader.upload_stream(options, (err, result) => {
      if (err) return reject(err);
      resolve(result);
    });
    stream.end(buffer);
  });
}

// Usage: upload from an in-memory Buffer
const buf = fs.readFileSync('/tmp/video.mp4');
uploadFromBuffer(buf, { resource_type: 'video', public_id: 'intro_video' })
  .then(result => console.log(result.secure_url))
  .catch(console.error);

// Pipe a read stream directly
fs.createReadStream('/tmp/large_image.jpg')
  .pipe(cloudinary.uploader.upload_stream({ tags: 'streamed' }, (err, result) => {
    if (err) console.error(err);
    else console.log(result.public_id);
  }));
```