Ellipse Gradient for Header

Cloudinary Integration Guide

Connect Cloudinary’s media APIs, upload workflows, transformation URLs, and selected processing notifications with enterprise applications through Martini.

Cloudinary integration options at a glance

Cloudinary provides REST-style Upload, Admin, Search, and Provisioning APIs for media ingestion, asset administration, metadata, folders, tags, and account operations. It also supports image, video, and raw-file uploads, large and chunked uploads, transformation and delivery URLs, and operation-specific asynchronous or bulk processing. Cloudinary notifications and callback URLs cover selected upload, transformation, and processing events rather than every asset change. Authentication uses API key and API secret credentials, signed requests, or controlled unsigned upload presets. Martini can consume these APIs, protect credentials in secrets, receive supported notifications through an API, schedule reconciliation workflows, and map Cloudinary assets into downstream systems.

Integration pointSupported by Cloudinary?Common use casesHow Martini supports it
REST APIsYesUse the Upload API for images, videos, and raw files; the Admin API for asset administration; the Search API for asset queries; and the Provisioning API for selected account operations.Martini can consume Cloudinary HTTP APIs, authenticate requests, map payloads, handle pagination, and orchestrate downstream workflows.
Webhooks and outbound callbacksLimitedCloudinary can send notifications for selected uploads, eager transformations, asynchronous processing, and certain media operations.Martini can expose an API to receive notifications, validate payloads, correlate them with workflow state, and trigger downstream processing. Coverage should not be assumed for every asset or metadata change.
Bulk, asynchronous, and batch operationsLimitedCloudinary supports large or chunked uploads, bulk resource administration, asynchronous transformations, and paginated Search or Admin API operations.Martini can split work into bounded batches, track checkpoints, retry transient failures, and coordinate status checks or callbacks for asynchronous processing.
File and attachment APIsYesCloudinary supports image, video, and raw-file uploads, large files, transformed outputs, delivery URLs, and asset deletion.Martini workflows can receive or retrieve files, validate type and size, upload them to Cloudinary, and map returned asset information to other systems.
Media delivery and transformation URLsYesTransformation URLs generate resized, cropped, formatted, quality-optimized, or otherwise processed image and video delivery resources.Martini can construct or map approved transformation parameters and return normalized delivery URLs through workflows or exposed APIs.
Authentication and signed requestsYesCloudinary uses API key and API secret credentials, HTTP Basic Authentication for server-side APIs, signed upload requests, and controlled unsigned upload presets.Martini can store credentials in protected secrets, generate or obtain signatures in server-side workflows, and keep API secrets out of client-facing requests.
Incremental synchronizationLimitedSynchronization can use selected notifications, Search or Admin API pagination, timestamps, metadata filters, and application-maintained checkpoints.Martini can schedule polling and reconciliation workflows, persist checkpoints, process pages, and recover from interrupted synchronization without assuming universal change-data capture.

How Cloudinary exposes data and business events

Cloudinary REST APIs

Cloudinary exposes Upload, Admin, Search, Provisioning, and related HTTP APIs for uploading media, administering assets, querying libraries, managing metadata, and generating integration results. The APIs use operation-specific request and response models and may return paginated or asynchronous results.

Martini implementation pattern

Martini implementation pattern: a workflow authenticates with protected Cloudinary credentials, calls the appropriate API, validates the response, maps Cloudinary objects into a canonical model, and invokes downstream systems or stores a checkpoint for later processing.

Implementation sequence

Receive a source request or scheduled trigger
Select the Cloudinary API operation
Authenticate using protected credentials or a controlled signature
Send the request with validated parameters
Process pagination or asynchronous status information
Map the response into the target model and persist the result

Cloudinary notifications

Cloudinary supports callback and notification requests for selected uploads, eager transformations, asynchronous processing, and certain media operations. Notification coverage is operation-specific and does not constitute a universal event stream for all asset, folder, metadata, or administrative changes.

Martini implementation pattern

Martini implementation pattern: expose a controlled API endpoint, validate the notification and its correlation data, retrieve the current Cloudinary asset when necessary, apply business rules, and update downstream systems. A scheduled reconciliation workflow can cover missed or unsupported changes.

Implementation sequence

Receive the Cloudinary notification
Validate the payload and expected correlation data
Retrieve the current asset or processing status when required
Apply business rules for the reported operation
Map the result to the downstream application
Record completion and route failures for retry or reconciliation

Cloudinary file uploads

