openapi: 3.0.0
servers:
  - url: https://westcentralus.api.cognitive.microsoft.com/vision/v2.0
  - url: "{Endpoint}/vision/v2.0"
    variables:
      Endpoint:
        default: none
        description: Supported Cognitive Services endpoints.
        x-ms-parameter-location: client
        x-ms-skip-url-encoding: true
info:
  contact:
    x-twitter: microsoft
  description: The Computer Vision API provides state-of-the-art algorithms to process images and return information. For example, it can be used to determine if an image contains mature content, or it can be used to find all the faces in an image.  It also has other features like estimating dominant and accent colors, categorizing the content of images, and describing an image with complete English sentences.  Additionally, it can also intelligently generate images thumbnails for displaying large images effectively.
  title: Computer Vision Client
  version: "2.0"
  x-apisguru-categories:
    - developer_tools
    - cloud
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_twitter.com_microsoft_profile_image.png
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/cognitiveservices/data-plane/ComputerVision/stable/v2.0/ComputerVision.json
      version: "3.0"
  x-preferred: false
  x-providerName: microsoft.com
  x-serviceName: cognitiveservices-ComputerVision
  x-tags:
    - Microsoft
security:
  - apim_key: []
paths:
  /analyze:
    post:
      description: "This operation extracts a rich set of visual features based on the image content.\r

        Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL. Within your request, there is an optional parameter to allow you to choose which features to return. By default, image categories are returned in the response.\r

        A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong."
      operationId: AnalyzeImage
      parameters:
        - $ref: "#/components/parameters/VisualFeatures"
        - description: "A string indicating which domain-specific details to return. Multiple values should be comma-separated. Valid visual feature types include: Celebrities - identifies celebrities if detected in the image, Landmarks - identifies notable landmarks in the image."
          examples:
            Successful AnalyzeImage request:
              value:
                - Celebrities
                - Landmarks
          explode: false
          in: query
          name: details
          required: false
          schema:
            items:
              enum:
                - Celebrities
                - Landmarks
              nullable: false
              type: string
              x-ms-enum:
                modelAsString: false
                name: Details
            type: array
          style: form
          x-nullable: true
        - $ref: "#/components/parameters/ServiceLanguage"
      requestBody:
        $ref: "#/components/requestBodies/ImageUrl"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful AnalyzeImage request:
                  $ref: "#/components/examples/Successful_AnalyzeImage_request"
              schema:
                $ref: "#/components/schemas/ImageAnalysis"
          description: "The response include the extracted features in JSON format. Here is the definitions for enumeration types:\r

            \ ClipartType\r

            \ Non - clipart = 0, ambiguous = 1, normal - clipart = 2, good - clipart = 3. LineDrawingTypeNon - LineDrawing = 0, LineDrawing = 1."
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /areaOfInterest:
    post:
      description: "This operation returns a bounding box around the most important area of the image.\r

        A successful response will be returned in JSON. If the request failed, the response contains an error code and a message to help determine what went wrong.\r

        Upon failure, the error code and an error message are returned. The error code could be one of InvalidImageUrl, InvalidImageFormat, InvalidImageSize, NotSupportedImage, FailedToProcess, Timeout, or InternalServerError."
      operationId: GetAreaOfInterest
      requestBody:
        $ref: "#/components/requestBodies/ImageUrl"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful GetAreaOfInterest request:
                  $ref: "#/components/examples/Successful_GetAreaOfInterest_request"
              schema:
                $ref: "#/components/schemas/AreaOfInterestResult"
          description: The response includes the extracted area of interest in JSON format.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /describe:
    post:
      description: "This operation generates a description of an image in human readable language with complete sentences. The description is based on a collection of content tags, which are also returned by the operation. More than one description can be generated for each image. Descriptions are ordered by their confidence score. All descriptions are in English.\r

        Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL.\r

        A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong."
      operationId: DescribeImage
      parameters:
        - description: Maximum number of candidate descriptions to be returned.  The default is 1.
          examples:
            Successful DescribeImage request:
              value: 1
          in: query
          name: maxCandidates
          required: false
          schema:
            default: 1
            format: int32
            type: integer
          x-nullable: true
        - $ref: "#/components/parameters/ServiceLanguage"
      requestBody:
        $ref: "#/components/requestBodies/ImageUrl"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful DescribeImage request:
                  $ref: "#/components/examples/Successful_DescribeImage_request"
              schema:
                $ref: "#/components/schemas/ImageDescription"
          description: Image description object.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /detect:
    post:
      description: "Performs object detection on the specified image.\r

        Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL.\r

        A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong."
      operationId: DetectObjects
      requestBody:
        $ref: "#/components/requestBodies/ImageUrl"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful DetectObjects request:
                  $ref: "#/components/examples/Successful_DetectObjects_request"
              schema:
                $ref: "#/components/schemas/DetectResult"
          description: The response include the detected objects in JSON format.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /generateThumbnail:
    post:
      description: "This operation generates a thumbnail image with the user-specified width and height. By default, the service analyzes the image, identifies the region of interest (ROI), and generates smart cropping coordinates based on the ROI. Smart cropping helps when you specify an aspect ratio that differs from that of the input image.\r

        A successful response contains the thumbnail image binary. If the request failed, the response contains an error code and a message to help determine what went wrong.\r

        Upon failure, the error code and an error message are returned. The error code could be one of InvalidImageUrl, InvalidImageFormat, InvalidImageSize, InvalidThumbnailSize, NotSupportedImage, FailedToProcess, Timeout, or InternalServerError."
      operationId: GenerateThumbnail
      parameters:
        - description: Width of the thumbnail, in pixels. It must be between 1 and 1024. Recommended minimum of 50.
          examples:
            Successful GenerateThumbnail request:
              value: "500"
          in: query
          name: width
          required: true
          schema:
            format: int32
            maximum: 1024
            minimum: 1
            type: integer
          x-nullable: false
        - description: Height of the thumbnail, in pixels. It must be between 1 and 1024. Recommended minimum of 50.
          examples:
            Successful GenerateThumbnail request:
              value: "500"
          in: query
          name: height
          required: true
          schema:
            format: int32
            maximum: 1024
            minimum: 1
            type: integer
          x-nullable: false
        - description: Boolean flag for enabling smart cropping.
          examples:
            Successful GenerateThumbnail request:
              value: true
          in: query
          name: smartCropping
          required: false
          schema:
            default: false
            type: boolean
          x-nullable: true
      requestBody:
        $ref: "#/components/requestBodies/ImageUrl"
      responses:
        "200":
          content:
            application/octet-stream:
              examples:
                Successful GenerateThumbnail request:
                  $ref: "#/components/examples/Successful_GenerateThumbnail_request"
              schema:
                format: binary
                type: string
          description: The generated thumbnail in binary format.
        default:
          content:
            application/octet-stream:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /models:
    get:
      description: "This operation returns the list of domain-specific models that are supported by the Computer Vision API. Currently, the API supports following domain-specific models: celebrity recognizer, landmark recognizer.\r

        A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong."
      operationId: ListModels
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful ListModels request:
                  $ref: "#/components/examples/Successful_ListModels_request"
              schema:
                $ref: "#/components/schemas/ListModelsResult"
          description: List of available domain models.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  "/models/{model}/analyze":
    post:
      description: "This operation recognizes content within an image by applying a domain-specific model. The list of domain-specific models that are supported by the Computer Vision API can be retrieved using the /models GET request. Currently, the API provides following domain-specific models: celebrities, landmarks.\r

        Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL.\r

        A successful response will be returned in JSON.\r

        If the request failed, the response will contain an error code and a message to help understand what went wrong."
      operationId: AnalyzeImageByDomain
      parameters:
        - description: The domain-specific content to recognize.
          examples:
            Successful AnalyzeImageByDomain request:
              value: Celebrities
          in: path
          name: model
          required: true
          schema:
            type: string
          x-nullable: true
        - $ref: "#/components/parameters/ServiceLanguage"
      requestBody:
        $ref: "#/components/requestBodies/ImageUrl"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful AnalyzeImageByDomain request:
                  $ref: "#/components/examples/Successful_AnalyzeImageByDomain_request"
              schema:
                $ref: "#/components/schemas/DomainModelResults"
          description: Analysis result based on the domain model.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /ocr:
    post:
      description: "Optical Character Recognition (OCR) detects text in an image and extracts the recognized characters into a machine-usable character stream.\r

        Upon success, the OCR results will be returned.\r

        Upon failure, the error code together with an error message will be returned. The error code can be one of InvalidImageUrl, InvalidImageFormat, InvalidImageSize, NotSupportedImage, NotSupportedLanguage, or InternalServerError."
      operationId: RecognizePrintedText
      parameters:
        - $ref: "#/components/parameters/DetectOrientation"
        - $ref: "#/components/parameters/OcrLanguage"
      requestBody:
        $ref: "#/components/requestBodies/ImageUrl"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful RecognizePrintedText request:
                  $ref: "#/components/examples/Successful_RecognizePrintedText_request"
              schema:
                $ref: "#/components/schemas/OcrResult"
          description: The OCR results in the hierarchy of region/line/word. The results include text, bounding box for regions, lines and words. The angle, in degrees, of the detected text with respect to the closest horizontal or vertical direction. After rotating the input image clockwise by this angle, the recognized text lines become horizontal or vertical. In combination with the orientation property it can be used to overlay recognition results correctly on the original image, by rotating either the original image or recognition results by a suitable angle around the center of the original image. If the angle cannot be confidently detected, this property is not present. If the image contains text at different angles, only part of the text will be recognized correctly.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /tag:
    post:
      description: "This operation generates a list of words, or tags, that are relevant to the content of the supplied image. The Computer Vision API can return tags based on objects, living beings, scenery or actions found in images. Unlike categories, tags are not organized according to a hierarchical classification system, but correspond to image content. Tags may contain hints to avoid ambiguity or provide context, for example the tag \"cello\" may be accompanied by the hint \"musical instrument\". All tags are in English.\r

        Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL.\r

        A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong."
      operationId: TagImage
      parameters:
        - $ref: "#/components/parameters/ServiceLanguage"
      requestBody:
        $ref: "#/components/requestBodies/ImageUrl"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful TagImage request:
                  $ref: "#/components/examples/Successful_TagImage_request"
              schema:
                $ref: "#/components/schemas/TagResult"
          description: Image tags object.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
