> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# User Help, API Documentation, and Framework SDKs

# Cloudinary Documentation

Cloudinary is a multi-product, API-first platform for managing, transforming, optimizing, and delivering images, videos, and other media at scale. Its core products include AI-powered image and video APIs, digital asset management (Cloudinary Assets), and workflow automation (MediaFlows). You upload assets to Cloudinary, apply transformations via URL parameters or SDKs, and deliver optimized media through a global CDN.

Use this page for product-level orientation and to choose the correct implementation path. For the full documentation map, see [`llms.txt`](/llms.txt).

If your agent runtime supports MCP or Cloudinary Skills, start with [Cloudinary AI agent tools and MCP servers](/cloudinary_llm_mcp). The Asset Management MCP server lets agents upload and manage assets and generate Cloudinary integration code without going through the SDK and API workflows below.

## Choose the right workflow

Match the task to one of these workflows. If multiple apply, see "Recommended default path" below.

### Upload from a server (recommended default)

For tasks involving uploads, metadata, eager transformations, signed operations, or asset management. See [Cloudinary SDKs](/cloudinary_sdks), [backend SDK quick starts](/dev_kickstart_sdks), and the [Upload API reference](/image_upload_api_reference).

### Deliver transformed media

For tasks where the asset already exists in Cloudinary and you need rendering, optimization, resizing, cropping, format conversion, or transformation debugging. See the [Transformation URL API reference](/transformation_reference), [frontend SDKs](/frontend_sdks), and the [JavaScript SDK](/javascript_integration).

### Upload directly from a browser or client app

For tasks where users upload without handling files through your own server. See the [Upload Widget](/upload_widget) for the fastest production-ready integration, [client-side uploading](/client_side_uploading) for custom browser flows, and [upload presets](/upload_presets) for unsigned upload configuration.

### Search or manage assets

For tasks involving listing assets, filtering by metadata or tags, organizing folders, managing presets, or updating asset details. See the [Admin API reference](/admin_api), [Search API method](/search_method), and [search expressions](/search_expressions).

### Secure or restrict delivery

For tasks where public delivery is not appropriate and you need signed URLs, private assets, authenticated delivery, or stricter transformation control. See [media access methods](/control_access_to_media) and [delivery URL signatures](/delivery_url_signatures).

### Recommended default path

If the task includes both upload and delivery, start with a backend SDK quick start. This is the fastest reliable path to a working integration because it gives you configuration, upload, response handling, transformation, and Admin API access in one flow.

## Authentication and setup

Every Cloudinary account has one or more **product environments**, each identified by a unique **cloud name**. To get started you need:

- **Cloud name** — required for all delivery URLs and SDK configuration. Find it in the Console under **Product Environment**.
- **API key** and **API secret** — required for upload, admin, and other authenticated operations. Find these on the **API Keys** page.

On the server, prefer environment-based configuration such as `CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME`.

### Security rules

- Never expose `api_secret` in browser or native-app code.
- For browser-only uploads, use the Upload Widget or an unsigned upload preset.
- For signed browser uploads, generate the signature on the server.
- For signed delivery URLs, generate the signature on the server.

## Core concepts

### Cloud name and product environments

The cloud name is a namespace for all assets and configuration within a product environment. API credentials authenticate requests against a specific product environment. An account can have multiple product environments (for example, dev, staging, production), each with its own asset repository.

### Assets

An **asset** is any file stored in Cloudinary: images, videos, raw files, or other media. The combination of three properties identifies each asset:

- **Public ID**: A unique identifier within the product environment (e.g., `folder/my-image`).
- **Resource type**: `image`, `video`, or `raw`.
- **Delivery type**: Controls access — `upload` (public), `private`, `authenticated`, `fetch` (remote URL proxy), and social types such as `facebook`, `twitter`, and `youtube`.

### Transformations

Transformations are operations applied to assets on-the-fly via URL parameters. They include resizing, cropping, format conversion, quality optimization, overlays, effects, and AI-based operations. Transformation parameters are comma-separated within a component and chained with slashes for multi-step pipelines.

A transformation URL follows this pattern:

```
https://res.cloudinary.com/<cloud_name>/<resource_type>/<delivery_type>/<transformations>/<public_id>.<format>
```

For example:

```
https://res.cloudinary.com/demo/image/upload/w_400,h_300,c_fill,g_auto/sample.webp
```

This delivers the image `sample` resized to 400x300 with content-aware cropping, converted to WebP. Transformations create derived versions on demand and do not modify the original asset.

### Delivery

Cloudinary delivers assets through its CDN at `https://res.cloudinary.com/<cloud_name>/`. The CDN processes and caches transformations on first request, then serves subsequent requests for the same transformation directly from cache. Only the cloud name is required to construct delivery URLs — no authentication is needed for the `upload` (public) delivery type.

## Key APIs

- **Transformation URL API**: A URL-based API for delivering assets with on-the-fly transformations. Best for delivery, optimization, and derived assets.
- **Upload API**: Upload and update assets, apply eager transformations, set tags and metadata, and generate derived versions.
- **Admin API**: Rate-limited management of assets, folders, upload presets, named transformations, and product environment configuration. Includes the search method and structured metadata method.
- **Search API**: The Admin API `search` method, which uses Lucene-like expression syntax across metadata, tags, context, and asset properties.
- **Provisioning API**: Programmatically manage account-level resources including users, user groups, and product environments. Ignore unless explicitly automating account-level admin.

## SDKs

Cloudinary provides official SDKs organized by platform:

- **Backend**: Node.js, Python, PHP, Java, Ruby/Rails, .NET, Go, and Dart.
- **Frontend**: React, Vue.js, Angular, JavaScript (`@cloudinary/url-gen`), Next.js, and jQuery.
- **Mobile**: iOS (Swift), Android, Flutter, React Native, and Kotlin.