Cloudinary supports image, video, and raw-file uploads, including large and chunked uploads. Upload requests may use signed parameters or controlled unsigned upload presets, and the returned asset may still require asynchronous processing before all derived resources are ready.

Martini implementation pattern

Martini implementation pattern: receive a file or source reference, validate media characteristics, select a restricted preset or generate a server-side signature, upload through the Cloudinary Upload API, and publish asset information only after the required processing state is confirmed.

Implementation sequence

Receive or retrieve the source file
Validate resource type, size, format, and naming
Select an upload preset or generate a protected signature
Upload the file to Cloudinary
Wait for processing completion or receive a supported notification
Return the asset ID, public ID, and approved delivery URL

Cloudinary Search and Admin synchronization

The Search and Admin APIs support asset queries, metadata and tag retrieval, administrative operations, and paginated access to media libraries. Cloudinary does not provide a confirmed universal change-data-capture stream for every asset or metadata change.

Martini implementation pattern

Martini implementation pattern: schedule a workflow that queries the appropriate endpoint, follows documented pagination or cursors, filters by a suitable timestamp or metadata condition, maps each page to the target model, and stores a checkpoint for restart and reconciliation.

Implementation sequence

Start the scheduled synchronization workflow
Load the last successful checkpoint
Query Cloudinary with the appropriate filter or expression
Process each paginated result set
Map assets and metadata to the target system
Persist the checkpoint and report rejected or failed items

Common Cloudinary integration patterns

Pattern 1: Synchronize product media to Cloudinary

When to use this pattern

Use this pattern when a commerce or catalog application is the source of product images, videos, or variant media and Cloudinary should manage ingestion, transformation, and delivery. Stable public IDs and explicit overwrite or versioning rules prevent duplicate assets.

Integration direction
Shopify
Martini
Cloudinary
Example Mapping
Cloudinary FieldCanonical FieldTarget Field
product.idsourceProductIdcontext.product_id
variant.skuassetKeypublic_id
media.urlsourceMediaUrlfile
media.typeresourceTyperesource_type
Martini implementation pattern

Martini receives catalog changes, resolves a deterministic public ID using product, tenant, locale, and asset type, validates the file, and calls the Upload API with a permitted preset or signed request. The workflow applies overwrite or versioning rules, waits for required transformations, then returns the Cloudinary asset ID and delivery URL to the catalog system. Transient failures are retried with bounded backoff, while duplicate or invalid media is routed for review.

Martini capabilities used
  • workflows
  • API consumption
  • data mapping
  • business rules
  • secrets management
  • error handling

Pattern 2: Synchronize Cloudinary metadata to a content platform

When to use this pattern

Use this pattern when a PIM, DAM, CMS, or commerce platform needs a current view of Cloudinary assets, tags, folders, and contextual or structured metadata. It is suited to large libraries where pagination and checkpoints are required.

Integration direction
Cloudinary
Martini
Contentful
Example Mapping
Cloudinary FieldCanonical FieldTarget Field
asset.asset_idexternalAssetIdcloudinaryAssetId
asset.public_idassetKeyfileNameOrReference
asset.tagslabelsmetadata.tags
asset.contextassetContextmetadata.context
Martini implementation pattern

A scheduled Martini workflow queries the Search or Admin API, follows documented pagination, filters by a suitable timestamp or expression, and maps each asset into the target content model. It stores a checkpoint after successful pages, preserves unknown metadata where required, and performs reconciliation for missed notifications or downstream failures. Updates are made idempotent using the Cloudinary asset ID or public ID.

Martini capabilities used
  • scheduler-triggered workflows
  • API consumption
  • pagination orchestration
  • data mapping
  • checkpoint management
  • error handling

Pattern 3: Process Cloudinary completion notifications

When to use this pattern

Use this pattern when downstream systems must react after an upload, eager transformation, or selected asynchronous media operation completes. Because notification coverage is selective, pair it with scheduled reconciliation when business completeness matters.

Integration direction
Cloudinary
Martini
Salesforce Commerce Cloud
Example Mapping
Cloudinary FieldCanonical FieldTarget Field
notification.public_idassetKeymedia.publicId
notification.resource_typeresourceTypemedia.type
notification.secure_urldeliveryUrlmedia.url
notification.statusprocessingStatusmedia.status
Martini implementation pattern

Martini exposes an API for Cloudinary notifications, validates the payload, correlates it with the originating upload or business transaction, and retrieves the current asset when the notification is incomplete. Business rules determine whether the asset is ready for publication, after which the workflow updates the target application. Duplicate notifications are handled idempotently and unprocessed items can be found by reconciliation polling.

