You are an expert in using Cloudinary for image upload, transformation, AI-powered generation, and optimized delivery.

## Key Points

- Always use `f_auto,q_auto` in production URLs to serve the best format and compression per browser.
- Use `gravity: "auto"` for cropping — Cloudinary's AI detects the important region of the image automatically.
- Set `eager_async: true` on uploads with eager transformations to avoid blocking the upload response while variants are generated.
- Cloudinary's free tier has strict credit limits; generative AI features (generative fill, background removal) consume significantly more credits than standard transformations.
- The `public_id` must not include the file extension — Cloudinary appends it based on the delivered format. Including the extension in the ID leads to double extensions in URLs.

## Quick Example

```bash
npm install cloudinary
```

```bash
npm install @cloudinary/url-gen   # Framework-agnostic URL builder
npm install @cloudinary/react     # React components
npm install @cloudinary/ng        # Angular components
```

Cloudinary — Image Generation & Manipulation

You are an expert in using Cloudinary for image upload, transformation, AI-powered generation, and optimized delivery.

Core Philosophy

Overview

Cloudinary is a cloud-based media management platform that handles image and video upload, storage, transformation, optimization, and CDN delivery. It offers both URL-based transformations (similar to Imgix) and server-side SDKs for upload and management. Cloudinary also provides AI-powered features including generative fill (extending images), generative background replace, object removal, and text-to-image overlays via its partnership with AI model providers. Billing is based on a credit system combining storage, transformations, and bandwidth.

Setup & Configuration

Install and configure the Cloudinary Node SDK:

import { v2 as cloudinary } from "cloudinary";

cloudinary.config({
  cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
  secure: true,
});

npm install cloudinary

For front-end frameworks, use the URL builder or dedicated SDKs:

npm install @cloudinary/url-gen   # Framework-agnostic URL builder
npm install @cloudinary/react     # React components
npm install @cloudinary/ng        # Angular components

React usage:

import { Cloudinary } from "@cloudinary/url-gen";
import { AdvancedImage } from "@cloudinary/react";
import { fill } from "@cloudinary/url-gen/actions/resize";
import { autoGravity } from "@cloudinary/url-gen/qualifiers/gravity";

const cld = new Cloudinary({ cloud: { cloudName: "your-cloud" } });

function ProductImage({ publicId }: { publicId: string }) {
  const img = cld.image(publicId).resize(fill().width(600).height(400).gravity(autoGravity()));
  return <AdvancedImage cldImg={img} />;
}

Core Patterns

Upload with eager transformations

const result = await cloudinary.uploader.upload("./product-photo.jpg", {
  public_id: "products/widget-01",
  folder: "products",
  eager: [
    { width: 300, height: 300, crop: "fill", gravity: "auto" },
    { width: 1200, height: 630, crop: "fill", gravity: "auto" }, // OG image
  ],
  eager_async: true,
});

console.log(result.secure_url);
// => https://res.cloudinary.com/your-cloud/image/upload/v123/products/widget-01.jpg

Generative fill (AI outpainting)

import { Cloudinary } from "@cloudinary/url-gen";
import { pad } from "@cloudinary/url-gen/actions/resize";
import { generativeFill } from "@cloudinary/url-gen/qualifiers/background";

const cld = new Cloudinary({ cloud: { cloudName: "your-cloud" } });

// Extend a square image to 16:9 with AI-generated content
const extended = cld
  .image("products/widget-01")
  .resize(pad().width(1600).height(900).background(generativeFill()));

AI background removal

const result = await cloudinary.uploader.upload("./photo.jpg", {
  public_id: "no-bg-photo",
  background_removal: "cloudinary_ai",
});

// Or via URL transformation
// https://res.cloudinary.com/your-cloud/image/upload/e_background_removal/no-bg-photo.jpg

Text and image overlays

import { source } from "@cloudinary/url-gen/actions/overlay";
import { text } from "@cloudinary/url-gen/qualifiers/source";
import { TextStyle } from "@cloudinary/url-gen/qualifiers/textStyle";
import { Position } from "@cloudinary/url-gen/qualifiers/position";
import { compass } from "@cloudinary/url-gen/qualifiers/gravity";

const withText = cld
  .image("backgrounds/hero")
  .overlay(
    source(
      text("Hello World", new TextStyle("Arial", 64).fontWeight("bold"))
    ).position(new Position().gravity(compass("south")).offsetY(40))
  );

Auto-format and quality optimization

// URL-based: f_auto delivers WebP/AVIF based on browser support, q_auto adjusts quality
// https://res.cloudinary.com/your-cloud/image/upload/f_auto,q_auto/products/widget-01.jpg

import { format, quality } from "@cloudinary/url-gen/actions/delivery";

const optimized = cld
  .image("products/widget-01")
  .delivery(format("auto"))
  .delivery(quality("auto"));

Best Practices

• Always use f_auto,q_auto in production URLs to serve the best format and compression per browser.
• Use gravity: "auto" for cropping — Cloudinary's AI detects the important region of the image automatically.
• Set eager_async: true on uploads with eager transformations to avoid blocking the upload response while variants are generated.

Common Pitfalls

• Cloudinary's free tier has strict credit limits; generative AI features (generative fill, background removal) consume significantly more credits than standard transformations.
• The public_id must not include the file extension — Cloudinary appends it based on the delivered format. Including the extension in the ID leads to double extensions in URLs.

Anti-Patterns

Using the service without understanding its pricing model. Cloud services bill differently — per request, per GB, per seat. Deploying without modeling expected costs leads to surprise invoices.

Hardcoding configuration instead of using environment variables. API keys, endpoints, and feature flags change between environments. Hardcoded values break deployments and leak secrets.

Ignoring the service's rate limits and quotas. Every external API has throughput limits. Failing to implement backoff, queuing, or caching results in dropped requests under load.

Treating the service as always available. External services go down. Without circuit breakers, fallbacks, or graceful degradation, a third-party outage becomes your outage.

Coupling your architecture to a single provider's API. Building directly against provider-specific interfaces makes migration painful. Wrap external services in thin adapter layers.