Community-developed libraries are also available for frameworks such as Svelte, Nuxt, Astro, Laravel, Gatsby, and Drupal.

### First successful implementation (Node.js)

The fastest reliable first task is: configure a backend SDK, upload one image, generate one transformed URL, verify both URLs in a browser.

```bash
npm install cloudinary
export CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME
```

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

(async () => {
  const result = await cloudinary.uploader.upload('./sample.jpg', {
    public_id: 'agent-entrypoint/sample',
  });

  console.log({
    public_id: result.public_id,
    secure_url: result.secure_url,
  });

  const transformedUrl = cloudinary.url(result.public_id, {
    secure: true,
    transformation: [
      { width: 400, height: 300, crop: 'fill', gravity: 'auto' },
      { fetch_format: 'auto', quality: 'auto' },
    ],
  });

  console.log({ transformedUrl });
})().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

**Success criteria:**

- The upload response includes a `public_id` and `secure_url`.
- Opening `secure_url` returns the uploaded asset.
- Opening `transformedUrl` returns an optimized 400x300 derived version.

For other backend languages (Python, PHP, Java, Ruby, .NET, Go, Dart), see the relevant quick start under [Cloudinary SDKs](/cloudinary_sdks). The pattern is the same: configure the SDK with credentials, call `uploader.upload()`, then build a delivery URL.

### Frontend delivery example (JavaScript / framework SDKs)

For frontend rendering when the asset already exists in Cloudinary, use `@cloudinary/url-gen`. This is the underlying URL-generation library used by all Cloudinary frontend SDKs, so the same API applies whether you are working in plain JavaScript, [React](/react_integration), [Vue](/vue_integration), [Angular](/angular_integration), [Next.js](/nextjs_integration), or another supported framework — only the rendering component differs (e.g. `<AdvancedImage>` in React).

```js
import { Cloudinary } from '@cloudinary/url-gen';
import { fill } from '@cloudinary/url-gen/actions/resize';
import { autoGravity } from '@cloudinary/url-gen/qualifiers/gravity';

const cld = new Cloudinary({ cloud: { cloudName: 'demo' } });
const img = cld.image('sample').resize(fill().width(400).height(300).gravity(autoGravity()));
const url = img.toURL();
```

For framework-specific component usage (rendering, lazy-loading, responsive images), see [Frontend SDKs](/frontend_sdks).

### First successful implementation (Python)

Same task as the Node.js example: configure the SDK, upload one image, generate one transformed URL, and verify both URLs in a browser.

```bash
pip install cloudinary
export CLOUDINARY_URL=cloudinary://API_KEY:API_SECRET@CLOUD_NAME
```

```python
import cloudinary
import cloudinary.uploader
import cloudinary.utils

result = cloudinary.uploader.upload(
    "./sample.jpg",
    public_id="agent-entrypoint/sample",
)

print({
    "public_id": result["public_id"],
    "secure_url": result["secure_url"],
})

transformed_url, _ = cloudinary.utils.cloudinary_url(
    result["public_id"],
    secure=True,
    transformation=[
        {"width": 400, "height": 300, "crop": "fill", "gravity": "auto"},
        {"fetch_format": "auto", "quality": "auto"},
    ],
)

print({"transformed_url": transformed_url})
```

**Success criteria:**

- The upload response includes a `public_id` and `secure_url`.
- Opening `secure_url` returns the uploaded asset.
- Opening `transformed_url` returns an optimized 400x300 derived version.

## Widgets and players

Cloudinary offers embeddable UI components that integrate directly into your application:

- **Upload Widget**: A drop-in upload UI supporting local files, URLs, camera, and third-party sources like Dropbox and Google Drive.
- **Media Library Widget**: Embed the Cloudinary Media Library into your app so users can browse and select assets.
- **Video Player**: An HTML5 video player with built-in adaptive bitrate streaming (HLS/MPEG-DASH), video transformations, and analytics.
- **Product Gallery**: An interactive widget for displaying product images and videos.
- **Media Editor**: An interactive widget for end-user image editing.

## Other product areas

Beyond the Image & Video APIs, Cloudinary includes additional products. These are not the default starting point for most coding tasks, but each has its own SDK and API surface for direct integration:

- **Cloudinary Assets (DAM)**: A digital asset management solution for marketing and creative teams, with a Media Library UI, structured metadata, approval workflows, search, and folder-based access control. Programmatic access via the Admin API and dedicated DAM endpoints.
- **MediaFlows**: Workflow automation using EasyFlows (step-by-step builder) and PowerFlows (drag-and-drop visual builder) to connect triggers and actions across media pipelines.
- **Cloudinary Moderation**: AI-powered visual quality and brand compliance checks for uploaded content.

## Add-ons and webhooks

Cloudinary's add-on ecosystem extends core capabilities with third-party and Cloudinary-built services, including AI-based auto-tagging (Google, Amazon Rekognition, Imagga), background removal, content moderation, OCR text extraction, and document conversion. Add-ons integrate directly with upload and transformation workflows.

Cloudinary also uses webhooks to notify your backend about events triggered by API methods or user actions in the Media Library, such as upload completion, eager transformation results, and moderation outcomes.

## How to use this documentation set

- Use **this page** for product-level orientation and high-level routing.
- Use [`llms.txt`](/llms.txt) for the full documentation map and page relationships.
- Use **quick starts** to get the first working integration.
- Use **task-oriented guides** for end-to-end implementation flow.
- Use **reference pages** for exact parameters, request formats, and transformation syntax.
- If your agent supports MCP, use [Cloudinary AI agent tools and MCP servers](/cloudinary_llm_mcp) to reduce manual API and navigation work.