Martini capabilities used
  • API exposure
  • webhook consumption
  • validation
  • business rules
  • data mapping
  • idempotency
  • monitoring

Pattern 4: Expose a controlled media ingestion API

When to use this pattern

Use this pattern when internal applications should submit media without receiving Cloudinary credentials or implementing Cloudinary-specific request signing and response handling themselves.

Integration direction
Internal application
Martini
Cloudinary
Example Mapping
Cloudinary FieldCanonical FieldTarget Field
request.filemediaFilefile
request.assetKeyrequestedPublicIdpublic_id
request.mediaTyperesourceTyperesource_type
Cloudinary.asset_idexternalAssetIdresponse.assetId
Martini implementation pattern

Martini exposes a secured API that validates the caller, file characteristics, requested public ID, and allowed transformation options. A workflow selects the appropriate upload preset or creates a server-side signature, uploads to Cloudinary, waits for required processing, and returns a normalized response containing asset identifiers and delivery information. Validation failures are rejected immediately; transient Cloudinary errors are retried without re-uploading blindly.

Martini capabilities used
  • API exposure
  • authentication and authorization
  • workflows
  • file handling
  • secrets management
  • data transformation
  • retry and error handling

Applications commonly integrated with Cloudinary

Cloudinary can sit alongside commerce, content, customer, and delivery platforms as a specialized media management and transformation layer. The following are common or conservative enterprise architecture patterns; exact object-level behavior should be validated for each product implementation.

Application Scenario Direction Martini Pattern
Shopify Synchronize product images, promotional media, and variant assets while storing optimized Cloudinary delivery URLs in the commerce catalog. Shopify → Martini → Cloudinary Martini receives product or catalog changes, resolves a deterministic public ID, uploads or updates the media through the Cloudinary Upload API, and returns the asset ID, public ID, and delivery URL to Shopify.
Adobe Commerce Centralize product and merchandising media in Cloudinary while providing transformed image and video URLs to storefront content. Adobe Commerce → Martini → Cloudinary A Martini workflow extracts catalog media references, validates resource type and format, uploads assets using the appropriate preset, and maps Cloudinary URLs and processing status back to Adobe Commerce.
Salesforce Commerce Cloud Manage storefront media separately from commerce catalog data and publish optimized Cloudinary delivery URLs for products and campaigns. Salesforce Commerce Cloud → Martini → Cloudinary Martini orchestrates catalog-to-media ingestion, applies naming and transformation rules, waits for required asynchronous processing, and updates Salesforce Commerce Cloud with the resulting media references.
Contentful Coordinate editorial content references in Contentful with media assets, metadata, and delivery URLs managed by Cloudinary. Contentful → Martini → Cloudinary Martini maps Contentful media metadata to Cloudinary upload parameters, preserves source identifiers and relationships, and writes normalized asset information back to content entries or an integration store.
WordPress Use Cloudinary transformations, optimization, and delivery for media consumed by WordPress sites. WordPress → Martini → Cloudinary A Martini workflow receives media references or export requests from WordPress, uploads or resolves the corresponding Cloudinary asset, and returns validated delivery URLs and processing status.
Salesforce Associate campaign, product, or customer-facing content with centrally managed Cloudinary media assets. Salesforce → Martini → Cloudinary Martini coordinates Salesforce business objects with Cloudinary asset metadata, applies rules for permitted formats and public IDs, and writes asset references or status updates to Salesforce.
Akamai Coordinate Cloudinary media transformation and origin delivery with broader enterprise edge distribution and caching requirements. Cloudinary → Martini → Akamai Martini can normalize Cloudinary delivery URLs and distribution metadata, apply routing or publishing rules, and pass approved media references to Akamai-related delivery processes where the architecture requires orchestration.
Bynder Exchange or coordinate media assets and metadata between Cloudinary and another digital asset management environment. Bynder → Martini → Cloudinary A scheduled or event-driven Martini workflow retrieves changed assets and metadata, maps tags and contextual fields, applies duplicate-prevention rules, and synchronizes approved media references between the platforms.

How to build a Cloudinary integration in Martini

Objective

Establish server-side access to Cloudinary without exposing the API secret or unrestricted upload controls to client applications.

Instructions in Martini

  • Store the Cloudinary cloud name, API key, API secret, and preset settings in protected Martini secrets or environment configuration.
  • Choose API key and secret authentication, signed requests, or a restricted unsigned preset for the specific operation.
  • Configure the Cloudinary endpoint and request authentication in the Martini workflow or reusable service.

