openapi: 3.0.3
info:
  title: Analyze API (Beta)
  description: |
    Use the Analyze API to analyze any external asset and return details based on the type of analysis requested.
    
    Currently supports the following analysis options:
      * [AI Vision - Tagging](https://cloudinary.com/documentation/cloudinary_ai_vision_addon#tagging_mode)
      * [AI Vision - Moderation](https://cloudinary.com/documentation/cloudinary_ai_vision_addon#moderation_mode)
      * [AI Vision - General](https://cloudinary.com/documentation/cloudinary_ai_vision_addon#general_mode)
      * [Captioning](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#ai_based_image_captioning)
      * [Cld Fashion](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#supported_content_aware_detection_models)
      * [Cld Text](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#supported_content_aware_detection_models)
      * [Coco](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#supported_content_aware_detection_models)
      * [Google Tagging](https://cloudinary.com/documentation/google_auto_tagging_addon)
      * [Human Anatomy](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#supported_content_aware_detection_models)
      * [Image Quality Analysis](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#image_quality_analysis)
      * [Lvis](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#supported_content_aware_detection_models)
      * [Shop Classifier](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#supported_content_aware_detection_models)
      * [Unidet](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#supported_content_aware_detection_models)
      * [Watermark Detection](https://cloudinary.com/documentation/cloudinary_ai_content_analysis_addon#watermark_detection)
    
      **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).
    
      The 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/pm)) or OAuth2 ([Contact support](https://support.cloudinary.com/hc/en-us/requests/new) for more information regarding OAuth).
  version: 0.2.0 # x-release-please-version
  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: 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.
      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: 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.
      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: The Tagging mode accepts a list of tag names along with their corresponding descriptions. If the image matches the description, which may encompass various elements, it will be appropriately tagged. This approach enables customers to align with their 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: Analyze 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: Analyze 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: Analyze 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: Analyze 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: Analyze 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: Analyze 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: Analyze 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: Analyze 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: Analyze 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: Get 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?