OAS 3.0.3

Analyze API (Beta)

Overview

The Analyze API provides a 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.

Take advantage of Cloudinary AI Vision for visual content queries or perform analysis using a variety of models included with Cloudinary AI Content Analysis.

See the Analyze API guide for more details about the analysis options and how to use the API.

Notes:

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 analysis options require an active subscription to the relevant add-on. Learn more about registering for add-ons.

Authentication

The Analyze API supports both Basic Authentication using your Cloudinary API Key and API Secret (which can be found on the Dashboard page of your Cloudinary Console) or OAuth2 (Contact support for more information regarding OAuth).

Base URL

cloud_name

Basic Authentication (basicAuth)

Client Libraries

Shell

Ruby

Node.js

PHP

Python

cURL Shell

Analysis

Use the Analyze API to analyze any external asset and return details based on the type of analysis requested.

Endpoints

POST/analyze/ai_vision_general POST/analyze/ai_vision_moderation POST/analyze/ai_vision_tagging POST/analyze/captioning POST/analyze/cld_fashion POST/analyze/cld_text POST/analyze/coco POST/analyze/google_logo_detection POST/analyze/google_tagging POST/analyze/human_anatomy POST/analyze/image_quality POST/analyze/lvis POST/analyze/shop_classifier POST/analyze/unidet POST/analyze/watermark_detection

Analyze - AI Vision General

The General mode serves a wide array of applications by providing detailed answers to diverse questions about an image. Users can inquire about any aspect of an image, such as identifying objects, understanding scenes, or interpreting text within the image.

Body

application/json

A JSON object containing request parameters

allOf

Responses

200Analysis succeeded
application/json
202Analysis accepted
application/json
400Bad request
application/json
401Unauthorized
application/json
403Forbidden
application/json
404Not found
application/json
429Rate limited
application/json
500Internal server error
application/json

POST/analyze/ai_vision_general

Shell cURL

curl --request POST \
  --url https://api.cloudinary.com/v2/analysis/CLOUD_NAME/analyze/ai_vision_general \
  --header 'Authorization: Basic' \
  --data '{
  "source": {
    "uri": "https://res.cloudinary.com/demo/image/upload/sample.jpg"
  },
  "prompts": [
    "Describe this image in detail",
    "Does this image contain an insect?"
  ]
}'

Passing an image URL to AI Vision General

Show Schema

{
  "data": {
    "entity": "…",
    "analysis": {
      "responses": [
        {
          "value": "The image contains one cat."
        },
        {
          "value": "The cat is on top of the table."
        }
      ],
      "model_version": 1
    }
  },
  "limits": {
    "items": [
      {
        "type": "ai_vision",
        "used_by_request": 123,
        "remaining": 500,
        "limit": 10000,
        "reset_time": "2024-01-20T12:34:56Z"
      }
    ]
  },
  "request_id": "17c3b70c5096df0e77e838323abb7029"
}

Analysis succeeded

Analyze - AI Vision Moderation

The Moderation mode accepts multiple questions about an image, to which the response provides concise answers of "yes," "no," or "unknown." This functionality allows for a nuanced evaluation of whether the image adheres to specific content policies, creative specs, or aesthetic criteria.

Body

application/json

A JSON object containing request parameters

allOf

Responses

200Analysis succeeded
application/json
202Analysis accepted
application/json
400Bad request
application/json
401Unauthorized
application/json
403Forbidden
application/json
404Not found
application/json
429Rate limited
application/json
500Internal server error
application/json

POST/analyze/ai_vision_moderation

Shell cURL

curl --request POST \
  --url https://api.cloudinary.com/v2/analysis/CLOUD_NAME/analyze/ai_vision_moderation \
  --header 'Authorization: Basic' \
  --data '{
  "source": {
    "uri": "https://res.cloudinary.com/demo/image/upload/sample.jpg"
  },
  "rejection_questions": [
    "Does this image contain any violent activity?",
    "Is there any nudity in the image?"
  ]
}'

Passing an image URL to AI Vision Moderation

Show Schema

{
  "data": {
    "entity": "…",
    "analysis": {
      "responses": [
        {
          "prompt": "Does the image contain any violent activity?",
          "value": "no"
        },
        {
          "prompt": "Is there any nudity in the image?",
          "value": "yes"
        }
      ],
      "model_version": 1
    }
  },
  "limits": {
    "items": [
      {
        "type": "ai_vision",
        "used_by_request": 123,
        "remaining": 500,
        "limit": 10000,
        "reset_time": "2024-01-20T12:34:56Z"
      }
    ]
  },
  "request_id": "17c3b70c5096df0e77e838323abb7029"
}

Analysis succeeded

Models


Key Required
Secret

Key

Value

{

"source": {

"uri": "https://res.cloudinary.com/demo/image/upload/sample.jpg"

"prompts": [

"Describe this image in detail",

"Does this image contain an insect?"

]

}

Response

.,,uod8B8bou,,. ..,uod8BBBBBBBBBBBBBBBBRPFT?l!i:. ||||||||||||||!?TFPRBBBBBBBBBBBBBBB8m=, |||| '""^^!!||||||||||TFPRBBBVT!:...! |||| '""^^!!|||||?!:.......! |||| ||||.........! |||| ||||.........! |||| ||||.........! |||| ||||.........! |||| ||||.........! |||| ||||.........! ||||, ||||.........` |||||!!-._ ||||.......;. ':!|||||||||!!-._ ||||.....bBBBBWdou,. bBBBBB86foi!|||||||!!-..:|||!..bBBBBBBBBBBBBBBY! ::!?TFPRBBBBBB86foi!||||||||!!bBBBBBBBBBBBBBBY..! :::::::::!?TFPRBBBBBB86ftiaabBBBBBBBBBBBBBBY....! :::;`"^!:;::::::!?TFPRBBBBBBBBBBBBBBBBBBBY......! ;::::::...''^::::::::::!?TFPRBBBBBBBBBBY........! .ob86foi;::::::::::::::::::::::::!?TFPRBY..........` .b888888888886foi;:::::::::::::::::::::::..........` .b888888888888888888886foi;::::::::::::::::...........b888888888888888888888888888886foi;:::::::::......`!Tf998888888888888888888888888888888886foi;:::....` '"^!|Tf9988888888888888888888888888888888!::..` '"^!|Tf998888888888888888888888889!! '` '"^!|Tf9988888888888888888!!` iBBbo. '"^!|Tf998888888889!` WBBBBbo. '"^!|Tf9989!` YBBBP^' '"^!` `

Error