Programmable Media
Menu

Analyze API guide (Beta)

Last updated: Feb-03-2025

Important
The Analyze API is currently in development and is available as a Public Beta, which means we value your feedback, so please feel free to share any thoughts with us.

Overview

The Analyze API provides a dedicated standalone mechanism for analyzing your assets programmatically.

Select an analysis type and return details about your assets based on the type of analysis requested. Run analysis on assets stored with Cloudinary, or located externally.

On this page:

Analyze your assets using a variety of models available by enabling different Cloudinary Add-ons:

  • AI Vision - Uses natural language and prompting to enable AI to interpret and respond to visual content queries for tagging, moderation or general queries.
  • Cloudinary AI Content Analysis - Contains a number of models for identifying a wide range of subjects in your images, such as objects, fashion items, human anatomy and text.
  • Google Tagging - Automatically tag your assets or detect logos.

For a full list of all available models and their endpoints, see the API reference.

Below are some use-cases for when you might want to use the Analyze API as part of your media workflows:

  1. Before uploading images to Cloudinary:

    • Run captioning analysis and upload the image only if specific words appears in the result.
    • Run face analysis and upload only images with/without faces

  2. Run captioning on external storage images, store the results and then you can search by the captioning field - to implement your own Visual Search on external storage.

  3. Ask questions about an image, identifying objects, describing scenes, or even evaluating if the image meets specific content guidelines.

Analyze an asset

To Analyze an asset, identify the model you want to use and send a POST request to the corresponding endpoint:

  • Base URL: https://api.cloudinary.com/v2/analysis/<cloud_name>/analyze/
  • Model endpoint: {model name} e.g. captioning.

For example, to use the AI Vision Tagging model for analysis, the endpoint would be:

https://api.cloudinary.com/v2/analysis/<cloud_name>/analyze/ai_vision_tagging.

As part of your request, include at least the source object as part of your JSON request body:

  • source - (JSON) An object containing the location of the file to analyze, either:
    • uri - (String) The URI of the asset to analyze. Example: https://res.cloudinary.com/demo/image/upload/sample.jpg
    • asset_id - (String) The automatically generated and immutable unique identifier for the asset stored in Cloudinary.

For example:

For some models, you need to supply additional data, such as prompts or tag definitions. See the API reference for full details on request parameters.

The following model endpoints are available for use with the Analyze API:

Endpoint Description
ai_vision_general General Get detailed answers to open-ended questions about your images - Requires a subscription to the AI Vision add-on.
ai_vision_moderation Moderation Assess images against specific criteria for content moderation purposes - Requires a subscription to the AI Vision add-on.
ai_vision_tagging Classify images using your custom tag definitions with AI Vision tagging - Requires a subscription to the AI Vision add-on.
captioning Analyze an image and suggest a caption based on the image's contents with Captioning - Requires a subscription to the Cloudinary AI Content Analysis add-on.
cld_fashion Identify attributes of clothing with Cld Fashion - Requires a subscription to the Cloudinary AI Content Analysis add-on.
cld_text Tells you if your image includes text, and where it's located with Cld Text - Requires a subscription to the Cloudinary AI Content Analysis add-on.
coco Analyze using the Common Objects in Context model with Coco - Requires a subscription to the Cloudinary AI Content Analysis add-on.
google_logo_detections Detect if any logos exist in an image - Requires a subscription to the Google tagging add-on.
google_tagging Images are automatically tagged according to the categories detected in each image with Google tagging - Requires a subscription to the Google tagging add-on.
human_anatomy Identify parts of the human body in an image with Human Anatomy - Requires a subscription to the Cloudinary AI Content Analysis add-on.
image_quality Analyze the quality of an image using the Image Quality Analysis (IQA) model - Requires a subscription to the Cloudinary AI Content Analysis add-on.
lvis Analyze using the Large Vocabulary Instance Segmentation model with Lvis - Requires a subscription to the Cloudinary AI Content Analysis add-on.
shop_classifier Detects if the image is a product image taken in a studio, or if it's a natural image with Shop Classifier - Requires a subscription to the Cloudinary AI Content Analysis add-on.
unidet Analyze using the UniDet model with Unidet - Requires a subscription to the Cloudinary AI Content Analysis add-on.
watermark_detection Detect if any watermarks exist in an image using Watermark Detection - Requires a subscription to the Cloudinary AI Content Analysis add-on.

Important
Many of the above require an active subscription to the relevant add-ons. Learn more about registering for add-ons.

Asynchronous requests

Depending on the model you use, the time for analysis can differ, therefore you may want to trigger analysis asynchronously for supported models and receive the results via a webhook/notification URL.

To trigger analysis asynchronously, set the async parameter to true as part of your request body. When sending your initial request, you receive a 202 response and the response data includes a task ID which is for checking analysis status.

For example:

Once analysis is complete, the data gets sent to a notification URL. Define this notification URL as part of your request body using the notification_url parameter. If not specified, the response gets sent to the Notification URL (if defined) in the Webhook Notifications settings of your Cloudinary Console.

Checking analysis status

To check the status of an analysis request, use the tasks endpoint and supply the taskId returned as part of your initial request.

For example, if your taskId is 123456, send a get request to https://api.cloudinary.com/v2/analysis/<cloud_name>/tasks/123456.

The response includes the status of the request which could be one of pending, processing, completed or failed.

For example:

Examples

Moderate the image located at "https://res.cloudinary.com/demo/image/upload/woman-business-suit" for alcohol and nudity:

Request

Response

Generate a caption for the image located at "https://res.cloudinary.com/demo/image/upload/cld-sample":

Request

Response

Detect whether an image is studio produced or a natural image using the shop classifier for the image located at "https://res.cloudinary.com/demo/image/upload/shirt":

Request

Response

API reference

For full details on the Analyze API see the Analyze API reference.

✔️ Feedback sent!

Rate this page: