Programmable Media

Analyze API guide (Beta)

Last updated: Jul-19-2024

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.

The Analyze API is based on version 2 of Cloudinary's APIs, and exposed via OpenAPI for a better developer experience. The API currently contains a single method for analyzing any external asset and returning details based on the type of analysis requested.

Use cases

The Analyze API's ability to analyze external assets can be helpful when you need to analyze images located on external storage.

  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.

The analyze method

You request analysis by using the analyze method of the Analysis API. The method accepts two parameters as follows:

  • uri - (String) The URI of the asset to analyze. Example: https://res.cloudinary.com/demo/image/upload/sample.jpg
  • analysis_type - (Enum) The type of analysis to perform, as shown in the table below.
Parameter Description Learn more
google_tagging Images are automatically tagged according to the categories detected in each image. Google tagging
captioning Analyze an image and suggest a caption based on the image's contents. Captioning
cld_fashion Identify attributes of clothing. Cld Fashion
coco Analyze using the Common Objects in Context model. Coco
lvis Analyze using the Large Vocabulary Instance Segmentation model. Lvis
unidet Analyze using the UniDet model. Unidet
human_anatomy Identify parts of the human body in an image. Human Anatomy
cld_text Tells you if your image includes text, and where it's located. Cld Text
shop_classifier Detects if the image is a product image taken in a studio, or if it's a natural image. Shop Classifier

Our backend SDK libraries provide a wrapper for the analyze method, enabling you to use your native programming language of choice. When using an SDK, request building and authentication are handled automatically, and the JSON response is parsed and returned.

Important
The analysis type requires an active subscription to the relevant add-ons. Learn more about registering for add-ons.

Analyze method examples

  1. Generate a caption for the image located at "https://res.cloudinary.com/demo/image/upload/dog":

  2. Detect if an image was produced in a studio or if it's a natural image using the shop classifier a caption for the image located at "https://res.cloudinary.com/demo/image/upload/shirt":

Analyze method response

The following shows a sample response to a request for captioning:

The Analyze API reference

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

✔️ Feedback sent!

Rate this page: