or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

admin-api.mdanalysis.mdconfiguration.mdhtml-generation.mdindex.mdprovisioning.mdsearch.mdupload.mdurl-generation.md
tile.json

index.mddocs/

Cloudinary

Cloudinary is a comprehensive cloud-based media management solution that provides a complete suite of APIs for uploading, transforming, managing, and delivering images and videos. The Node.js SDK offers both callback-based (v1) and Promise-based (v2) interfaces for seamless integration into modern applications.

Package Information

  • Package Name: cloudinary
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install cloudinary

Core Imports

const cloudinary = require('cloudinary');

ES6/TypeScript:

import * as cloudinary from 'cloudinary';
// Or import specific modules
import { v2 as cloudinary } from 'cloudinary';

Basic Usage

import { v2 as cloudinary } from 'cloudinary';

// Configure your account
cloudinary.config({
  cloud_name: 'your_cloud_name',
  api_key: 'your_api_key',
  api_secret: 'your_api_secret'
});

// Upload an image
const uploadResult = await cloudinary.uploader.upload('./sample.jpg', {
  public_id: 'my_image',
  transformation: [
    { width: 300, height: 300, crop: 'fill' },
    { quality: 'auto', fetch_format: 'auto' }
  ]
});

// Generate optimized URL
const optimizedUrl = cloudinary.url('my_image', {
  width: 400,
  height: 300,
  crop: 'fill',
  quality: 'auto',
  fetch_format: 'auto'
});

// Generate HTML image tag
const imageTag = cloudinary.image('my_image', {
  width: 400,
  height: 300,
  crop: 'fill'
});

Architecture

Cloudinary's Node.js SDK is organized around several key components:

  • Configuration System: Global and per-request configuration management
  • URL Generation: Powerful URL building with transformation parameters
  • Upload API: File upload with various methods (stream, chunked, direct)
  • Admin API: Resource management and metadata operations
  • Transformation Engine: Comprehensive image and video processing
  • HTML Helpers: Optimized tag generation for web delivery
  • V2 Promise Interface: Modern async/await compatible API

Capabilities

Configuration and Setup

Global configuration management and environment-based setup for Cloudinary credentials and settings.

function config(options?: ConfigOptions): ConfigOptions;

interface ConfigOptions {
  cloud_name?: string;
  api_key?: string;
  api_secret?: string;
  secure?: boolean;
  cdn_subdomain?: boolean;
  private_cdn?: boolean;
  secure_distribution?: string;
  [key: string]: any;
}

Configuration

URL Generation and Transformations

Core URL generation with comprehensive transformation parameters for images and videos, including cropping, resizing, effects, and format optimization.

function url(public_id: string, options?: TransformationOptions): string;

interface TransformationOptions {
  width?: number | string;
  height?: number | string;
  crop?: 'scale' | 'fit' | 'limit' | 'fill' | 'lfill' | 'pad' | 'lpad' | 'mpad' | 'crop' | 'thumb';
  gravity?: 'auto' | 'face' | 'faces' | 'center' | 'north' | 'south' | 'east' | 'west';
  quality?: number | string | 'auto';
  format?: string;
  fetch_format?: 'auto' | string;
  effect?: string | string[];
  angle?: number | string | 'auto_right' | 'auto_left';
  [key: string]: any;
}

URL Generation

File Upload

Comprehensive file upload capabilities including streaming uploads, chunked uploads for large files, and various upload methods with extensive configuration options.

function upload(
  file: string | Buffer | Stream,
  options?: UploadOptions,
  callback?: (error: any, result: UploadApiResponse) => void
): Promise<UploadApiResponse>;

interface UploadOptions {
  public_id?: string;
  folder?: string;
  use_filename?: boolean;
  unique_filename?: boolean;
  resource_type?: 'image' | 'video' | 'raw' | 'auto';
  transformation?: TransformationOptions;
  tags?: string | string[];
  context?: string | object;
  [key: string]: any;
}

interface UploadApiResponse {
  public_id: string;
  version: number;
  signature: string;
  width: number;
  height: number;
  format: string;
  resource_type: string;
  url: string;
  secure_url: string;
  [key: string]: any;
}

Upload API

Admin API

Administrative operations for managing resources, including listing, updating, deleting, and organizing assets with comprehensive metadata management.

function resources(
  options?: ResourceOptions,
  callback?: (error: any, result: ResourceApiResponse) => void
): Promise<ResourceApiResponse>;

function resource(
  public_id: string,
  options?: ResourceOptions,
  callback?: (error: any, result: any) => void
): Promise<any>;

interface ResourceOptions {
  type?: string;
  resource_type?: 'image' | 'video' | 'raw';
  max_results?: number;
  next_cursor?: string;
  tags?: boolean;
  context?: boolean;
  [key: string]: any;
}