components:
  examples:
    Successful_AnalyzeImageByDomain_request:
      value:
        metadata:
          format: Jpeg
          height: 1000
          width: 1500
        requestId: f0027b4b-dc0d-4082-9228-1545ed246b03
        result:
          celebrities:
            - confidence: 0.999028444
              faceRectangle:
                height: 248
                left: 597
                top: 162
                width: 248
              name: Satya Nadella
    Successful_AnalyzeImage_request:
      value:
        adult:
          adultScore: 0.0934349000453949
          isAdultContent: false
          isRacyContent: false
          racyScore: 0.06861349195241928
        brands:
          - confidence: 0.857
            name: Pepsi
            rectangle:
              h: 177
              w: 161
              x: 489
              y: 79
          - confidence: 0.893
            name: Coca-Cola
            rectangle:
              h: 372
              w: 171
              x: 216
              y: 55
        categories:
          - name: abstract_
            score: 0.00390625
          - detail:
              celebrities:
                - confidence: 0.999028444
                  faceRectangle:
                    height: 248
                    left: 597
                    top: 162
                    width: 248
                  name: Satya Nadella
              landmarks:
                - confidence: 0.9978346
                  name: Forbidden City
            name: people_
            score: 0.83984375
        color:
          accentColor: 873B59
          dominantColorBackground: Brown
          dominantColorForeground: Brown
          dominantColors:
            - Brown
            - Black
          isBWImg: false
        description:
          captions:
            - confidence: 0.48293603002174407
              text: Satya Nadella sitting on a bench
          tags:
            - person
            - man
            - outdoor
            - window
            - glasses
        faces:
          - age: 44
            faceRectangle:
              height: 250
              left: 593
              top: 160
              width: 250
            gender: Male
        imageType:
          clipArtType: 0
          lineDrawingType: 0
        metadata:
          format: Jpeg
          height: 1000
          width: 1500
        objects:
          - confidence: 0.9
            object: tree
            parent:
              confidence: 0.95
              object: plant
            rectangle:
              h: 50
              w: 50
              x: 0
              y: 0
        requestId: 0dbec5ad-a3d3-4f7e-96b4-dfd57efe967d
        tags:
          - confidence: 0.9897908568382263
            name: person
          - confidence: 0.9449388980865479
            name: man
          - confidence: 0.938492476940155
            name: outdoor
          - confidence: 0.8951393961906433
            name: window
          - confidence: 0.7250059783791661
            hint: mammal
            name: pangolin
    Successful_DescribeImage_request:
      value:
        description:
          captions:
            - confidence: 0.48293603002174407
              text: Satya Nadella sitting on a bench
            - confidence: 0.4003700681542283
              text: Satya Nadella is sitting on a bench
            - confidence: 0.38035155997373377
              text: Satya Nadella sitting in front of a building
          tags:
            - person
            - man
            - outdoor
            - window
            - glasses
        metadata:
          format: Jpeg
          height: 1000
          width: 1500
        requestId: ed2de1c6-fb55-4686-b0da-4da6e05d283f
    Successful_DetectObjects_request:
      value:
        metadata:
          format: Jpeg
          height: 100
          width: 100
        objects:
          - confidence: 0.9
            object: tree
            parent:
              confidence: 0.95
              object: plant
            rectangle:
              h: 50
              w: 50
              x: 0
              y: 0
        requestId: 1ad0e45e-b7b4-4be3-8042-53be96103337
    Successful_GenerateThumbnail_request:
      value: "{binary}"
    Successful_GetAreaOfInterest_request:
      value:
        areaOfInterest:
          h: 951
          w: 950
          x: 160
          y: 0
        metadata:
          format: Jpeg
          height: 951
          width: 1378
        requestId: ed2de1c6-fb55-4686-b0da-4da6e05d283f
    Successful_ListModels_request:
      value:
        models:
          - categories:
              - people_
            name: celebrities
          - categories:
              - building_
            name: landmarks
    Successful_RecognizePrintedText_request:
      value:
        language: en
        orientation: Up
        regions:
          - boundingBox: 462,379,497,258
            lines:
              - boundingBox: 462,379,497,74
                words:
                  - boundingBox: 462,379,41,73
                    text: A
                  - boundingBox: 523,379,153,73
                    text: GOAL
                  - boundingBox: 694,379,265,74
                    text: WITHOUT
              - boundingBox: 565,471,289,74
                words:
                  - boundingBox: 565,471,41,73
                    text: A
                  - boundingBox: 626,471,150,73
                    text: PLAN
                  - boundingBox: 801,472,53,73
                    text: IS
              - boundingBox: 519,563,375,74
                words:
                  - boundingBox: 519,563,149,74
                    text: JUST
                  - boundingBox: 683,564,41,72
                    text: A
                  - boundingBox: 741,564,153,73
                    text: WISH
        textAngle: -2.0000000000000338
    Successful_TagImage_request:
      value:
        metadata:
          format: Jpeg
          height: 400
          width: 400
        requestId: 1ad0e45e-b7b4-4be3-8042-53be96103337
        tags:
          - confidence: 0.9999997615814209
            name: grass
          - confidence: 0.9999706745147705
            name: outdoor
          - confidence: 0.9992897510528564
            name: sky
          - confidence: 0.9964632391929626
            name: building
          - confidence: 0.9927980303764343
            name: house
          - confidence: 0.8226802945137024
            name: lawn
          - confidence: 0.6412225365638733
            name: green
          - confidence: 0.31403225660324097
            name: residential
  parameters:
    DetectOrientation:
      description: Whether detect the text orientation in the image. With detectOrientation=true the OCR service tries to detect the image orientation and correct it before further processing (e.g. if it's upside-down).
      examples:
        Successful RecognizePrintedText request:
          value: "true"
      in: query
      name: detectOrientation
      required: true
      schema:
        default: true
        type: boolean
      x-ms-parameter-location: method
    Endpoint:
      description: Supported Cognitive Services endpoints.
      in: path
      name: Endpoint
      required: true
      schema:
        type: string
      x-ms-parameter-location: client
      x-ms-skip-url-encoding: true
    OcrLanguage:
      description: The BCP-47 language code of the text to be detected in the image. The default value is 'unk'.
      examples:
        Successful RecognizePrintedText request:
          value: en
      in: query
      name: language
      required: false
      schema:
        default: unk
        enum:
          - unk
          - zh-Hans
          - zh-Hant
          - cs
          - da
          - nl
          - en
          - fi
          - fr
          - de
          - el
          - hu
          - it
          - ja
          - ko
          - nb
          - pl
          - pt
          - ru
          - es
          - sv
          - tr
          - ar
          - ro
          - sr-Cyrl
          - sr-Latn
          - sk
        type: string
      x-ms-enum:
        modelAsString: false
        name: OcrLanguages
      x-ms-parameter-location: method
      x-nullable: false
    ServiceLanguage:
      description: The desired language for output generation. If this parameter is not specified, the default value is &quot;en&quot;.Supported languages:en - English, Default. es - Spanish, ja - Japanese, pt - Portuguese, zh - Simplified Chinese.
      examples:
        Successful AnalyzeImage request:
          value: en
      in: query
      name: language
      required: false
      schema:
        default: en
        enum:
          - en
          - es
          - ja
          - pt
          - zh
        type: string
      x-ms-parameter-location: method
      x-nullable: false
    VisualFeatures:
      description: "A string indicating what visual feature types to return. Multiple values should be comma-separated. Valid visual feature types include: Categories - categorizes image content according to a taxonomy defined in documentation. Tags - tags the image with a detailed list of words related to the image content. Description - describes the image content with a complete English sentence. Faces - detects if faces are present. If present, generate coordinates, gender and age. ImageType - detects if image is clipart or a line drawing. Color - determines the accent color, dominant color, and whether an image is black&white. Adult - detects if the image is pornographic in nature (depicts nudity or a sex act).  Sexually suggestive content is also detected. Objects - detects various objects within an image, including the approximate location. The Objects argument is only available in English. Brands - detects various brands within an image, including the approximate location. The Brands argument is only available in English."
      examples:
        Successful AnalyzeImage request:
          value:
            - Categories
            - Adult
            - Tags
            - Description
            - Faces
            - Color
            - ImageType
            - Objects
            - Brands
      explode: false
      in: query
      name: visualFeatures
      required: false
      schema:
        items:
          enum:
            - ImageType
            - Faces
            - Adult
            - Categories
            - Color
            - Tags
            - Description
            - Objects
            - Brands
          nullable: false
          type: string
          x-ms-enum:
            modelAsString: false
            name: VisualFeatureTypes
        type: array
      style: form
      x-ms-parameter-location: method
  requestBodies:
    AnalyzeImageInStreamImage:
      content:
        application/octet-stream:
          schema:
            format: file
            type: object
        multipart/form-data:
          schema:
            format: file
            type: object
      description: An image stream.
      required: true
      x-ms-parameter-location: method
    ImageUrl:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ImageUrl"
      description: A JSON document with a URL pointing to the image that is to be analyzed.
      required: true
      x-ms-client-flatten: true
      x-ms-parameter-location: method
  schemas:
    AdultInfo:
      description: An object describing whether the image contains adult-oriented content and/or is racy.
      nullable: true
      properties:
        adultScore:
          description: Score from 0 to 1 that indicates how much the content is considered adult-oriented within the image.
          format: double
          nullable: false
          type: number
        isAdultContent:
          description: A value indicating if the image contains adult-oriented content.
          nullable: false
          type: boolean
        isRacyContent:
          description: A value indicating if the image is racy.
          nullable: false
          type: boolean
        racyScore:
          description: Score from 0 to 1 that indicates how suggestive is the image.
          format: double
          nullable: false
          type: number
      type: object
    AreaOfInterestResult:
      description: Result of AreaOfInterest operation.
      nullable: true
      properties:
        areaOfInterest:
          $ref: "#/components/schemas/BoundingRect"
        metadata:
          $ref: "#/components/schemas/ImageMetadata"
        requestId:
          description: Id of the REST API request.
          nullable: true
          type: string
      type: object
    BoundingRect:
      description: A bounding box for an area inside an image.
      nullable: false
      properties:
        h:
          description: Height measured from the top-left point of the area, in pixels.
          format: int32
          nullable: false
          type: integer
        w:
          description: Width measured from the top-left point of the area, in pixels.
          format: int32
          nullable: false
          type: integer
        x:
          description: X-coordinate of the top left point of the area, in pixels.
          format: int32
          nullable: false
          type: integer
        y:
          description: Y-coordinate of the top left point of the area, in pixels.
          format: int32
          nullable: false
          type: integer
      type: object
    Category:
      description: An object describing identified category.
      nullable: true
      properties:
        detail:
          $ref: "#/components/schemas/CategoryDetail"
        name:
          description: Name of the category.
          nullable: true
          type: string
        score:
          description: Scoring of the category.
          format: double
          nullable: false
          type: number
      type: object
    CategoryDetail:
      description: An object describing additional category details.
      nullable: true
      properties:
        celebrities:
          description: An array of celebrities if any identified.
          items:
            $ref: "#/components/schemas/CelebritiesModel"
          nullable: true
          type: array
        landmarks:
          description: An array of landmarks if any identified.
          items:
            $ref: "#/components/schemas/LandmarksModel"
          nullable: true
          type: array
      type: object
    CelebritiesModel:
      description: An object describing possible celebrity identification.
      nullable: true
      properties:
        confidence:
          description: Confidence level for the celebrity recognition as a value ranging from 0 to 1.
          format: double
          nullable: false
          type: number
        faceRectangle:
          $ref: "#/components/schemas/FaceRectangle"
        name:
          description: Name of the celebrity.
          nullable: true
          type: string
      type: object
    CelebrityResults:
      description: Result of domain-specific classifications for the domain of celebrities.
      nullable: true
      properties:
        celebrities:
          description: List of celebrities recognized in the image.
          items:
            $ref: "#/components/schemas/CelebritiesModel"
          nullable: true
          type: array
        metadata:
          $ref: "#/components/schemas/ImageMetadata"
        requestId:
          description: Id of the REST API request.
          nullable: true
          type: string
      type: object
    ColorInfo:
      description: An object providing additional metadata describing color attributes.
      nullable: true
      properties:
        accentColor:
          description: Possible accent color.
          nullable: true
          type: string
        dominantColorBackground:
          description: Possible dominant background color.
          nullable: true
          type: string
        dominantColorForeground:
          description: Possible dominant foreground color.
          nullable: true
          type: string
        dominantColors:
          description: An array of possible dominant colors.
          items:
            nullable: true
            type: string
          nullable: true
          type: array
        isBWImg:
          description: A value indicating if the image is black and white.
          nullable: false
          type: boolean
      type: object
    ComputerVisionError:
      description: Details about the API request error.
      properties:
        code:
          description: The error code.
          enum:
            - InvalidImageFormat
            - UnsupportedMediaType
            - InvalidImageUrl
            - NotSupportedFeature
            - NotSupportedImage
            - Timeout
            - InternalServerError
            - InvalidImageSize
            - BadArgument
            - DetectFaceError
            - NotSupportedLanguage
            - InvalidThumbnailSize
            - InvalidDetails
            - InvalidModel
            - CancelledRequest
            - NotSupportedVisualFeature
            - FailedToProcess
            - Unspecified
            - StorageException
          x-ms-enum:
            modelAsString: true
            name: ComputerVisionErrorCodes
        message:
          description: A message explaining the error reported by the service.
          type: string
        requestId:
          description: A unique request identifier.
          type: string
      required:
        - code
        - message
      type: object
    DetectResult:
      description: Result of a DetectImage call.
      nullable: true
      properties:
        metadata:
          $ref: "#/components/schemas/ImageMetadata"
        objects:
          description: An array of detected objects.
          items:
            $ref: "#/components/schemas/DetectedObject"
          nullable: true
          readOnly: true
          type: array
        requestId:
          description: Id of the REST API request.
          nullable: true
          type: string
      type: object
    DetectedBrand:
      description: A brand detected in an image.
      nullable: true
      properties:
        confidence:
          description: Confidence score of having observed the brand in the image, as a value ranging from 0 to 1.
          format: double
          nullable: false
          readOnly: true
          type: number
        name:
          description: Label for the brand.
          nullable: true
          readOnly: true
          type: string
        rectangle:
          $ref: "#/components/schemas/BoundingRect"
      type: object
    DetectedObject:
      description: An object detected in an image.
      nullable: true
      properties:
        confidence:
          description: Confidence score of having observed the object in the image, as a value ranging from 0 to 1.
          format: double
          nullable: false
          type: number
        object:
          description: Label for the object.
          nullable: true
          type: string
        parent:
          $ref: "#/components/schemas/ObjectHierarchy"
        rectangle:
          $ref: "#/components/schemas/BoundingRect"
      type: object
    DomainModelResults:
      description: Result of image analysis using a specific domain model including additional metadata.
      nullable: true
      properties:
        metadata:
          $ref: "#/components/schemas/ImageMetadata"
        requestId:
          description: Id of the REST API request.
          nullable: true
          type: string
        result:
          description: Model-specific response.
          type: object
          x-ms-client-flatten: true
      type: object
    FaceDescription:
      description: An object describing a face identified in the image.
      nullable: true
      properties:
        age:
          description: Possible age of the face.
          format: int32
          nullable: false
          type: integer
        faceRectangle:
          $ref: "#/components/schemas/FaceRectangle"
        gender:
          description: Possible gender of the face.
          enum:
            - Male
            - Female
          nullable: true
          type: string
          x-ms-enum:
            modelAsString: false
            name: Gender
      type: object
    FaceRectangle:
      description: An object describing face rectangle.
      nullable: true
      properties:
        height:
          description: Height measured from the top-left point of the face, in pixels.
          format: int32
          nullable: false
          type: integer
        left:
          description: X-coordinate of the top left point of the face, in pixels.
          format: int32
          nullable: false
          type: integer
        top:
          description: Y-coordinate of the top left point of the face, in pixels.
          format: int32
          nullable: false
          type: integer
        width:
          description: Width measured from the top-left point of the face, in pixels.
          format: int32
          nullable: false
          type: integer
      type: object
    ImageAnalysis:
      description: Result of AnalyzeImage operation.
      nullable: true
      properties:
        adult:
          $ref: "#/components/schemas/AdultInfo"
        brands:
          description: Array of brands detected in the image.
          items:
            $ref: "#/components/schemas/DetectedBrand"
          nullable: true
          type: array
        categories:
          description: An array indicating identified categories.
          items:
            $ref: "#/components/schemas/Category"
          nullable: true
          type: array
        color:
          $ref: "#/components/schemas/ColorInfo"
        description:
          $ref: "#/components/schemas/ImageDescriptionDetails"
        faces:
          description: An array of possible faces within the image.
          items:
            $ref: "#/components/schemas/FaceDescription"
          nullable: true
          type: array
        imageType:
          $ref: "#/components/schemas/ImageType"
        metadata:
          $ref: "#/components/schemas/ImageMetadata"
        objects:
          description: Array of objects describing what was detected in the image.
          items:
            $ref: "#/components/schemas/DetectedObject"
          nullable: true
          type: array
        requestId:
          description: Id of the REST API request.
          nullable: true
          type: string
        tags:
          description: A list of tags with confidence level.
          items:
            $ref: "#/components/schemas/ImageTag"
          nullable: true
          type: array
      type: object
    ImageCaption:
      description: An image caption, i.e. a brief description of what the image depicts.
      nullable: true
      properties:
        confidence:
          description: The level of confidence the service has in the caption.
          format: double
          nullable: false
          type: number
        text:
          description: The text of the caption.
          nullable: true
          type: string
      type: object
    ImageDescription:
      description: A collection of content tags, along with a list of captions sorted by confidence level, and image metadata.
      nullable: true
      properties:
        description:
          $ref: "#/components/schemas/ImageDescriptionDetails"
        metadata:
          $ref: "#/components/schemas/ImageMetadata"
        requestId:
          description: Id of the REST API request.
          nullable: true
          type: string
      type: object
    ImageDescriptionDetails:
      description: A collection of content tags, along with a list of captions sorted by confidence level, and image metadata.
      nullable: true
      properties:
        captions:
          description: A list of captions, sorted by confidence level.
          items:
            $ref: "#/components/schemas/ImageCaption"
          nullable: true
          type: array
        tags:
          description: A collection of image tags.
          items:
            nullable: true
            type: string
          nullable: true
          type: array
      type: object
    ImageMetadata:
      description: Image metadata.
      nullable: true
      properties:
        format:
          description: Image format.
          nullable: true
          type: string
        height:
          description: Image height, in pixels.
          format: int32
          nullable: false
          type: integer
        width:
          description: Image width, in pixels.
          format: int32
          nullable: false
          type: integer
      type: object
    ImageTag:
      description: An entity observation in the image, along with the confidence score.
      nullable: true
      properties:
        confidence:
          description: The level of confidence that the entity was observed.
          format: double
          nullable: false
          type: number
        hint:
          description: Optional hint/details for this tag.
          nullable: true
          type: string
        name:
          description: Name of the entity.
          nullable: true
          type: string
      type: object
    ImageType:
      description: An object providing possible image types and matching confidence levels.
      nullable: true
      properties:
        clipArtType:
          description: Confidence level that the image is a clip art.
          format: int32
          nullable: false
          type: integer
        lineDrawingType:
          description: Confidence level that the image is a line drawing.
          format: int32
          nullable: false
          type: integer
      type: object
    ImageUrl:
      properties:
        url:
          description: Publicly reachable URL of an image.
          type: string
      required:
        - url
      type: object
    LandmarkResults:
      description: Result of domain-specific classifications for the domain of landmarks.
      nullable: true
      properties:
        landmarks:
          description: List of landmarks recognized in the image.
          items:
            $ref: "#/components/schemas/LandmarksModel"
          nullable: true
          type: array
        metadata:
          $ref: "#/components/schemas/ImageMetadata"
        requestId:
          description: Id of the REST API request.
          nullable: true
          type: string
      type: object
    LandmarksModel:
      description: A landmark recognized in the image.
      nullable: true
      properties:
        confidence:
          description: Confidence level for the landmark recognition as a value ranging from 0 to 1.
          format: double
          nullable: false
          type: number
        name:
          description: Name of the landmark.
          nullable: true
          type: string
      type: object
    ListModelsResult:
      description: Result of the List Domain Models operation.
      nullable: true
      properties:
        models:
          description: An array of supported models.
          items:
            $ref: "#/components/schemas/ModelDescription"
          nullable: true
          readOnly: true
          type: array
      type: object
    ModelDescription:
      description: An object describing supported model by name and categories.
      nullable: true
      properties:
        categories:
          description: Categories of the model.
          items:
            nullable: true
            type: string
          nullable: true
          type: array
        name:
          description: The name of the model.
          nullable: true
          type: string
      type: object
    ObjectHierarchy:
      description: An object detected inside an image.
      nullable: true
      properties:
        confidence:
          description: Confidence score of having observed the object in the image, as a value ranging from 0 to 1.
          format: double
          nullable: false
          type: number
        object:
          description: Label for the object.
          nullable: true
          type: string
        parent:
          $ref: "#/components/schemas/ObjectHierarchy"
      type: object
    OcrLine:
      description: An object describing a single recognized line of text.
      nullable: true
      properties:
        boundingBox:
          description: Bounding box of a recognized line. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down.
          nullable: true
          type: string
        words:
          description: An array of objects, where each object represents a recognized word.
          items:
            $ref: "#/components/schemas/OcrWord"
          nullable: true
          type: array
      type: object
    OcrRegion:
      description: A region consists of multiple lines (e.g. a column of text in a multi-column document).
      nullable: true
      properties:
        boundingBox:
          description: Bounding box of a recognized region. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down.
          nullable: true
          type: string
        lines:
          description: An array of recognized lines of text.
          items:
            $ref: "#/components/schemas/OcrLine"
          nullable: true
          type: array
      type: object
    OcrResult:
      nullable: true
      properties:
        language:
          description: The BCP-47 language code of the text in the image.
          nullable: true
          type: string
        orientation:
          description: Orientation of the text recognized in the image. The value (up, down, left, or right) refers to the direction that the top of the recognized text is facing, after the image has been rotated around its center according to the detected text angle (see textAngle property).
          nullable: true
          type: string
        regions:
          description: An array of objects, where each object represents a region of recognized text.
          items:
            $ref: "#/components/schemas/OcrRegion"
          nullable: true
          type: array
        textAngle:
          description: The angle, in degrees, of the detected text with respect to the closest horizontal or vertical direction. After rotating the input image clockwise by this angle, the recognized text lines become horizontal or vertical. In combination with the orientation property it can be used to overlay recognition results correctly on the original image, by rotating either the original image or recognition results by a suitable angle around the center of the original image. If the angle cannot be confidently detected, this property is not present. If the image contains text at different angles, only part of the text will be recognized correctly.
          format: double
          nullable: false
          type: number
      type: object
    OcrWord:
      description: Information on a recognized word.
      nullable: true
      properties:
        boundingBox:
          description: Bounding box of a recognized word. The four integers represent the x-coordinate of the left edge, the y-coordinate of the top edge, width, and height of the bounding box, in the coordinate system of the input image, after it has been rotated around its center according to the detected text angle (see textAngle property), with the origin at the top-left corner, and the y-axis pointing down.
          nullable: true
          type: string
        text:
          description: String value of a recognized word.
          nullable: true
          type: string
      type: object
    TagResult:
      description: The results of a image tag operation, including any tags and image metadata.
      nullable: true
      properties:
        metadata:
          $ref: "#/components/schemas/ImageMetadata"
        requestId:
          description: Id of the REST API request.
          nullable: true
          type: string
        tags:
          description: A list of tags with confidence level.
          items:
            $ref: "#/components/schemas/ImageTag"
          nullable: true
          type: array
      type: object
  securitySchemes:
    apim_key:
      in: header
      name: Ocp-Apim-Subscription-Key
      type: apiKey
x-ms-paths:
  /analyze?overload=stream:
    post:
      description: "This operation extracts a rich set of visual features based on the image content.\r

        Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL. Within your request, there is an optional parameter to allow you to choose which features to return. By default, image categories are returned in the response.\r

        A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong."
      operationId: AnalyzeImageInStream
      parameters:
        - $ref: "#/components/parameters/VisualFeatures"
        - description: "A string indicating which domain-specific details to return. Multiple values should be comma-separated. Valid visual feature types include: Celebrities - identifies celebrities if detected in the image, Landmarks - identifies notable landmarks in the image."
          examples:
            Successful AnalyzeImage request:
              value:
                - Celebrities
                - Landmarks
          explode: false
          in: query
          name: details
          required: false
          schema:
            items:
              enum:
                - Celebrities
                - Landmarks
              nullable: false
              type: string
              x-ms-enum:
                modelAsString: false
                name: Details
            type: array
          style: form
          x-nullable: true
        - $ref: "#/components/parameters/ServiceLanguage"
      requestBody:
        $ref: "#/components/requestBodies/AnalyzeImageInStreamImage"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful AnalyzeImage request:
                  $ref: "#/components/examples/Successful_AnalyzeImage_request"
              schema:
                $ref: "#/components/schemas/ImageAnalysis"
          description: "The response include the extracted features in JSON format. Here is the definitions for enumeration types:\r

            \ ClipartType\r

            \ Non - clipart = 0, ambiguous = 1, normal - clipart = 2, good - clipart = 3. LineDrawingTypeNon - LineDrawing = 0, LineDrawing = 1."
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /areaOfInterest?overload=stream:
    post:
      description: "This operation returns a bounding box around the most important area of the image.\r

        A successful response will be returned in JSON. If the request failed, the response contains an error code and a message to help determine what went wrong.\r

        Upon failure, the error code and an error message are returned. The error code could be one of InvalidImageUrl, InvalidImageFormat, InvalidImageSize, NotSupportedImage, FailedToProcess, Timeout, or InternalServerError."
      operationId: GetAreaOfInterestInStream
      requestBody:
        $ref: "#/components/requestBodies/AnalyzeImageInStreamImage"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful GetAreaOfInterest request:
                  $ref: "#/components/examples/Successful_GetAreaOfInterest_request"
              schema:
                $ref: "#/components/schemas/AreaOfInterestResult"
          description: The response includes the extracted area of interest in JSON format.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /describe?overload=stream:
    post:
      description: "This operation generates a description of an image in human readable language with complete sentences. The description is based on a collection of content tags, which are also returned by the operation. More than one description can be generated for each image. Descriptions are ordered by their confidence score. All descriptions are in English.\r

        Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL.\r

        A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong."
      operationId: DescribeImageInStream
      parameters:
        - description: Maximum number of candidate descriptions to be returned.  The default is 1.
          examples:
            Successful DescribeImage request:
              value: 1
          in: query
          name: maxCandidates
          required: false
          schema:
            default: 1
            format: int32
            type: integer
          x-nullable: true
        - $ref: "#/components/parameters/ServiceLanguage"
      requestBody:
        $ref: "#/components/requestBodies/AnalyzeImageInStreamImage"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful DescribeImage request:
                  $ref: "#/components/examples/Successful_DescribeImage_request"
              schema:
                $ref: "#/components/schemas/ImageDescription"
          description: Image description object.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /detect?overload=stream:
    post:
      description: "Performs object detection on the specified image.\r

        Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL.\r

        A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong."
      operationId: DetectObjectsInStream
      requestBody:
        $ref: "#/components/requestBodies/AnalyzeImageInStreamImage"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful DetectObjects request:
                  $ref: "#/components/examples/Successful_DetectObjects_request"
              schema:
                $ref: "#/components/schemas/DetectResult"
          description: The response include the detected objects in JSON format.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /generateThumbnail?overload=stream:
    post:
      description: "This operation generates a thumbnail image with the user-specified width and height. By default, the service analyzes the image, identifies the region of interest (ROI), and generates smart cropping coordinates based on the ROI. Smart cropping helps when you specify an aspect ratio that differs from that of the input image.\r

        A successful response contains the thumbnail image binary. If the request failed, the response contains an error code and a message to help determine what went wrong.\r

        Upon failure, the error code and an error message are returned. The error code could be one of InvalidImageUrl, InvalidImageFormat, InvalidImageSize, InvalidThumbnailSize, NotSupportedImage, FailedToProcess, Timeout, or InternalServerError."
      operationId: GenerateThumbnailInStream
      parameters:
        - description: Width of the thumbnail, in pixels. It must be between 1 and 1024. Recommended minimum of 50.
          examples:
            Successful GenerateThumbnail request:
              value: "500"
          in: query
          name: width
          required: true
          schema:
            format: int32
            maximum: 1024
            minimum: 1
            type: integer
          x-nullable: false
        - description: Height of the thumbnail, in pixels. It must be between 1 and 1024. Recommended minimum of 50.
          examples:
            Successful GenerateThumbnail request:
              value: "500"
          in: query
          name: height
          required: true
          schema:
            format: int32
            maximum: 1024
            minimum: 1
            type: integer
          x-nullable: false
        - description: Boolean flag for enabling smart cropping.
          examples:
            Successful GenerateThumbnail request:
              value: true
          in: query
          name: smartCropping
          required: false
          schema:
            default: false
            type: boolean
          x-nullable: true
      requestBody:
        $ref: "#/components/requestBodies/AnalyzeImageInStreamImage"
      responses:
        "200":
          content:
            application/octet-stream:
              examples:
                Successful GenerateThumbnail request:
                  $ref: "#/components/examples/Successful_GenerateThumbnail_request"
              schema:
                format: binary
                type: string
          description: The generated thumbnail in binary format.
        default:
          content:
            application/octet-stream:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  "/models/{model}/analyze?overload=stream":
    post:
      description: "This operation recognizes content within an image by applying a domain-specific model. The list of domain-specific models that are supported by the Computer Vision API can be retrieved using the /models GET request. Currently, the API provides following domain-specific models: celebrities, landmarks.\r

        Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL.\r

        A successful response will be returned in JSON.\r

        If the request failed, the response will contain an error code and a message to help understand what went wrong."
      operationId: AnalyzeImageByDomainInStream
      parameters:
        - description: The domain-specific content to recognize.
          examples:
            Successful AnalyzeImageByDomain request:
              value: Celebrities
          in: path
          name: model
          required: true
          schema:
            type: string
          x-nullable: true
        - $ref: "#/components/parameters/ServiceLanguage"
      requestBody:
        $ref: "#/components/requestBodies/AnalyzeImageInStreamImage"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful AnalyzeImageByDomain request:
                  $ref: "#/components/examples/Successful_AnalyzeImageByDomain_request"
              schema:
                $ref: "#/components/schemas/DomainModelResults"
          description: Analysis result based on the domain model.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /ocr?overload=stream:
    post:
      description: "Optical Character Recognition (OCR) detects text in an image and extracts the recognized characters into a machine-usable character stream.\r

        Upon success, the OCR results will be returned.\r

        Upon failure, the error code together with an error message will be returned. The error code can be one of InvalidImageUrl, InvalidImageFormat, InvalidImageSize, NotSupportedImage, NotSupportedLanguage, or InternalServerError."
      operationId: RecognizePrintedTextInStream
      parameters:
        - $ref: "#/components/parameters/DetectOrientation"
        - $ref: "#/components/parameters/OcrLanguage"
      requestBody:
        $ref: "#/components/requestBodies/AnalyzeImageInStreamImage"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful RecognizePrintedText request:
                  $ref: "#/components/examples/Successful_RecognizePrintedText_request"
              schema:
                $ref: "#/components/schemas/OcrResult"
          description: The OCR results in the hierarchy of region/line/word. The results include text, bounding box for regions, lines and words. The angle, in degrees, of the detected text with respect to the closest horizontal or vertical direction. After rotating the input image clockwise by this angle, the recognized text lines become horizontal or vertical. In combination with the orientation property it can be used to overlay recognition results correctly on the original image, by rotating either the original image or recognition results by a suitable angle around the center of the original image. If the angle cannot be confidently detected, this property is not present. If the image contains text at different angles, only part of the text will be recognized correctly.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /tag?overload=stream:
    post:
      description: "This operation generates a list of words, or tags, that are relevant to the content of the supplied image. The Computer Vision API can return tags based on objects, living beings, scenery or actions found in images. Unlike categories, tags are not organized according to a hierarchical classification system, but correspond to image content. Tags may contain hints to avoid ambiguity or provide context, for example the tag \"cello\" may be accompanied by the hint \"musical instrument\". All tags are in English.\r

        Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL.\r

        A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong."
      operationId: TagImageInStream
      parameters:
        - $ref: "#/components/parameters/ServiceLanguage"
      requestBody:
        $ref: "#/components/requestBodies/AnalyzeImageInStreamImage"
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful TagImage request:
                  $ref: "#/components/examples/Successful_TagImage_request"
              schema:
                $ref: "#/components/schemas/TagResult"
          description: Image tags object.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
