Programmable Media
Menu

Analyze API guide (Beta)

Last updated: Nov-28-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 a version 2 Cloudinary API, and exposed via OpenAPI for a better developer experience. The API currently contains endpoints for analyzing any external asset and returning details based on the type of analysis requested.

On this page:

Use cases

The Analyze API analyzes external assets and 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.

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

The analyze endpoints

You request analysis by using the analyze endpoints of the Analysis API. All the endpoints required at least the source parameter:

  • 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: source: {uri: "https://www.example.com/pic.jpg"}

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

The API exposes the following endpoints from the root:

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

Endpoint Description
ai_vision_tagging Classify images using your custom tag definitions with AI Vision tagging - 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_general General Get detailed answers to open-ended questions about your images - Requires a subscription to the AI Vision 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.
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.
coco Analyze using the Common Objects in Context model with Coco - 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.
unidet Analyze using the UniDet model with Unidet - Requires a subscription to the Cloudinary AI Content Analysis 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.
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.
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.

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

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

Request examples

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

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

  3. 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":

Response example

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: