Cloudinary integration

Cloudinary is a cloud-based media management platform that provides storage, transformation, optimization, and delivery of images, videos, and other files. This integration lets your WeWeb backend upload, transform, and manage media assets using Cloudinary's API.

Use cases

• Upload user-generated content (profile photos, product images, documents)
• Generate optimized, transformed image URLs on the fly (resize, crop, apply effects)
• Build media galleries with pagination and filtering
• Secure private files with time-limited signed URLs
• Organize media assets with folders, tags, and metadata

Setup

1. In Cloudinary, get your API credentials (Cloud Name, API Key, API Secret) from the Dashboard.
2. In WeWeb, add your Cloudinary credentials to the Editor and Production modes.
3. Test by uploading a simple image using the Upload Resource action to verify authentication.
4. If the test fails, verify your API credentials are correct and that your Cloudinary account is active.

Transforming files

One of Cloudinary's most powerful features is the ability to transform images and videos on the fly. When you use the Get URL or Get Signed URL actions, you can pass transformation parameters to resize, crop, apply effects, and more—all without modifying the original file.

Basic resizing and cropping

Control the dimensions and aspect ratio of your images.

Resize by width

{
  "width": 400
}

Resize by width and height

{
  "width": 400,
  "height": 300
}

Crop modes

The crop parameter determines how the image fills the specified dimensions:

fill — Resize to fill the dimensions, cropping excess content

{
  "width": 400,
  "height": 300,
  "crop": "fill"
}

fit — Resize to fit within the dimensions, preserving aspect ratio (no cropping)

{
  "width": 400,
  "height": 300,
  "crop": "fit"
}

scale — Resize to exact dimensions, ignoring aspect ratio (may distort)

{
  "width": 400,
  "height": 300,
  "crop": "scale"
}

thumb — Generate a thumbnail with face detection for smart cropping

{
  "width": 200,
  "height": 200,
  "crop": "thumb",
  "gravity": "face"
}

crop — Extract a specific region from the image

{
  "width": 300,
  "height": 300,
  "crop": "crop",
  "gravity": "north_west",
  "x": 50,
  "y": 50
}

Gravity and focus

Control which part of the image to focus on when cropping.

Center focus

{
  "width": 400,
  "height": 400,
  "crop": "fill",
  "gravity": "center"
}

Face detection

{
  "width": 400,
  "height": 400,
  "crop": "fill",
  "gravity": "face"
}

Auto focus

Automatically detect the most interesting part

{
  "width": 400,
  "height": 400,
  "crop": "fill",
  "gravity": "auto"
}

Directional gravity

Possible values: north, south, east, west, north_east, north_west, south_east, south_west, center

{
  "width": 400,
  "height": 400,
  "crop": "fill",
  "gravity": "south"
}

Quality and format

Optimize file size and convert between formats.

Auto quality

Cloudinary automatically optimizes quality

{
  "quality": "auto"
}

Specific quality

Set quality from 1 to 100

{
  "quality": 80
}

Format conversion

Convert to different image formats

{
  "format": "webp"
}

Supported formats: jpg, png, gif, webp, avif, svg, pdf, bmp, tiff

Auto format

Deliver the best format based on browser support

{
  "fetch_format": "auto"
}

Effects and filters

Apply visual effects to your images.

Blur

{
  "effect": "blur:300"
}

Grayscale

{
  "effect": "grayscale"
}

Sepia

{
  "effect": "sepia"
}

Pixelate

{
  "effect": "pixelate:10"
}

Sharpen

{
  "effect": "sharpen:100"
}

Brightness and contrast

{
  "effect": "brightness:50"
}

{
  "effect": "contrast:50"
}

Auto enhance

Automatically improve image quality

{
  "effect": "auto_brightness"
}

{
  "effect": "auto_contrast"
}

Saturation

{
  "effect": "saturation:50"
}

Vignette

Darken the edges