Objective

Select an event-driven, API-led, or scheduled entry point based on the Cloudinary operation and its notification coverage.

Instructions in Martini

  • Use an exposed Martini API for application-initiated uploads or Cloudinary notifications.
  • Use a scheduler trigger for Search or Admin API polling and reconciliation.
  • Treat notifications as selected-operation callbacks rather than a universal asset change stream.

Objective

Acquire the source file, Cloudinary notification, or paginated asset response needed for processing.

Instructions in Martini

  • Receive or retrieve the source media and validate its resource type, format, size, and dimensions.
  • For callbacks, validate the payload and correlate it with the expected upload or workflow execution.
  • For synchronization, load the saved checkpoint and retrieve pages using the documented Cloudinary pagination behavior.

Objective

Coordinate Cloudinary requests, asynchronous processing, downstream updates, and recovery logic in a maintainable Martini workflow.

Instructions in Martini

  • Call the Upload, Admin, Search, or relevant Cloudinary endpoint.
  • Separate upload acceptance from completion of asynchronous transformations or derived assets.
  • Use reusable logic for signing, public ID construction, status checks, and response normalization.

Objective

Convert Cloudinary assets and metadata into the canonical model required by the target application.

Instructions in Martini

  • Map asset IDs, public IDs, resource types, formats, tags, folders, metadata, and delivery URLs.
  • Transform contextual or structured metadata to the target schema and preserve approved unknown fields where forward compatibility is needed.
  • Construct only validated transformation URLs and do not accept unrestricted transformation instructions from untrusted callers.

Objective

Enforce naming, duplicate prevention, publishing, security, and media readiness decisions before writing downstream data.

Instructions in Martini

  • Apply deterministic public ID, tenant, locale, and versioning rules.
  • Decide whether an existing public ID is overwritten, versioned, or rejected.
  • Publish delivery URLs only when the required Cloudinary processing is complete.

Common Cloudinary data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
AssetsRepresent uploaded images, videos, and raw files with public IDs, asset IDs, resource types, formats, tags, metadata, and delivery information.Shopify, Adobe Commerce, Contentful, WordPress, Salesforce, BynderMartini uploads, retrieves, validates, maps, and synchronizes asset attributes while applying deterministic naming and idempotency rules.
FoldersOrganize assets and public IDs into logical structures for applications, tenants, products, or campaigns.Commerce platforms, Contentful, Bynder, internal media catalogsMartini maps source hierarchy to Cloudinary folder conventions and applies business rules before creating or referencing folder paths.
TransformationsDefine resizing, cropping, formatting, quality optimization, overlays, video processing, and other media operations.Shopify, Adobe Commerce, Salesforce Commerce Cloud, WordPress, AkamaiMartini validates approved transformation parameters, constructs delivery URLs, and waits for required asynchronous processing before publishing results.
Upload presetsControl upload behavior, transformations, naming, access settings, and related ingestion options.Internal ingestion services, commerce platforms, CMS applicationsMartini selects presets by source or channel and keeps preset identifiers in protected configuration rather than accepting unrestricted client input.
TagsLabel assets for organization, search, campaign grouping, and downstream processing.Contentful, Bynder, commerce catalogs, marketing applicationsMartini maps source classifications to Cloudinary tags, preserves unmapped values where appropriate, and uses tags in Search API synchronization.
Contextual and structured metadataStore key-value context and schema-based metadata associated with assets.PIM, DAM, CMS, commerce platforms, internal asset repositoriesMartini transforms metadata schemas, handles missing or new fields, preserves forward-compatible values, and writes validated metadata to downstream systems.

Authentication and security considerations

Protect API credentials and signatures

Cloudinary API keys and API secrets support server-side authentication, while signed uploads use the API secret to calculate request signatures. Store these values in protected Martini secrets or environment configuration and keep the API secret out of client-facing code and payloads.

Control upload policies

Use signed uploads or carefully restricted unsigned upload presets according to the ingestion channel. Limit permitted resource types, formats, folders, public IDs, and transformations rather than accepting unrestricted client input.

Secure callback APIs

Protect Martini APIs that receive Cloudinary notifications with appropriate authentication or validation controls. Validate payloads, correlate notifications with expected workflow state, and do not trust inbound public IDs or URLs without business validation.

Operational considerations for Cloudinary integrations

Pagination and checkpoints

