Post-upload processing

In addition to the upload control parameters that control what happens during the upload itself, you can also include options in your upload call or upload preset that trigger additional processing after Cloudinary uploads and stores the asset. Even though you specify these options up front, they run asynchronously in the background after Cloudinary stores the asset, and you can use webhook notifications to monitor when processing completes.

This page covers the post-upload processing parameters: moderation, analysis, on-success event handling, and running otherwise synchronous operations asynchronously.

Moderation

Moderating assets before they go live lets you keep out inappropriate or offensive content, reject assets that don't meet your quality standards, and ensure that only the right content reaches your audience. This is especially important for platforms that accept user-generated content (UGC), where you can't control what users upload.

You can manually mark an uploading asset for moderation or use one of the AI-based add-ons to automatically moderate assets at upload time. Assets added to the moderation queue can then be reviewed in the Media Library.

For example, you can moderate assets while uploading them by specifying the moderation parameter in the upload method. The following code marks an image for moderation by the WebPurify's Image Moderation add-on and the Cloudinary Duplicate Image Detection add-on:

Analysis

When uploading assets to your Cloudinary product environment, you can request different types of analysis to be performed on the assets. In addition to Image quality analysis, Accessibility analysis, and Semantic data extraction, Cloudinary has a number of add-ons that enable various types of AI-based analyses.

For example, you can request quality and accessibility analysis on assets while uploading them by specifying the quality_analysis and accessibility_analysis parameters in the upload method. The following code uploads the user_photo.jpg image and requests analysis:

The following is an example of the response returned:

On success: Update metadata after upload

The on_success parameter lets you customize asset behavior after a successful upload by running JavaScript code. Use it when you need information that's only available after the upload completes, such as AI captioning results, quality analysis scores, or face detection data.

How it works

You write JavaScript to:

• Inspect e.upload_info (event.upload_info), which contains the full upload response, e.g.:

  • e.upload_info.width – to check final dimensions
  • e.upload_info.info.detection.captioning – to access AI analysis results
    Note

    You can also check e.status, which is either "success" or "failure". This is rarely needed for on_success (since it only runs on success), but may be useful in shared scripts used across multiple event types (e.g., on_error, on_failure).

• Call current_asset.update() to assign new values to:

  • tags – list of tags
  • context – contextual key-value metadata
  • metadata – structured metadata fields from your product environment
    Note

    The values you assign with current_asset.update() replace any existing values. They aren't merged or appended.

Quick example: Add a caption after upload

Set a "caption" in the asset's contextual metadata based on the uploaded file's name.

• Here's the JavaScript code to include in your upload call as a string;

• Here's how to include that code in your upload request across various SDKs:

Examples

Save an AI-generated caption as contextual metadata

Upload an asset and update its contextual metadata (context) with the caption returned from the Cloudinary AI Content Analysis add-on, and add the tag 'autocaption' (current_asset.update({tags: ['autocaption'], context: {caption: e.upload_info?.info?.detection?.captioning?.data?.caption}})):

Set structured Metadata for large images

Assign values to different types of structured metadata, but only if the image width exceeds 1000 pixels.

• Assign high to the single-select structured metadata field, rating.

• Assign ['print', 'web', 'social'] to the multiselect structured metadata field usage_types.

Append to existing tags

To add tags without losing any existing tags, explicitly include the current tags from the upload response:

Requesting asynchronous uploads

By default, when you call the upload method, Cloudinary processes the upload and returns a response synchronously. However, note that many of the post-upload processing options on this page (such as moderation, analysis, and transcription) always run asynchronously regardless of this setting, and return a pending status in the upload response.

For uploads that would otherwise be handled synchronously, you can request asynchronous processing by setting the async parameter to true. This is recommended for large assets or uploads that include parameters that take a long time to process, where waiting for the synchronous response would result in a poor experience for your users. When async is true, Cloudinary returns a short response immediately with a pending status and a batch ID, and sends the full upload response to your notification URL once processing is complete.

For example, to asynchronously upload an image, request the Content Analysis add-on to analyze the image and suggest a caption, and then send a notification to "https://mysite.example.com/upload_endpoint" when the processing is complete with the full upload response:

The immediate response to an asynchronous upload call is short and looks similar to this:

When the processing is finished, the complete upload response is sent to the notification URL that you specified.

Webhook notifications

Cloudinary provides webhook notifications to inform your backend about upload events. When the upload is completed, an HTTP POST request can be sent to a public notification URL you provide. The payload contains all the results pertinent to the upload.

You can use webhook notifications with any upload, but we recommend using them whenever your upload includes asynchronous post-upload operations. This ensures your application is notified when processing completes.

For example, you can ask Cloudinary to send a notification when an asset finishes uploading, by specifying the notification_url parameter in the upload method. The following code uploads the sample.jpg image and then sends a notification to https://mysite.example.com/my_notification_endpoint.

For example, to add a notification_url to a specific upload call: