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.

Image & Video APIs
Menu

Image analysis

Last updated: May-28-2026

The Cloudinary AI Content Analysis add-on provides three image analysis capabilities: image quality analysis, watermark detection, and AI-based image captioning.

On this page:

Image quality analysis

You can analyze the quality of an image using the Image Quality Analysis (IQA) model by setting the detection parameter to iqa when calling Cloudinary's upload or update methods.

A quality score from 0 to 1 is returned in the score attribute of the response, and a general quality estimation of low, medium, or high is returned in the quality attribute.

For example, invoking the iqa model while uploading winter_fashion.jpg:

The response includes the iqa-analysis field:

Notes

Watermark detection

You can detect watermarks in images by setting the detection parameter to watermark-detection when calling Cloudinary's upload or update methods. The response can be one of the following: banner (see Banners), watermark (see Watermarks), or, if neither of these are detected, clean.

Note
You can add the tags, banner, watermark or clean by setting the auto_tagging parameter, as described in Adding tags to images and you can also use asynchronous handling.

Banners

If the image contains an opaque text/logo layer with a semi-transparent background it is likely that the image will be flagged as containing a banner.

For example, uploading the following image, requesting watermark-detection, the response shows 99% confidence that it contains a banner:

Example of a banner watermark

Upload request:

The response includes:

Watermarks

If the image contains a semi-transparent layer, it is likely that the image will be flagged as containing a watermark.

For example, uploading the following image, requesting watermark-detection, the response shows 99% confidence that it contains a watermark:

Example of a watermark

Upload request:

The response includes:

AI-based image captioning

The Cloudinary AI Content Analysis add-on can be used to analyze an image and suggest a caption based on the image's contents.

Some example captions suggested by the AI:

a brown dog standing on top of a street next to a sidewalk with a building in the back ground a group of young children playing soccer on a soccer field with a goal post in the foreground and a goal post in the background a hand reaching for a donut with chocolate and sprinkles on it on a dark surface
  1. A brown dog standing on top of a street next to a sidewalk with a building in the background
  2. A group of young children playing soccer on a soccer field with a goal post in the foreground and a goal post in the background
  3. A hand reaching for a donut with chocolate and sprinkles on it on a dark surface

By setting the detection parameter to captioning when calling Cloudinary's upload or update methods, the add-on automatically analyzes the content of the image. For example, invoking the captioning detection model while uploading toy_room.jpg:

Toy room

Tip

You can use upload presets to centrally define a set of upload options including add-on operations to apply, instead of specifying them in each upload call. You can define multiple upload presets, and apply different presets in different upload scenarios. You can create new upload presets in the Upload Presets page of the Console Settings or using the upload_presets Admin API method. From the Upload page of the Console Settings, you can also select default upload presets to use for image, video, and raw API uploads (respectively) as well as default presets for image, video, and raw uploads performed via the Media Library UI.

Learn more: Upload presets

The upload API response includes the captioning information:

Tips
  • You can retrieve the caption text value from the response and then use the update method of the Admin API to add the caption text to the metadata of images stored in your product environment, such as the contextual metadata (context) or a structured metadata field (metadata).
  • After you've requested a caption using the upload or update method, you can use the Admin API get details of a single resource method to return details of the image, including the stored caption value.
  • You can also request analysis using the Analyze API (Beta) which also accepts external assets to analyze.
  • Watch a video tutorial showing how to automatically set alt text for images in a Next.js application.

Asynchronous handling

As the response may not be immediate, it is good practice to use asynchronous handling for these calls.

To make the call asynchronous, set the async parameter of the upload method to true. To be notified when the processing is complete, you can either set the notification_url parameter of the upload method (as in the example below) or the global webhook Notification URL in the Upload page of your Cloudinary Console Settings.

The response to an asynchronous upload call looks similar to this:

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

✔️ Feedback sent!

Rate this page:

one star two stars three stars four stars five stars