{
  "effect": "vignette:30"
}

Rotation and orientation

Rotate or flip your images.

Rotate by degrees

{
  "angle": 45
}

Auto orientation

Use EXIF data to orient correctly

{
  "angle": "auto"
}

Flip horizontally

{
  "angle": "hflip"
}

Flip vertically

{
  "angle": "vflip"
}

Borders and frames

Add borders or rounded corners.

Simple border

{
  "border": "5px_solid_black"
}

Colored border

{
  "border": "10px_solid_rgb:0066cc"
}

Rounded corners

{
  "radius": 20
}

Circle crop

Make the image circular

{
  "width": 300,
  "height": 300,
  "crop": "fill",
  "radius": "max"
}

Background and padding

Add padding or change the background color.

Add background color

{
  "width": 400,
  "height": 400,
  "crop": "pad",
  "background": "auto:border"
}

Custom background color

{
  "width": 400,
  "height": 400,
  "crop": "pad",
  "background": "rgb:f0f0f0"
}

Transparent background

{
  "background": "transparent"
}

Overlays and watermarks

Add text or images on top of your media.

Image overlay

{
  "overlay": "logo_public_id",
  "gravity": "south_east",
  "x": 10,
  "y": 10,
  "width": 100,
  "opacity": 70
}

Text overlay

{
  "overlay": {
    "font_family": "Arial",
    "font_size": 48,
    "text": "Sample Text"
  },
  "gravity": "north",
  "y": 20,
  "color": "white"
}

Chaining transformations

Combine multiple transformations in sequence by using an array.

Example: Crop, then add overlay

{
  "transformation": [
    {
      "width": 400,
      "height": 400,
      "crop": "fill"
    },
    {
      "overlay": "logo",
      "gravity": "south_east",
      "width": 80
    }
  ]
}

Video transformations

Apply similar transformations to videos.

Resize video

{
  "width": 640,
  "height": 480,
  "crop": "fill"
}

Extract thumbnail from video

Get a frame at a specific time

{
  "start_offset": "5.0",
  "duration": "1.0"
}

Convert video format

{
  "format": "mp4"
}

Video quality

{
  "quality": "auto"
}

Responsive images

Generate images optimized for different devices.

Responsive width

{
  "width": "auto",
  "crop": "scale",
  "responsive": true
}

DPR (Device Pixel Ratio)

Serve high-resolution images for retina displays

{
  "width": 400,
  "dpr": "auto"
}

Combining transformations

You can combine multiple parameters to achieve complex effects.

Example: Responsive product image with auto format and quality

{
  "width": 800,
  "height": 600,
  "crop": "fill",
  "gravity": "auto",
  "quality": "auto",
  "fetch_format": "auto",
  "dpr": "auto"
}

Example: Profile photo with circular crop and border

{
  "width": 200,
  "height": 200,
  "crop": "fill",
  "gravity": "face",
  "radius": "max",
  "border": "3px_solid_white"
}

Example: Watermarked image with effects

{
  "transformation": [
    {
      "width": 1200,
      "height": 800,
      "crop": "fill",
      "quality": "auto:good"
    },
    {
      "effect": "sharpen:80"
    },
    {
      "overlay": "watermark_logo",
      "gravity": "south_east",
      "x": 20,
      "y": 20,
      "opacity": 60,
      "width": 150
    }
  ]
}

TRANSFORMATION DOCUMENTATION

For a complete list of all available transformations and their parameters, visit the Cloudinary Transformation Reference.

Common pitfalls (setup & usage)

Invalid API credentials

If your Cloud Name, API Key, or API Secret is incorrect, all requests will fail with a 401 error. Double-check that you've copied the credentials exactly from your Cloudinary dashboard, including any trailing characters.

FINDING YOUR CREDENTIALS

In Cloudinary, go to Dashboard > Settings > Account to find your Cloud Name, API Key, and API Secret. Make sure you're copying from the correct environment (production vs. development).

