Core URL generation functionality for creating Cloudinary delivery URLs with comprehensive transformation parameters. Supports images, videos, and other assets with extensive customization options.
Generate Cloudinary URLs for assets with optional transformations.
/**
* Generate a Cloudinary URL for an asset
* @param public_id - The public ID of the asset
* @param options - Transformation and delivery options
* @returns Cloudinary URL string
*/
function url(public_id: string, options?: UrlGenerationOptions): string;
interface UrlGenerationOptions extends TransformationOptions {
/** Resource type: image, video, or raw */
resource_type?: 'image' | 'video' | 'raw';
/** Delivery type */
type?: 'upload' | 'private' | 'authenticated' | 'fetch' | 'multi' | 'text' | 'asset';
/** Asset version */
version?: number | string;
/** File format override */
format?: string;
/** URL suffix for vanity URLs */
url_suffix?: string;
/** Use root path */
use_root_path?: boolean;
/** Authentication token */
auth_token?: string;
/** Sign the URL */
sign_url?: boolean;
[key: string]: any;
}Usage Examples:
const cloudinary = require('cloudinary');
// Basic URL
const basicUrl = cloudinary.url('sample');
// Result: https://res.cloudinary.com/demo/image/upload/sample
// URL with transformations
const transformedUrl = cloudinary.url('sample', {
width: 300,
height: 200,
crop: 'fill',
quality: 'auto',
fetch_format: 'auto'
});
// Result: https://res.cloudinary.com/demo/image/upload/w_300,h_200,c_fill,q_auto,f_auto/sample
// Video URL
const videoUrl = cloudinary.url('sample_video', {
resource_type: 'video',
quality: 'auto',
format: 'mp4'
});Specialized URL generation for video assets with video-specific transformations.
/**
* Generate a video URL with video-specific transformations
* @param public_id - The public ID of the video
* @param options - Video transformation options
* @returns Video URL string
*/
function video_url(public_id: string, options?: VideoTransformationOptions): string;
/**
* Generate a video thumbnail URL
* @param public_id - The public ID of the video
* @param options - Thumbnail transformation options
* @returns Video thumbnail URL string
*/
function video_thumbnail_url(public_id: string, options?: TransformationOptions): string;
interface VideoTransformationOptions extends TransformationOptions {
/** Video codec */
video_codec?: string;
/** Audio codec */
audio_codec?: 'none' | 'aac' | 'vorbis' | 'mp3';
/** Video bitrate */
bit_rate?: number | string;
/** Frames per second */
fps?: number | string | number[];
/** Video sampling */
video_sampling?: number | string;
/** Audio frequency */
audio_frequency?: number;
/** Start offset for video trimming */
start_offset?: number | string;
/** End offset for video trimming */
end_offset?: number | string;
/** Video duration */
duration?: number | string;
/** Streaming profile */
streaming_profile?: string;
/** Video flags */
flags?: string | string[];
[key: string]: any;
}Usage Examples:
const cloudinary = require('cloudinary');
// Video URL with transformations
const videoUrl = cloudinary.utils.video_url('my_video', {
width: 640,
height: 480,
crop: 'fill',
quality: 'auto',
format: 'mp4',
video_codec: 'h264',
audio_codec: 'aac'
});
// Video thumbnail
const thumbnailUrl = cloudinary.utils.video_thumbnail_url('my_video', {
width: 300,
height: 200,
crop: 'fill',
start_offset: '10' // Thumbnail from 10 seconds
});Build transformation strings programmatically for complex transformations.
/**
* Generate transformation string from options
* @param options - Transformation options object
* @returns Transformation string
*/
function generate_transformation_string(options: TransformationOptions): string;Usage Examples:
const cloudinary = require('cloudinary');
// Generate transformation string
const transformString = cloudinary.utils.generate_transformation_string({
width: 300,
height: 200,
crop: 'fill',
gravity: 'face',
quality: 'auto',
effect: ['sharpen', 'sepia']
});
// Result: "w_300,h_200,c_fill,g_face,q_auto,e_sharpen,e_sepia"
// Use in URL
const url = cloudinary.url('sample', {
raw_transformation: transformString
});Generate signed URLs for secure asset delivery.
/**
* Generate signed URL parameters
* @param params_to_sign - Parameters to include in signature
* @param options - Configuration options with API secret
* @returns Object with signature and api_key
*/
function sign_request(
params_to_sign: Record<string, any>,
options?: { api_secret?: string; [key: string]: any }
): { signature: string; api_key: string; [key: string]: any };
/**
* Generate API signature for request parameters
* @param params_to_sign - Parameters to sign
* @param api_secret - API secret for signing
* @returns Signature string
*/
function api_sign_request(
params_to_sign: Record<string, any>,
api_secret: string
): string;Usage Examples:
const cloudinary = require('cloudinary');
// Generate signed URL
const signedUrl = cloudinary.url('sample', {
width: 300,
height: 200,
crop: 'fill',
sign_url: true,
type: 'authenticated'
});
// Manual signature generation
const params = {
public_id: 'sample',
width: 300,
height: 200,
crop: 'fill',
timestamp: Math.floor(Date.now() / 1000)
};
const signed = cloudinary.utils.sign_request(params);
console.log('Signature:', signed.signature);Generate URLs for private asset downloads with temporary access.
/**
* Generate private download URL for authenticated access
* @param public_id - Asset public ID
* @param format - File format
* @param options - Download options
* @returns Private download URL
*/
function private_download_url(
public_id: string,
format: string,
options?: {
resource_type?: 'image' | 'video' | 'raw';
type?: string;
expires_at?: number;
attachment?: boolean;
}
): string;Usage Examples:
const cloudinary = require('cloudinary');
// Generate private download URL
const downloadUrl = cloudinary.utils.private_download_url('sample', 'jpg', {
resource_type: 'image',
expires_at: Math.floor(Date.now() / 1000) + 3600, // Expires in 1 hour
attachment: true
});Generate URLs for downloading asset archives (ZIP files).
/**
* Generate archive download URL
* @param options - Archive options
* @returns Archive download URL
*/
function download_archive_url(options?: ArchiveOptions): string;
/**
* Generate ZIP download URL
* @param options - ZIP archive options
* @returns ZIP download URL
*/
function download_zip_url(options?: ArchiveOptions): string;
interface ArchiveOptions {
/** Archive type: zip or tgz */
type?: 'zip' | 'tgz';
/** Target public ID for the archive */
target_public_id?: string;
/** Public IDs to include */
public_ids?: string[];
/** Tags to include */
tags?: string | string[];
/** Transformations to apply */
transformations?: TransformationOptions;
/** Expiration timestamp */
expires_at?: number;
[key: string]: any;
}Usage Examples:
const cloudinary = require('cloudinary');
// Generate ZIP download URL for tagged assets
const zipUrl = cloudinary.utils.download_zip_url({
tags: ['product_images'],
transformations: [
{ width: 300, height: 300, crop: 'fill' }
]
});
// Archive specific assets
const archiveUrl = cloudinary.utils.download_archive_url({
public_ids: ['image1', 'image2', 'image3'],
type: 'zip',
target_public_id: 'my_archive'
});interface TransformationOptions {
/** Image/video width */
width?: number | string;
/** Image/video height */
height?: number | string;
/** Crop mode */
crop?: 'scale' | 'fit' | 'limit' | 'mfit' | 'fill' | 'lfill' | 'pad' | 'lpad' | 'mpad' | 'crop' | 'thumb' | 'imagga_crop' | 'imagga_scale';
/** Gravity for cropping */
gravity?: 'auto' | 'center' | 'face' | 'faces' | 'body' | 'north' | 'south' | 'east' | 'west' | 'north_east' | 'north_west' | 'south_east' | 'south_west';
/** Image quality */
quality?: number | string | 'auto';
/** File format */
format?: string;
/** Automatic format selection */
fetch_format?: 'auto' | string;
/** Visual effects */
effect?: string | string[];
/** Rotation angle */
angle?: number | string | 'auto_right' | 'auto_left' | 'vflip' | 'hflip';
/** Background color */
background?: string;
/** Border settings */
border?: string;
/** Color adjustments */
color?: string;
/** Device pixel ratio */
dpr?: number | string;
/** Processing flags */
flags?: string | string[];
/** Image overlay */
overlay?: string;
/** Image underlay */
underlay?: string;
/** Corner radius */
radius?: number | string;
/** Opacity level */
opacity?: number | string;
/** Custom variables */
variables?: Array<string | object>;
/** Conditional transformations */
if?: string;
/** Raw transformation string */
raw_transformation?: string;
[key: string]: any;
}
interface UrlGenerationOptions extends TransformationOptions {
resource_type?: 'image' | 'video' | 'raw';
type?: 'upload' | 'private' | 'authenticated' | 'fetch' | 'multi' | 'text' | 'asset';
version?: number | string;
format?: string;
url_suffix?: string;
use_root_path?: boolean;
auth_token?: string;
sign_url?: boolean;
[key: string]: any;
}
interface VideoTransformationOptions extends TransformationOptions {
video_codec?: string;
audio_codec?: 'none' | 'aac' | 'vorbis' | 'mp3';
bit_rate?: number | string;
fps?: number | string | number[];
video_sampling?: number | string;
audio_frequency?: number;
start_offset?: number | string;
end_offset?: number | string;
duration?: number | string;
streaming_profile?: string;
[key: string]: any;
}
interface ArchiveOptions {
type?: 'zip' | 'tgz';
target_public_id?: string;
public_ids?: string[];
tags?: string | string[];
transformations?: TransformationOptions;
expires_at?: number;
[key: string]: any;
}