# Analyze API reference (Beta)

```yaml
openapi: 3.0.3
info:
  title: Analyze API (Beta)
  description: >

    ## 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](cloudinary_ai_vision_addon) for
    visual content queries or perform analysis using a variety of models
    included with [Cloudinary AI Content
    Analysis](cloudinary_ai_content_analysis_addon).


    See the [Analyze API guide](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](https://support.cloudinary.com/hc/en-us/requests/new).

    * The analysis options require an active subscription to the relevant
    add-on. Learn more about [registering for
    add-ons](https://cloudinary.com/documentation/cloudinary_add_ons#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](https://console.cloudinary.com/app/home/dashboard)) or OAuth2 ([Contact
    support](https://support.cloudinary.com/hc/en-us/requests/new) for more
    information regarding OAuth).

             
  version: 0.2.0
  license:
    name: MIT
    url: 'https://opensource.org/license/MIT'
  x-cld-module-context: cloud
  x-cld-module-name: analysis
servers:
  - url: 'https://api.cloudinary.com/v2/analysis/{cloud_name}'
    variables:
      cloud_name:
        default: CLOUD_NAME
        description: Your Cloud Name.
tags:
  - name: Analysis
    description: >-
      Use the Analyze API to analyze any external asset and return details based
      on the type of analysis requested.
  - name: Tasks
    description: Query the status of analysis tasks.
security:
  - basicAuth: []
  - OAuth2:
      - media_analysis
paths:
  /analyze/ai_vision_general:
    post:
      tags:
        - Analysis
      summary: Analyze - AI Vision General
      description: >-
        Provides detailed answers to diverse questions about an image using AI
        Vision General mode.


        Users can inquire about any aspect of an image, such as identifying
        objects, understanding scenes, or interpreting text within the image.
      operationId: analyze_ai_vision_general
      x-cld-use-for-readme: true
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeAIVisionGeneralRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/AnalyzeAIVisionGeneralUriExample'
              AssetIDExample:
                $ref: '#/components/examples/AnalyzeAIVisionGeneralAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeAIVisionGeneralResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/ai_vision_moderation:
    post:
      tags:
        - Analysis
      summary: Analyze - AI Vision Moderation
      description: >-
        Evaluates an image against multiple yes/no questions, responding with
        "yes," "no," or "unknown."


        This allows for nuanced evaluation of whether the image adheres to
        specific content policies, creative specs, or aesthetic criteria.
      operationId: analyze_ai_vision_moderation
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeAIVisionModerationRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/AnalyzeAIVisionModerationUriExample'
              AssetIDExample:
                $ref: '#/components/examples/AnalyzeAIVisionModerationAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeAIVisionModerationResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/ai_vision_tagging:
    post:
      tags:
        - Analysis
      summary: Analyze - AI Vision Tagging
      description: >-
        Tags an image based on a list of custom tag names and their
        corresponding descriptions.


        If the image matches a description, it's appropriately tagged. This
        allows you to align metadata with your own brand taxonomy, offering a
        dynamic, flexible, and open method for image classification.
      operationId: analyze_ai_vision_tagging
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeAIVisionTaggingRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/AnalyzeAIVisionTaggingUriExample'
              AssetIDExample:
                $ref: '#/components/examples/AnalyzeAIVisionTaggingAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeAIVisionTaggingResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/captioning:
    post:
      tags:
        - Analysis
      summary: Analyze - Captioning
      description: Provides a caption for an image.
      operationId: analyze_captioning
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeCaptioningRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/ParameterlessAnalyzeUriExample'
              AssetIDExample:
                $ref: '#/components/examples/ParameterlessAnalyzeAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeCaptioningResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/cld_fashion:
    post:
      tags:
        - Analysis
      summary: Analyze - Cld-Fashion
      description: >-
        Analyzes an image using the
        [Cld-Fashion](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#ai_based_image_captioning)
        content-aware detection model.


        Cloudinary's fashion model is specifically dedicated to items of
        clothing. The response includes attributes of the clothing identified,
        for example whether the garment contains pockets, its material and the
        fastenings used.
      operationId: analyze_cld_fashion
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeCldFashionRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/ParameterlessAnalyzeUriExample'
              AssetIDExample:
                $ref: '#/components/examples/ParameterlessAnalyzeAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeCldFashionResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/cld_text:
    post:
      tags:
        - Analysis
      summary: Analyze - Cld-Text
      description: >-
        Analyzes an image using the
        [Cld-Text](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#ai_based_image_captioning)
        content-aware detection model.


        Cloudinary's text model tells you if your image includes text, and where
        it's located. Used with image tagging, you can then search for images
        that contain blocks of text. Used with object-aware cropping, you can
        choose to keep only the text part, or specify a crop that avoids the
        text.
      operationId: analyze_cld_text
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeCldTextRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/ParameterlessAnalyzeUriExample'
              AssetIDExample:
                $ref: '#/components/examples/ParameterlessAnalyzeAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeCldTextResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/coco:
    post:
      tags:
        - Analysis
      summary: Analyze - Coco
      description: >-
        Analyzes an image using the
        [Coco](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#ai_based_image_captioning)
        content-aware detection model.


        The [Common Objects in Context](https://cocodataset.org/) model contains
        just 80 common objects.
      operationId: analyze_coco
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeCocoRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/ParameterlessAnalyzeUriExample'
              AssetIDExample:
                $ref: '#/components/examples/ParameterlessAnalyzeAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeCocoResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/google_logo_detection:
    post:
      tags:
        - Analysis
      summary: Analyze - Google Logo Detection
      description: Detects popular product logos within an image.
      operationId: analyze_google_logo_detection
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeGoogleLogoDetectionRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/ParameterlessAnalyzeUriExample'
              AssetIDExample:
                $ref: '#/components/examples/ParameterlessAnalyzeAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeGoogleLogoDetectionResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/google_tagging:
    post:
      tags:
        - Analysis
      summary: Analyze - Google Tagging
      description: Provides tags for an image using Google's tagging service.
      operationId: analyze_google_tagging
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeGoogleTaggingRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/ParameterlessAnalyzeUriExample'
              AssetIDExample:
                $ref: '#/components/examples/ParameterlessAnalyzeAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeGoogleTaggingResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/human_anatomy:
    post:
      tags:
        - Analysis
      summary: Analyze - Human Anatomy
      description: >-
        Analyzes an image using the [Human
        Anatomy](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#ai_based_image_captioning)
        content-aware detection model.


        Cloudinary's human anatomy model identifies parts of the human body in
        an image. It works best when the majority of a human body is detected in
        the image.
      operationId: analyze_human_anatomy
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeHumanAnatomyRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/ParameterlessAnalyzeUriExample'
              AssetIDExample:
                $ref: '#/components/examples/ParameterlessAnalyzeAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeHumanAnatomyResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/image_quality:
    post:
      tags:
        - Analysis
      summary: Analyze - Image Quality Analysis
      description: >-
        Analyzes an image using the [Image Quality
        Analysis](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#image_quality_analysis)
        model.
      operationId: analyze_image_quality
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeImageQualityRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/ParameterlessAnalyzeUriExample'
              AssetIDExample:
                $ref: '#/components/examples/ParameterlessAnalyzeAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeImageQualityResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/lvis:
    post:
      tags:
        - Analysis
      summary: Analyze - Lvis
      description: >-
        Analyzes an image using the
        [Lvis](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#ai_based_image_captioning)
        content-aware detection model.


        The [Large Vocabulary Instance Segmentation](https://www.lvisdataset.org/)
        model contains thousands of general objects.
      operationId: analyze_lvis
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeLvisRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/ParameterlessAnalyzeUriExample'
              AssetIDExample:
                $ref: '#/components/examples/ParameterlessAnalyzeAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeLvisResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/shop_classifier:
    post:
      tags:
        - Analysis
      summary: Analyze - Shop Classifier
      description: >-
        Analyzes an image using the [Shop
        Classifier](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#ai_based_image_captioning)
        content-aware detection model.


        Cloudinary's shop classifier model detects if the image is a product
        image taken in a studio, or if it's a natural image.
      operationId: analyze_shop_classifier
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeShopClassifierRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/ParameterlessAnalyzeUriExample'
              AssetIDExample:
                $ref: '#/components/examples/ParameterlessAnalyzeAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeShopClassifierResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/unidet:
    post:
      tags:
        - Analysis
      summary: Analyze - Unidet
      description: >-
        Analyzes an image using the
        [Unidet](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#ai_based_image_captioning)
        content-aware detection model.


        The [UniDet](https://github.com/xingyizhou/UniDet) model is a unified
        model, combining a number of object models, including
        [Objects365](https://www.objects365.org/overview.html), which focuses on
        diverse objects in the wild.
      operationId: analyze_unidet
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeUnidetRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/ParameterlessAnalyzeUriExample'
              AssetIDExample:
                $ref: '#/components/examples/ParameterlessAnalyzeAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeUnidetResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /analyze/watermark_detection:
    post:
      tags:
        - Analysis
      summary: Analyze - Watermark Detection
      description: >-
        Analyzes an image using the [Watermark
        Detection](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#watermark_detection)
        detection model.
      operationId: analyze_watermark_detection
      requestBody:
        required: true
        description: A JSON object containing request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeWatermarkDetectionRequest'
            examples:
              UriExample:
                $ref: '#/components/examples/ParameterlessAnalyzeUriExample'
              AssetIDExample:
                $ref: '#/components/examples/ParameterlessAnalyzeAssetIDExample'
      responses:
        '200':
          description: Analysis succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeWatermarkDetectionResponse'
        '202':
          $ref: '#/components/responses/AnalysisAcceptedResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  '/tasks/{task_id}':
    parameters:
      - in: path
        name: task_id
        description: The ID of the analysis task
        required: true
        schema:
          type: string
        example: >-
          053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb
    get:
      tags:
        - Tasks
      summary: Get analysis task status
      description: Gets the status of an analysis task.
      operationId: get_analysis_task_status
      security:
        - basicAuth: []
        - OAuth2:
            - query_analysis_tasks
      responses:
        '200':
          description: Analysis task status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTaskStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://oauth.cloudinary.com/oauth2/auth'
          tokenUrl: 'https://oauth.cloudinary.com/oauth2/token'
          scopes:
            media_analysis: Analyze media
            query_analysis_tasks: Query status of analysis tasks
  responses:
    AnalysisAcceptedResponse:
      description: Analysis accepted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AsyncOperationAcceptedResponse'
    BadRequestResponse:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ForbiddenResponse:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFoundResponse:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimitedResponse:
      description: Rate limited
      content:
        application/json:
          schema:
            title: RateLimitedResponse
            allOf:
              - $ref: '#/components/schemas/ErrorResponse'
              - $ref: '#/components/schemas/LimitsResponse'
    InternalServerErrorResponse:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Source:
      type: object
      properties:
        asset_id:
          type: string
          description: The asset ID to analyze
          example: e12345b5c456c8901bbb0efc00c0fcf
        uri:
          type: string
          format: uri
          description: The URI of the asset to analyze
          example: 'https://res.cloudinary.com/demo/image/upload/sample.jpg'
      oneOf:
        - required:
            - asset_id
        - required:
            - uri
    BaseAnalyzeRequest:
      properties:
        source:
          $ref: '#/components/schemas/Source'
        async:
          type: boolean
          description: >-
            Whether to perform the analysis asynchronously.

            If true, the response is returned immediately and analysis is done
            in the background.

            Once complete, a webhook notification will be sent to the specified
            URL and/or to the URLs defined in the Webhook Notifications settings
            of your Cloudinary Console.
        notification_url:
          type: string
          description: >-
            The webhook URL to notify when the analysis is complete. Only
            relevant when async is set to true.
          example: 'https://path.to/webhook'
      required:
        - source
    AnalyzeAIVisionGeneralRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
        - type: object
          properties:
            prompts:
              type: array
              description: >-
                One or more prompts of open questions or tasks with an open
                answer
              items:
                type: string
                example:
                  - Please describe this image in detail
                  - Does this image contain an animal?
              minItems: 1
              maxItems: 10
    AnalyzeAIVisionModerationRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
        - type: object
          properties:
            rejection_questions:
              type: array
              description: A list of yes/no questions
              items:
                type: string
                example: Does the image contain any violent activity?
              minItems: 1
              maxItems: 10
    AnalyzeAIVisionTaggingRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
        - type: object
          properties:
            tag_definitions:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: >-
                      The name of the tag to apply. This can be any string and
                      does not affect the decision process
                    example: cigarettes
                  description:
                    type: string
                    description: >-
                      A description to be used by the AI to determine whether
                      the tag should be applied
                    example: Does the image contain a pack of cigarettes?
                required:
                  - name
                  - description
              minItems: 1
              maxItems: 10
              example:
                - name: cigarettes
                  description: Does the image contain a pack of cigarettes?
          required:
            - tag_definitions
    AnalyzeCaptioningRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
    AnalyzeCldFashionRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
    AnalyzeCldTextRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
    AnalyzeCocoRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
    AnalyzeGoogleLogoDetectionRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
    AnalyzeGoogleTaggingRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
    AnalyzeHumanAnatomyRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
    AnalyzeImageQualityRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
    AnalyzeLvisRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
    AnalyzeShopClassifierRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
    AnalyzeUnidetRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
    AnalyzeWatermarkDetectionRequest:
      allOf:
        - $ref: '#/components/schemas/BaseAnalyzeRequest'
    BaseAnalyzeResponse:
      allOf:
        - $ref: '#/components/schemas/LimitsResponse'
        - type: object
          properties:
            request_id:
              type: string
              example: 17c3b70c5096df0e77e838323abb7029
    AnalyzeAIVisionGeneralResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/AIVisionGeneralAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    AIVisionGeneralAnalysisData:
      type: object
      properties:
        responses:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
          example:
            - value: The image contains one cat.
            - value: The cat is on top of the table.
        model_version:
          type: integer
          example: 1
      required:
        - responses
    AnalyzeAIVisionModerationResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/AIVisionModerationAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    AIVisionModerationAnalysisData:
      type: object
      properties:
        responses:
          type: array
          items:
            type: object
            properties:
              prompt:
                type: string
              value:
                type: string
                enum:
                  - 'yes'
                  - 'no'
                  - unknown
          example:
            - prompt: Does the image contain any violent activity?
              value: 'no'
            - prompt: Is there any nudity in the image?
              value: 'yes'
        model_version:
          type: integer
          example: 1
      required:
        - responses
    AnalyzeAIVisionTaggingResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/AIVisionTaggingAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    AIVisionTaggingAnalysisData:
      type: object
      properties:
        tags:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
          example:
            - name: cat
            - name: table
        model_version:
          type: integer
          example: 1
      required:
        - tags
    AnalyzeCaptioningResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/CaptioningAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    CaptioningAnalysisData:
      type: object
      properties:
        data:
          type: object
          properties:
            caption:
              type: string
          required:
            - caption
          example:
            caption: A cat sitting on a table
        model_version:
          type: integer
          example: 1
      required:
        - data
    AnalyzeCldFashionResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/CldFashionAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    CldFashionAnalysisData:
      type: object
      properties:
        tags:
          type: object
        model_version:
          type: integer
          example: 1
      required:
        - tags
    AnalyzeCldTextResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/CldTextAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    CldTextAnalysisData:
      type: object
      properties:
        tags:
          type: object
        model_version:
          type: integer
          example: 1
      required:
        - tags
    AnalyzeCocoResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/CocoAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    CocoAnalysisData:
      type: object
      properties:
        tags:
          type: object
        model_version:
          type: integer
          example: 1
      required:
        - tags
    AnalyzeGoogleLogoDetectionResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/GoogleLogoDetectionAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    GoogleLogoDetectionAnalysisData:
      type: object
      properties:
        logo_annotations:
          type: array
          items:
            type: object
            properties:
              mid:
                type: string
              description:
                type: string
              score:
                type: number
              bounding_poly:
                type: object
                properties:
                  vertices:
                    type: array
                    items:
                      type: object
                      properties:
                        x:
                          type: integer
                        'y':
                          type: integer
            required:
              - description
              - score
              - bounding_poly
      example:
        logo_annotations:
          - mid: /m/045c7b
            description: google
            score: 0.980325
            bounding_poly:
              vertices:
                - x: 12
                  'y': 42
                - x: 439
                  'y': 42
                - x: 439
                  'y': 285
                - x: 12
                  'y': 285
      required:
        - logo_annotations
    AnalyzeGoogleTaggingResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/GoogleTaggingAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    GoogleTaggingAnalysisData:
      type: object
      properties:
        label_annotations:
          type: object
          properties:
            labels:
              type: array
              items:
                type: object
                properties:
                  label:
                    type: string
                  score:
                    type: number
                required:
                  - label
                  - score
          example:
            labels:
              - label: cat
                score: 0.9
              - label: table
                score: 0.8
      required:
        - label_annotations
    AnalyzeHumanAnatomyResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/HumanAnatomyAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    HumanAnatomyAnalysisData:
      type: object
      properties:
        tags:
          type: object
        model_version:
          type: integer
          example: 1
      required:
        - tags
    AnalyzeImageQualityResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/ImageQualityAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    ImageQualityAnalysisData:
      type: object
      properties:
        quality:
          type: string
          example: medium
        score:
          type: number
          example: 0.45218
        confidence:
          type: number
          example: 0.8
        model_version:
          type: integer
          example: 1
      required:
        - tags
    AnalyzeLvisResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/LvisAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    LvisAnalysisData:
      type: object
      properties:
        tags:
          type: object
        model_version:
          type: integer
          example: 1
      required:
        - tags
    AnalyzeShopClassifierResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/ShopClassifierAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    ShopClassifierAnalysisData:
      type: object
      properties:
        tags:
          type: object
        model_version:
          type: integer
          example: 1
      required:
        - tags
    AnalyzeUnidetResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/UnidetAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    UnidetAnalysisData:
      type: object
      properties:
        tags:
          type: object
        model_version:
          type: integer
          example: 1
      required:
        - tags
    AnalyzeWatermarkDetectionResponse:
      allOf:
        - type: object
          properties:
            data:
              properties:
                entity:
                  type: string
                analysis:
                  $ref: '#/components/schemas/WatermarkDetectionAnalysisData'
        - $ref: '#/components/schemas/BaseAnalyzeResponse'
    WatermarkDetectionAnalysisData:
      type: object
      properties:
        detections:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: banner
              confidence:
                type: number
                example: 0.99
            required:
              - name
              - confidence
          example:
            - name: banner
              confidence: 0.99
        model_version:
          type: integer
          example: 1
      required:
        - tags
    TaskStatus:
      type: string
      description: The status of an async task
      enum:
        - pending
        - processing
        - completed
        - failed
    LimitsResponse:
      type: object
      nullable: true
      properties:
        limits:
          $ref: '#/components/schemas/LimitsObject'
    LimitsObject:
      type: object
      nullable: true
      title: limits_object
      properties:
        items:
          type: array
          items:
            type: object
            title: limit
            properties:
              type:
                $ref: '#/components/schemas/Feature'
              used_by_request:
                type: integer
                nullable: true
                description: The amount of quota used by the current request
              remaining:
                type: integer
                nullable: true
                description: The remaining quota
              limit:
                type: integer
                nullable: true
                description: The total quota limit
              reset_time:
                type: string
                format: date-time
                nullable: true
                description: Time in UTC when the limit will be reset
            required:
              - type
          example:
            - type: ai_vision
              used_by_request: 123
              remaining: 500
              limit: 10000
              reset_time: '2024-01-20T12:34:56Z'
    Feature:
      type: string
      enum:
        - google_tagging
        - object_detection
        - ai_vision
    ErrorCategory:
      type: string
      enum:
        - user_error
        - auth_error
        - server_error
        - rate_limit_error
    AsyncOperationAcceptedResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            task_id:
              type: string
            status:
              $ref: '#/components/schemas/TaskStatus'
          required:
            - task_id
            - status
        request_id:
          type: string
          example: 17c3b70c5096df0e77e838323abb7029
      example:
        data:
          task_id: >-
            053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb
          status: pending
        request_id: 17c3b70c5096df0e77e838323abb7029
    BaseWebhookPayload:
      description: Base payload for webhook notifications
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - $ref: '#/components/schemas/LimitsResponse'
        - type: object
          properties:
            operation_name:
              type: string
              example: analyze
            operation_type:
              type: string
              enum:
                - single
                - bulk
            notification_type:
              type: string
              example: analyze
            request_id:
              type: string
              example: 17c3b70c5096df0e77e838323abb7029
            task_id:
              type: string
              example: >-
                053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb
            http_status:
              type: integer
              example: 200
    AnalysisWebhookPayload:
      description: Payload for webhook notifications for analysis operations
      allOf:
        - $ref: '#/components/schemas/BaseWebhookPayload'
        - type: object
          properties:
            data:
              type: object
    GetTaskStatusResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            task_id:
              type: string
              example: >-
                053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb
            status:
              $ref: '#/components/schemas/TaskStatus'
          example:
            task_id: >-
              053f4bde4b933c8ecef23724ecde63b667c1ea21816d56c161c7ec1df6297da4b43109625650e9edf0f42152cc4cc32c8ad57824ac75ba8e05020f827c415559ac1248076a2d72c0a73af0479cca77eb
            status: processing
        request_id:
          type: string
          example: 17c3b70c5096df0e77e838323abb7029
      required:
        - status
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    ErrorObject:
      type: object
      nullable: true
      example:
        category: user_error
        code: MA_00001
        message: missing parameters
        details:
          parameters:
            - param1
            - param2
        request_id: 17c3b70c5096df0e77e838323abb7029
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
        code:
          type: string
          example: MA_00001
        message:
          type: string
          example: missing parameters
        details:
          type: object
          example:
            parameters:
              - uri
              - analysis_type
        request_id:
          type: string
          example: 17c3b70c5096df0e77e838323abb7029
  examples:
    ParameterlessAnalyzeUriExample:
      summary: Passing an image URL to be analyzed
      value:
        source:
          uri: 'https://res.cloudinary.com/demo/image/upload/sample.jpg'
    ParameterlessAnalyzeAssetIDExample:
      summary: Passing an asset ID to be analyzed
      value:
        source:
          asset_id: e12345b5c456c8901bbb0efc00c0fcf
    AnalyzeAIVisionGeneralUriExample:
      summary: Passing an image URL to AI Vision General
      value:
        source:
          uri: 'https://res.cloudinary.com/demo/image/upload/sample.jpg'
        prompts:
          - Describe this image in detail
          - Does this image contain an insect?
    AnalyzeAIVisionGeneralAssetIDExample:
      summary: Passing an asset ID to AI Vision General
      value:
        source:
          asset_id: e12345b5c456c8901bbb0efc00c0fcf
        prompts:
          - Describe this image in detail
          - Does this image contain an insect?
    AnalyzeAIVisionModerationUriExample:
      summary: Passing an image URL to AI Vision Moderation
      value:
        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?
    AnalyzeAIVisionModerationAssetIDExample:
      summary: Passing an asset ID to AI Vision Moderation
      value:
        source:
          asset_id: e12345b5c456c8901bbb0efc00c0fcf
        rejection_questions:
          - Does this image contain any violent activity?
          - Is there any nudity in the image?
    AnalyzeAIVisionTaggingUriExample:
      summary: Passing an image URL to AI Vision Tagging
      value:
        source:
          uri: 'https://res.cloudinary.com/demo/image/upload/sample.jpg'
        tag_definitions:
          - name: cigarettes
            description: Does the image contain a pack of cigarettes?
          - name: furniture
            description: 'Does the image contain any tables, chairs, couches or sofas?'
    AnalyzeAIVisionTaggingAssetIDExample:
      summary: Passing an asset ID to AI Vision Tagging
      value:
        source:
          asset_id: e12345b5c456c8901bbb0efc00c0fcf
        tag_definitions:
          - name: cigarettes
            description: Does the image contain a pack of cigarettes?
          - name: furniture
            description: 'Does the image contain any tables, chairs, couches or sofas?'
```