File size limits

Free Cloudinary accounts have upload size limits (typically 10MB for images, 100MB for videos). Attempting to upload larger files will fail. Consider upgrading your plan or reducing file sizes before upload.

Invalid Public IDs

Public IDs can only contain alphanumeric characters, hyphens, underscores, and forward slashes. Special characters or spaces will cause upload failures. Sanitize filenames before using them as Public IDs.

Transformation errors

Invalid transformation parameters (like negative dimensions or unsupported crop modes) will cause URL generation to fail. Always reference the Cloudinary transformations documentation for valid parameter combinations.

All Actions

This integration provides seven actions for comprehensive media management.

Action	Description
Upload Resource	Upload a file to Cloudinary from a URL, base64 data, or file path
Get URL	Generate an optimized URL for a resource with optional transformations
Get All Resources	List resources with filtering and pagination
Get Resource by ID	Retrieve detailed information about a specific resource
Delete Resource	Permanently delete a resource from Cloudinary
Get Signed URL	Generate a temporary, secure URL for private resources
Update Resource	Update tags, context metadata, or moderation status of a resource

Action details

Upload Resource

Upload a file to Cloudinary from a URL, base64 data URI, or file path.

Inputs

Display Key	Example Input	Description	Restrictions
File	"https://example.com/image.jpg"	File to upload (URL, base64 data URI, or file path)	Required; for base64, use format: data:image/jpeg;base64,/9j/4AAQ...
Public ID Optional	"my_image"	Custom identifier for the resource	Alphanumeric, hyphens, underscores, slashes; if not provided, Cloudinary generates one
Folder Optional	"products/featured"	Folder path to store the resource	Creates folder if it doesn't exist
Tags Optional	["product","featured"]	Tags to assign to the resource	Array of strings
Resource Type Optional	"auto"	Type of resource	Allowed values: auto, image, video, raw; default: auto
Storage Type Optional	"upload"	Access level for the resource	Allowed values: upload, private, authenticated; default: upload
Context Optional	{"alt":"Product image","caption":"Featured item"}	Key-value pairs of contextual metadata	Object with string values
Overwrite Optional	false	Whether to overwrite existing resource with same Public ID	Boolean; default: false
Unique Filename Optional	true	Add random characters to filename for uniqueness	Boolean; default: true

Example output

{
  "public_id": "products/featured/my_image",
  "version": 1672531200,
  "signature": "abc123def456",
  "width": 1920,
  "height": 1080,
  "format": "jpg",
  "resource_type": "image",
  "created_at": "2024-01-01T12:00:00Z",
  "tags": ["product", "featured"],
  "bytes": 245678,
  "type": "upload",
  "url": "http://res.cloudinary.com/demo/image/upload/v1672531200/products/featured/my_image.jpg",
  "secure_url": "https://res.cloudinary.com/demo/image/upload/v1672531200/products/featured/my_image.jpg"
}

Documentation of API endpoint that powers action: Cloudinary API - Upload (POST /v1_1/:cloud_name/:resource_type/upload)

Get URL

Generate an optimized URL for a resource with optional transformations applied on the fly.

Inputs

Display Key	Example Input	Description	Restrictions
Public ID	"my_image"	Identifier of the resource	Required
Transformation Optional	{"width":300,"height":300,"crop":"fill"}	Transformation parameters (resize, crop, effects, etc.)	Object; see Cloudinary transformations documentation
Secure Optional	true	Use HTTPS URL	Boolean; default: true
Resource Type Optional	"image"	Type of resource	Allowed values: image, video, raw; default: image
Format Optional	"jpg"	Desired output format	String (e.g., jpg, png, webp, gif)
Quality Optional	"auto"	Image quality	String: auto or number 1-100; default: auto

Example output

{
  "url": "https://res.cloudinary.com/demo/image/upload/w_300,h_300,c_fill,q_auto/my_image.jpg"
}