Admin API

HTML Tag Generation

Generate optimized HTML tags (img, video, picture) with responsive attributes, lazy loading, and automatic format selection for web delivery.

function image(
  public_id: string,
  options?: ImageTagOptions
): string;

function video(
  public_id: string,
  options?: VideoTagOptions
): string;

interface ImageTagOptions extends TransformationOptions {
  responsive?: boolean;
  hidpi?: boolean;
  client_hints?: boolean;
  srcset?: object;
  attributes?: object;
  [key: string]: any;
}

HTML Generation

Search API

Advanced search capabilities with fluent query builder for finding resources based on various criteria including tags, metadata, and asset properties.

interface Search {
  expression(value: string): Search;
  max_results(value: number): Search;
  next_cursor(value: string): Search;
  sort_by(key: string, value: 'asc' | 'desc'): Search;
  aggregate(value: string): Search;
  with_field(value: string | string[]): Search;
  execute(): Promise<any>;
}

const search: {
  expression(value: string): Search;
  instance(): Search;
}

Search API

Analysis API

AI-powered content analysis for automatic tagging, moderation, object detection, and content understanding using various analysis models.

function analyze_uri(
  uri: string,
  analysis_type: 'google_tagging' | 'coco' | 'captioning' | 'custom',
  options?: AnalysisOptions
): Promise<AnalysisResponse>;

interface AnalysisOptions {
  model_name?: string;
  model_version?: number;
  [key: string]: any;
}

Analysis API

Provisioning API

Enterprise account management including sub-account creation, user management, and access key generation for multi-tenant applications.

function sub_accounts(
  options?: ProvisioningOptions,
  callback?: (error: any, result: any) => void
): Promise<any>;

function create_sub_account(
  name: string,
  cloud_name: string,
  options?: ProvisioningOptions,
  callback?: (error: any, result: any) => void
): Promise<any>;

Provisioning API

V2 Promise API

Modern Promise-based interface providing async/await compatibility for all operations while maintaining the same functionality as the callback-based API.

import { v2 as cloudinary } from 'cloudinary';

// All v2 methods return Promises
const uploadResult = await cloudinary.uploader.upload(file, options);
const resources = await cloudinary.api.resources(options);
const searchResults = await cloudinary.search.expression('tags:sample').execute();

The v2 API includes all the same modules and functions as v1 but with Promise return types instead of callbacks.

Types

Core Configuration Types

interface ConfigOptions {
  cloud_name?: string;
  api_key?: string;
  api_secret?: string;
  api_proxy?: string;
  private_cdn?: boolean;
  secure_distribution?: string;
  force_version?: boolean;
  ssl_detected?: boolean;
  secure?: boolean;
  cdn_subdomain?: boolean;
  secure_cdn_subdomain?: boolean;
  cname?: string;
  shorten?: boolean;
  sign_url?: boolean;
  long_url_signature?: boolean;
  use_root_path?: boolean;
  auth_token?: AuthTokenOptions;
  [key: string]: any;
}

interface AuthTokenOptions {
  key: string;
  acl?: string;
  ip?: string;
  start_time?: number;
  duration?: number;
  expiration?: number;
}

Transformation Types

type CropMode = 'scale' | 'fit' | 'limit' | 'mfit' | 'fill' | 'lfill' | 'pad' | 'lpad' | 'mpad' | 'crop' | 'thumb' | 'imagga_crop' | 'imagga_scale';

type Gravity = 'north_west' | 'north' | 'north_east' | 'west' | 'center' | 'east' | 'south_west' | 'south' | 'south_east' | 'face' | 'faces' | 'body' | 'auto' | 'custom';

type ResourceType = 'image' | 'video' | 'raw';

type DeliveryType = 'upload' | 'private' | 'authenticated' | 'fetch' | 'multi' | 'text' | 'asset';

interface TransformationOptions {
  width?: number | string;
  height?: number | string;
  crop?: CropMode;
  gravity?: Gravity;
  quality?: number | string | 'auto';
  format?: string;
  fetch_format?: 'auto' | string;
  effect?: string | string[];
  angle?: number | string | 'auto_right' | 'auto_left';
  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;
}

Response Types

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?: object;
  metadata?: object;
  [key: string]: any;
}

interface ResourceApiResponse {
  resources: Array<{
    public_id: string;
    format: string;
    version: number;
    resource_type: string;
    type: string;
    created_at: string;
    bytes: number;
    width: number;
    height: number;
    url: string;
    secure_url: string;
    tags: string[];
    context?: object;
    [key: string]: any;
  }>;
  next_cursor?: string;
  [key: string]: any;
}