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/Ocr.json
      version: "3.0"
  x-preferred: false
  x-providerName: microsoft.com
  x-serviceName: cognitiveservices-Ocr
  x-tags:
    - Microsoft
security:
  - apim_key: []
paths:
  /read/core/asyncBatchAnalyze:
    post:
      description: Use this interface to get the result of a Read operation, employing the state-of-the-art Optical Character Recognition (OCR) algorithms optimized for text-heavy documents. When you use the Read File interface, the response contains a field called 'Operation-Location'. The 'Operation-Location' field contains the URL that you must use for your 'GetReadOperationResult' operation to access OCR results.​
      operationId: BatchReadFile
      requestBody:
        $ref: "#/components/requestBodies/ImageUrl"
      responses:
        "202":
          description: The service has accepted the request and will start processing later.
          headers:
            Operation-Location:
              description: "URL to query for status of the operation. The operation ID will expire in 48 hours. "
              schema:
                type: string
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  "/read/operations/{operationId}":
    get:
      description: This interface is used for getting OCR results of Read operation. The URL to this interface should be retrieved from 'Operation-Location' field returned from Batch Read File interface.
      operationId: GetReadOperationResult
      parameters:
        - description: Id of read operation returned in the response of the 'Batch Read File' interface.
          examples:
            Successful Get Read Operation Result request:
              value: e56ffa6e-1ee4-4042-bc07-993db706c95f
          in: path
          name: operationId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful Get Read Operation Result request:
                  $ref: "#/components/examples/Successful_Get_Read_Operation_Result_request"
              schema:
                $ref: "#/components/schemas/ReadOperationResult"
          description: Returns the read operation status.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /recognizeText:
    post:
      description: Recognize Text operation. When you use the Recognize Text interface, the response contains a field called 'Operation-Location'. The 'Operation-Location' field contains the URL that you must use for your Get Recognize Text Operation Result operation.
      operationId: RecognizeText
      parameters:
        - $ref: "#/components/parameters/TextRecognitionMode"
      requestBody:
        $ref: "#/components/requestBodies/ImageUrl"
      responses:
        "202":
          description: The service has accepted the request and will start processing later. It will return Accepted immediately and include an 'Operation-Location' header. Client side should further query the operation status using the URL specified in this header. The operation ID will expire in 48 hours.
          headers:
            Operation-Location:
              description: "URL to query for status of the operation. The operation ID will expire in 48 hours. "
              schema:
                type: string
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  "/textOperations/{operationId}":
    get:
      description: This interface is used for getting text operation result. The URL to this interface should be retrieved from 'Operation-Location' field returned from Recognize Text interface.
      operationId: GetTextOperationResult
      parameters:
        - description: Id of the text operation returned in the response of the 'Recognize Text'
          examples:
            Successful Get Text Operation Result request:
              value: 49a36324-fc4b-4387-aa06-090cfbf0064f
          in: path
          name: operationId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                Successful Get Text Operation Result request:
                  $ref: "#/components/examples/Successful_Get_Text_Operation_Result_request"
              schema:
                $ref: "#/components/schemas/TextOperationResult"
          description: Returns the operation status.
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
components:
  examples:
    Successful_Get_Read_Operation_Result_request:
      value:
        recognitionResults:
          - clockwiseOrientation: 349.59
            height: 400
            lines:
              - boundingBox:
                  - 202
                  - 618
                  - 2047
                  - 643
                  - 2046
                  - 840
                  - 200
                  - 813
                text: Our greatest glory is not
                words:
                  - boundingBox:
                      - 204
                      - 627
                      - 481
                      - 628
                      - 481
                      - 830
                      - 204
                      - 829
                    text: Our
                  - boundingBox:
                      - 519
                      - 628
                      - 1057
                      - 630
                      - 1057
                      - 832
                      - 518
                      - 830
                    text: greatest
                  - boundingBox:
                      - 1114
                      - 630
                      - 1549
                      - 631
                      - 1548
                      - 833
                      - 1114
                      - 832
                    text: glory
                  - boundingBox:
                      - 1586
                      - 631
                      - 1785
                      - 632
                      - 1784
                      - 834
                      - 1586
                      - 833
                    text: is
                  - boundingBox:
                      - 1822
                      - 632
                      - 2115
                      - 633
                      - 2115
                      - 835
                      - 1822
                      - 834
                    text: not
              - boundingBox:
                  - 420
                  - 1273
                  - 2954
                  - 1250
                  - 2958
                  - 1488
                  - 422
                  - 1511
                text: but in rising every time we fall
                words:
                  - boundingBox:
                      - 423
                      - 1269
                      - 634
                      - 1268
                      - 635
                      - 1507
                      - 424
                      - 1508
                    text: but
                  - boundingBox:
                      - 667
                      - 1268
                      - 808
                      - 1268
                      - 809
                      - 1506
                      - 668
                      - 1507
                    text: in
                  - boundingBox:
                      - 874
                      - 1267
                      - 1289
                      - 1265
                      - 1290
                      - 1504
                      - 875
                      - 1506
                    text: rising
                  - boundingBox:
                      - 1331
                      - 1265
                      - 1771
                      - 1263
                      - 1772
                      - 1502
                      - 1332
                      - 1504
                    text: every
                  - boundingBox:
                      - 1812
                      - 1263
                      - 2178
                      - 1261
                      - 2179
                      - 1500
                      - 1813
                      - 1502
                    text: time
                  - boundingBox:
                      - 2219
                      - 1261
                      - 2510
                      - 1260
                      - 2511
                      - 1498
                      - 2220
                      - 1500
                    text: we
                  - boundingBox:
                      - 2551
                      - 1260
                      - 3016
                      - 1258
                      - 3017
                      - 1496
                      - 2552
                      - 1498
                    text: fall
            page: 1
            unit: pixel
            width: 600
          - clockwiseOrientation: 1.32
            height: 400
            lines:
              - boundingBox:
                  - 1612
                  - 903
                  - 2744
                  - 935
                  - 2738
                  - 1139
                  - 1607
                  - 1107
                text: in never failing ,
                words:
                  - boundingBox:
                      - 1611
                      - 934
                      - 1707
                      - 933
                      - 1708
                      - 1147
                      - 1613
                      - 1147
                    text: in
                  - boundingBox:
                      - 1753
                      - 933
                      - 2132
                      - 930
                      - 2133
                      - 1144
                      - 1754
                      - 1146
                    text: never
                  - boundingBox:
                      - 2162
                      - 930
                      - 2673
                      - 927
                      - 2674
                      - 1140
                      - 2164
                      - 1144
                    text: failing
                  - boundingBox:
                      - 2703
                      - 926
                      - 2788
                      - 926
                      - 2790
                      - 1139
                      - 2705
                      - 1140
                    confidence: Low
                    text: ","
            page: 2
            unit: pixel
            width: 600
        status: Succeeded
    Successful_Get_Text_Operation_Result_request:
      value:
        recognitionResult:
          lines:
            - boundingBox:
                - 202
                - 618
                - 2047
                - 643
                - 2046
                - 840
                - 200
                - 813
              text: Our greatest glory is not
              words:
                - boundingBox:
                    - 204
                    - 627
                    - 481
                    - 628
                    - 481
                    - 830
                    - 204
                    - 829
                  text: Our
                - boundingBox:
                    - 519
                    - 628
                    - 1057
                    - 630
                    - 1057
                    - 832
                    - 518
                    - 830
                  text: greatest
                - boundingBox:
                    - 1114
                    - 630
                    - 1549
                    - 631
                    - 1548
                    - 833
                    - 1114
                    - 832
                  text: glory
                - boundingBox:
                    - 1586
                    - 631
                    - 1785
                    - 632
                    - 1784
                    - 834
                    - 1586
                    - 833
                  text: is
                - boundingBox:
                    - 1822
                    - 632
                    - 2115
                    - 633
                    - 2115
                    - 835
                    - 1822
                    - 834
                  text: not
            - boundingBox:
                - 420
                - 1273
                - 2954
                - 1250
                - 2958
                - 1488
                - 422
                - 1511
              text: but in rising every time we fall
              words:
                - boundingBox:
                    - 423
                    - 1269
                    - 634
                    - 1268
                    - 635
                    - 1507
                    - 424
                    - 1508
                  text: but
                - boundingBox:
                    - 667
                    - 1268
                    - 808
                    - 1268
                    - 809
                    - 1506
                    - 668
                    - 1507
                  text: in
                - boundingBox:
                    - 874
                    - 1267
                    - 1289
                    - 1265
                    - 1290
                    - 1504
                    - 875
                    - 1506
                  text: rising
                - boundingBox:
                    - 1331
                    - 1265
                    - 1771
                    - 1263
                    - 1772
                    - 1502
                    - 1332
                    - 1504
                  text: every
                - boundingBox:
                    - 1812
                    - 1263
                    - 2178
                    - 1261
                    - 2179
                    - 1500
                    - 1813
                    - 1502
                  text: time
                - boundingBox:
                    - 2219
                    - 1261
                    - 2510
                    - 1260
                    - 2511
                    - 1498
                    - 2220
                    - 1500
                  text: we
                - boundingBox:
                    - 2551
                    - 1260
                    - 3016
                    - 1258
                    - 3017
                    - 1496
                    - 2552
                    - 1498
                  text: fall
            - boundingBox:
                - 1612
                - 903
                - 2744
                - 935
                - 2738
                - 1139
                - 1607
                - 1107
              text: in never failing ,
              words:
                - boundingBox:
                    - 1611
                    - 934
                    - 1707
                    - 933
                    - 1708
                    - 1147
                    - 1613
                    - 1147
                  text: in
                - boundingBox:
                    - 1753
                    - 933
                    - 2132
                    - 930
                    - 2133
                    - 1144
                    - 1754
                    - 1146
                  text: never
                - boundingBox:
                    - 2162
                    - 930
                    - 2673
                    - 927
                    - 2674
                    - 1140
                    - 2164
                    - 1144
                  text: failing
                - boundingBox:
                    - 2703
                    - 926
                    - 2788
                    - 926
                    - 2790
                    - 1139
                    - 2705
                    - 1140
                  text: ","
        status: Succeeded
  parameters:
    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
    TextRecognitionMode:
      description: Type of text to recognize.
      examples:
        Successful Recognize Text request:
          value: Handwritten
      in: query
      name: mode
      required: true
      schema:
        enum:
          - Handwritten
          - Printed
        type: string
      x-ms-enum:
        modelAsString: false
        name: TextRecognitionMode
      x-ms-parameter-location: method
  requestBodies:
    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
    RecognizeTextInStreamImage:
      content:
        application/octet-stream:
          schema:
            format: file
            type: object
      description: An image stream.
      required: true
      x-ms-parameter-location: method
  schemas:
    BoundingBox:
      description: Quadrangle bounding box, with coordinates in original image. The eight numbers represent the four points (x-coordinate, y-coordinate from the left-top corner of the image) of the detected rectangle from the left-top corner in the clockwise direction. For images, coordinates are in pixels. For PDF, coordinates are in inches.
      items:
        nullable: false
        type: number
      type: array
    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
    ImageUrl:
      properties:
        url:
          description: Publicly reachable URL of an image.
          type: string
      required:
        - url
      type: object
    Line:
      description: An object representing a recognized text line.
      properties:
        boundingBox:
          $ref: "#/components/schemas/BoundingBox"
        text:
          description: The text content of the line.
          type: string
        words:
          description: List of words in the text line.
          items:
            $ref: "#/components/schemas/Word"
          type: array
      type: object
    OperationStatus:
      description: Status code of the text operation.
      enum:
        - NotStarted
        - Running
        - Failed
        - Succeeded
      nullable: false
      type: string
      x-ms-enum:
        modelAsString: false
        name: TextOperationStatusCodes
    ReadOperationResult:
      description: OCR result of the read operation.
      properties:
        recognitionResults:
          description: An array of text recognition result of the read operation.
          items:
            $ref: "#/components/schemas/TextRecognitionResult"
          type: array
        status:
          $ref: "#/components/schemas/OperationStatus"
      type: object
    TextOperationResult:
      description: Result of recognition text operation.
      properties:
        recognitionResult:
          $ref: "#/components/schemas/TextRecognitionResult"
        status:
          $ref: "#/components/schemas/OperationStatus"
      type: object
    TextRecognitionResult:
      description: An object representing a recognized text region
      properties:
        clockwiseOrientation:
          description: The orientation of the image in degrees in the clockwise direction. Range between [0, 360).
          type: number
        height:
          description: The height of the image in pixels or the PDF in inches.
          type: number
        lines:
          description: A list of recognized text lines.
          items:
            $ref: "#/components/schemas/Line"
          type: array
        page:
          description: The 1-based page number of the recognition result.
          type: integer
        unit:
          description: The unit used in the Width, Height and BoundingBox. For images, the unit is 'pixel'. For PDF, the unit is 'inch'.
          enum:
            - pixel
            - inch
          nullable: true
          type: string
          x-ms-enum:
            modelAsString: false
            name: TextRecognitionResultDimensionUnit
        width:
          description: The width of the image in pixels or the PDF in inches.
          type: number
      required:
        - lines
      type: object
    Word:
      description: An object representing a recognized word.
      properties:
        boundingBox:
          $ref: "#/components/schemas/BoundingBox"
        confidence:
          description: Qualitative confidence measure.
          enum:
            - High
            - Low
          nullable: true
          type: string
          x-ms-enum:
            modelAsString: false
            name: TextRecognitionResultConfidenceClass
        text:
          description: The text content of the word.
          type: string
      required:
        - boundingBox
        - text
      type: object
  securitySchemes:
    apim_key:
      in: header
      name: Ocp-Apim-Subscription-Key
      type: apiKey