Search and Admin API operations can return paginated results. Follow documented cursors or pagination fields and persist checkpoints so scheduled synchronization can resume safely.

Rate limits and retries

Cloudinary limits can vary by operation and plan. Use bounded retries with backoff for transient failures and avoid retrying non-idempotent uploads without a duplicate-prevention strategy.

Asynchronous processing

An accepted upload does not necessarily mean that every transformation or derived asset is ready. Use supported notifications or status checks before publishing delivery URLs downstream.

Idempotency and schema changes

Use deterministic public IDs, source identifiers, or correlation keys to handle duplicate notifications and repeated executions. Define mappings for missing, renamed, and newly introduced tags or metadata fields.

Testing and reconciliation

Test images, videos, raw files, large uploads, invalid formats, asynchronous transformations, notification retries, and downstream failures. Schedule reconciliation when notifications do not cover the required business change set.

Why use Martini instead of scripts or point-to-point integrations?

Centralize integration logic

Martini separates Cloudinary-specific authentication, signing, upload behavior, pagination, and response handling from downstream application logic. Reusable workflows and services reduce duplicated implementation across commerce, content, and internal applications.

Support multiple integration styles

Martini can consume Cloudinary REST APIs, expose controlled APIs for internal media ingestion, receive selected notifications, and run scheduled reconciliation workflows. This supports real-time, asynchronous, and batch-oriented designs in one integration environment.

Make transformations and rules explicit

Mappings, validation, public ID conventions, metadata rules, publishing conditions, and duplicate handling can be maintained as workflow behavior rather than scattered across scripts or point-to-point integrations.

Improve operational control

Workflow-level error handling, retries, checkpoints, logging, and monitoring provide a consistent operational model for large media libraries and asynchronous processing. This is particularly useful when Cloudinary notifications cover only selected operations.

Frequently asked questions

How can Cloudinary be integrated with enterprise systems?

Cloudinary can be integrated through its Upload, Admin, Search, and selected Provisioning REST APIs; image, video, and raw-file upload endpoints; transformation and delivery URLs; and notifications for selected upload or processing operations. Enterprise workflows commonly combine API calls, controlled request signing, scheduled synchronization, pagination, and downstream metadata mapping.

Can Martini integrate with Cloudinary?

Yes. Martini can consume Cloudinary REST APIs, orchestrate signed or unsigned upload workflows, receive supported Cloudinary notifications through an exposed API, map asset and metadata responses, and run scheduled reconciliation workflows where notification coverage is incomplete.

Do I need a connector to integrate Cloudinary with Martini?

No. A dedicated Cloudinary connector is not required. Martini can integrate using Cloudinary’s confirmed native REST APIs, file upload endpoints, delivery URLs, notification callbacks, authentication methods, and scheduled polling patterns.

Is there any extra Lonti cost to integrate Cloudinary with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate Cloudinary with Martini. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Cloudinary, infrastructure providers, or other third-party systems based on subscriptions, usage, and deployment choices.

Which Cloudinary integration methods should an enterprise use?

Use the Upload API for media ingestion, the Admin API for administration and metadata operations, and the Search API for asset queries and synchronization. Use transformation and delivery URLs for approved media variants, notifications for selected asynchronous events, and scheduled reconciliation when a complete change feed is required.

Can Martini receive Cloudinary events or webhooks?

Martini can expose an API to receive Cloudinary callback or notification requests for selected uploads, eager transformations, asynchronous processing, and related operations. Cloudinary does not provide a confirmed universal event stream for every asset, folder, metadata, or administrative change, so polling may still be necessary.

How does synchronization and data mapping work between Cloudinary and other systems?

Martini can retrieve Cloudinary assets through the Search or Admin API, follow pagination, map asset IDs, public IDs, resource types, tags, folders, and metadata to a target schema, and persist checkpoints for incremental processing. Notifications can accelerate selected changes, while reconciliation workflows address missed or unsupported events.

How does Martini handle Cloudinary errors, retries, and duplicate assets?

Martini workflows can classify Cloudinary response errors, apply bounded retries with backoff for transient failures, and route permanent failures for review. Stable public IDs, source identifiers, checksums, or correlation keys can support idempotency and prevent blind re-uploading or duplicate downstream updates.

Related Martini documentation

Martini APIs

Workflows

Security

Operations

Connect Cloudinary to your enterprise systems

Use Martini to orchestrate Cloudinary media ingestion, asset synchronization, processing notifications, transformations, and secure API workflows across your application landscape.

EXPLORE MARTINI
BOOK A DEMO