Documentation of API endpoint that powers action: Cloudinary API - URL Generation

Get All Resources

List resources from your Cloudinary account with filtering and pagination.

Inputs

Display Key	Example Input	Description	Restrictions
Resource Type Optional	"image"	Filter by resource type	Allowed values: all, image, video, raw
Max Results Optional	100	Maximum number of resources to return	Number between 1 and 500
Next Cursor Optional	"abc123def456..."	Pagination cursor from previous response	String from next_cursor field
Prefix Optional	"products/"	Filter by Public ID prefix or folder path	String
Storage Type Optional	"upload"	Filter by storage type	Allowed values: upload, private, authenticated; default: upload
Include Tags Optional	true	Include tags in response	Boolean; default: false
Include Context Optional	true	Include context metadata in response	Boolean; default: false
Include Moderations Optional	false	Include moderation status in response	Boolean; default: false

Example output

{
  "resources": [
    {
      "public_id": "products/item_123",
      "format": "jpg",
      "version": 1672531200,
      "resource_type": "image",
      "type": "upload",
      "created_at": "2024-01-01T12:00:00Z",
      "bytes": 245678,
      "width": 1920,
      "height": 1080,
      "url": "http://res.cloudinary.com/demo/image/upload/v1672531200/products/item_123.jpg",
      "secure_url": "https://res.cloudinary.com/demo/image/upload/v1672531200/products/item_123.jpg"
    }
  ],
  "next_cursor": "def789ghi012...",
  "rate_limit_allowed": 500,
  "rate_limit_reset_at": "2024-01-01T13:00:00Z",
  "rate_limit_remaining": 498
}

Documentation of API endpoint that powers action: Cloudinary API - List resources (GET /v1_1/:cloud_name/resources/:resource_type)

Get Resource by ID

Retrieve detailed information about a specific resource including metadata, dimensions, and URLs.

Inputs

Display Key	Example Input	Description	Restrictions
Public ID	"sample_image"	Unique identifier of the resource	Required
Resource Type Optional	"image"	Type of resource	Allowed values: image, video, raw; default: image

Example output

{
  "public_id": "sample_image",
  "format": "jpg",
  "version": 1672531200,
  "resource_type": "image",
  "type": "upload",
  "created_at": "2024-01-01T12:00:00Z",
  "bytes": 245678,
  "width": 1920,
  "height": 1080,
  "url": "http://res.cloudinary.com/demo/image/upload/v1672531200/sample_image.jpg",
  "secure_url": "https://res.cloudinary.com/demo/image/upload/v1672531200/sample_image.jpg",
  "tags": ["product", "featured"],
  "context": {
    "alt": "Product image",
    "caption": "Featured item"
  }
}

Documentation of API endpoint that powers action: Cloudinary API - Get resource details (GET /v1_1/:cloud_name/resources/:resource_type/:type/:public_id)

Delete Resource

Permanently delete a resource from Cloudinary. This action cannot be undone.

Inputs

Display Key	Example Input	Description	Restrictions
Public ID	"my_image"	Identifier of the resource to delete	Required
Resource Type Optional	"image"	Type of resource	Allowed values: image, video, raw; default: image
Storage Type Optional	"upload"	Storage type	Allowed values: upload, private, authenticated; default: upload
Invalidate Optional	false	Invalidate CDN cached copies	Boolean; default: false; may incur additional costs

Example output

{
  "result": "ok"
}

Documentation of API endpoint that powers action: Cloudinary API - Delete resource (DELETE /v1_1/:cloud_name/resources/:resource_type/:type/:public_id)

Get Signed URL

Generate a temporary, secure URL for accessing private or authenticated resources with time-limited access.

Inputs