x-ms-paths:
  /read/core/asyncBatchAnalyze?overload=stream:
    post:
      description: Use this interface to get the result of a Read Document operation, employing the state-of-the-art Optical Character Recognition (OCR) algorithms optimized for text-heavy documents. When you use the Read Document interface, the response contains a field called 'Operation-Location'. The 'Operation-Location' field contains the URL that you must use for your 'Get Read Result operation' to access OCR results.​
      operationId: BatchReadFileInStream
      requestBody:
        $ref: "#/components/requestBodies/RecognizeTextInStreamImage"
      responses:
        "202":
          description: The service has accepted the request and will start processing later.
          headers:
            Operation-Location:
              description: "URL to query for status of the operation. The operation ID will expire in 48 hours. "
              schema:
                type: string
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
  /recognizeText?overload=stream:
    post:
      description: Recognize Text operation. When you use the Recognize Text interface, the response contains a field called 'Operation-Location'. The 'Operation-Location' field contains the URL that you must use for your Get Recognize Text Operation Result operation.
      operationId: RecognizeTextInStream
      parameters:
        - $ref: "#/components/parameters/TextRecognitionMode"
      requestBody:
        $ref: "#/components/requestBodies/RecognizeTextInStreamImage"
      responses:
        "202":
          description: The service has accepted the request and will start processing later.
          headers:
            Operation-Location:
              description: "URL to query for status of the operation. The operation ID will expire in 48 hours. "
              schema:
                type: string
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ComputerVisionError"
          description: Error response.