Display Key	Example Input	Description	Restrictions
Public ID	"my_image"	Identifier of the resource	Required
Expires At Optional	1700000000	Unix timestamp for URL expiry	Number; if not provided, defaults to 1 hour from now
Transformation Optional	{"width":300,"height":300,"crop":"fill"}	Transformation parameters	Object; see Cloudinary transformations documentation
Attachment Optional	false	Force download instead of display	Boolean; default: false
Resource Type Optional	"image"	Type of resource	Allowed values: image, video, raw; default: image
Format Optional	"jpg"	Resource format	String (e.g., jpg, png, webp)

Example output

{
  "url": "https://res.cloudinary.com/demo/image/authenticated/s--abc123def--/v1672531200/w_300,h_300,c_fill/my_image.jpg"
}

Documentation of API endpoint that powers action: Cloudinary API - Authenticated URLs

Update Resource

Update tags, context metadata, or moderation status of an existing resource without re-uploading it.

Inputs

Display Key	Example Input	Description	Restrictions
Public ID	"my_image"	Identifier of the resource to update	Required
Tags Optional	["updated","verified"]	Replace existing tags	Array of strings; replaces all existing tags
Context Optional	{"alt":"Updated description","caption":"New caption"}	Replace existing context metadata	Object; replaces all existing context
Resource Type Optional	"image"	Type of resource	Allowed values: image, video, raw; default: image
Storage Type Optional	"upload"	Storage type	Allowed values: upload, private, authenticated; default: upload
Moderation Status Optional	"approved"	Set moderation status	Allowed values: pending, approved, rejected

Example output

{
  "public_id": "my_image",
  "version": 1672531200,
  "tags": ["updated", "verified"],
  "context": {
    "alt": "Updated description",
    "caption": "New caption"
  },
  "moderation_status": "approved"
}

Documentation of API endpoint that powers action: Cloudinary API - Update resource (POST /v1_1/:cloud_name/resources/:resource_type/:type/:public_id)

Error handling

Error code and type	Reason
401 Unauthorized	Invalid or missing API credentials (Cloud Name, API Key, or API Secret).
400 Bad Request	Invalid parameters (e.g., malformed Public ID, invalid transformation parameters, missing required fields).
404 Not Found	Resource with specified Public ID does not exist or incorrect resource type.
420 Rate Limited	Too many requests in a short period; reduce request frequency and retry with backoff.
500 Internal Server Error	Cloudinary service error; retry with exponential backoff.

FAQs

How do I organize files into folders?

Use the Folder field when uploading to specify the folder path (e.g., products/featured). Alternatively, you can include the folder path in the Public ID using forward slashes (e.g., products/featured/item_123). The Folder field is recommended for cleaner separation between folder structure and filename.

What's the difference between Public ID and Folder?

Public ID is the unique identifier for your file (like a filename), while Folder is the directory path where it's stored. If you use both, they combine: Folder products + Public ID item_123 = final path products/item_123. For best practice, use Folder for organization and Public ID for just the filename.

How do I transform images without re-uploading them?

Use the Get URL action with the Transformation parameter. Cloudinary applies transformations on the fly when the URL is accessed - no re-upload needed. For example, {"width": 300, "height": 300, "crop": "fill"} will resize and crop the image dynamically.

What file formats are supported?

Cloudinary supports most common formats: images (JPEG, PNG, GIF, WebP, SVG), videos (MP4, MOV, AVI), and raw files (PDFs, documents, etc.). Use Resource Type to specify the type: image, video, or raw.

How do signed URLs work?

Signed URLs are temporary, secure links for private or authenticated resources. Use Get Signed URL to generate a URL that expires after a specified time (default 1 hour). This is perfect for giving time-limited access to private files without making them permanently public.

Why do I get a 404 when trying to access a resource?

Check that: (1) the Public ID exactly matches the uploaded resource, (2) the Resource Type matches (image, video, or raw), (3) the Storage Type matches (upload, private, or authenticated), and (4) the resource hasn't been deleted.