Call the Azure AI Vision 3.2 GA Read API

This guide shows you how to call the v3.2 GA Read API to extract text from images. You'll learn the different ways you can configure the behavior of this API to meet your needs. This guide assumes you have already create a Vision resource and obtained a key and endpoint URL. If you haven't, follow a quickstart to get started.

OCR (Read) editions

Input requirements

The Read API call takes images and documents as its input. They have the following requirements:

• Supported file formats: JPEG, PNG, BMP, PDF, and TIFF
• For PDF and TIFF files, up to 2,000 pages (only the first two pages for the free tier) are processed.
• The file size of images must be less than 500 MB (4 MB for the free tier) and dimensions at least 50 x 50 pixels and at most 10,000 x 10,000 pixels. PDF files don't have a size limit.
• The minimum height of the text to be extracted is 12 pixels for a 1024 x 768 image. This corresponds to about 8 font point text at 150 DPI.

Determine how to process the data (optional)

Specify the OCR model

By default, the service uses the latest generally available (GA) model to extract text. Starting with Read 3.2, a model-version parameter allows choosing between the GA and preview models for a given API version. The model you specify will be used to extract text with the Read operation.

When using the Read operation, use the following values for the optional model-version parameter.

Input language

By default, the service extracts all text from your images or documents including mixed languages. The Read operation has an optional request parameter for language. Only provide a language code if you want to force the document to be processed as that specific language. Otherwise, the service may return incomplete and incorrect text.

Natural reading order output (Latin languages only)

By default, the service outputs the text lines in the left to right order. Optionally, with the readingOrder request parameter, use natural for a more human-friendly reading order output as shown in the following example. This feature is only supported for Latin languages.

Select page(s) or page range(s) for text extraction

By default, the service extracts text from all pages in the documents. Optionally, use the pages request parameter to specify page numbers or page ranges to extract text from only those pages. The following example shows a document with 10 pages, with text extracted for both cases - all pages (1-10) and selected pages (3-6).

Submit data to the service

You submit either a local image or a remote image to the Read API. For local, you put the binary image data in the HTTP request body. For remote, you specify the image's URL by formatting the request body like the following: {"url":"http://example.com/images/test.jpg"}.

The Read API's Read call takes an image or PDF document as the input and extracts text asynchronously.

https://{endpoint}/vision/v3.2/read/analyze[?language][&pages][&readingOrder]

The call returns with a response header field called Operation-Location. The Operation-Location value is a URL that contains the Operation ID to be used in the next step.

Get results from the service

The second step is to call Get Read Result operation. This operation takes as input the operation ID that was created by the Read operation.

https://{endpoint}/vision/v3.2/read/analyzeResults/{operationId}

It returns a JSON response that contains a status field with the following possible values.

You call this operation iteratively until it returns with the succeeded value. Use an interval of 1 to 2 seconds to avoid exceeding the requests per second (RPS) rate.

When the status field has the succeeded value, the JSON response contains the extracted text content from your image or document. The JSON response maintains the original line groupings of recognized words. It includes the extracted text lines and their bounding box coordinates. Each text line includes all extracted words with their coordinates and confidence scores.

Sample JSON output

See the following example of a successful JSON response:

{
  "status": "succeeded",
  "createdDateTime": "2021-02-04T06:32:08.2752706+00:00",
  "lastUpdatedDateTime": "2021-02-04T06:32:08.7706172+00:00",
  "analyzeResult": {
    "version": "3.2",
    "readResults": [
      {
        "page": 1,
        "angle": 2.1243,
        "width": 502,
        "height": 252,
        "unit": "pixel",
        "lines": [
          {
            "boundingBox": [
              58,
              42,
              314,
              59,
              311,
              123,
              56,
              121
            ],
            "text": "Tabs vs",
            "appearance": {
              "style": {
                "name": "handwriting",
                "confidence": 0.96
              }
            },
            "words": [
              {
                "boundingBox": [
                  68,
                  44,
                  225,
                  59,
                  224,
                  122,
                  66,
                  123
                ],
                "text": "Tabs",
                "confidence": 0.933
              },
              {
                "boundingBox": [
                  241,
                  61,
                  314,
                  72,
                  314,
                  123,
                  239,
                  122
                ],
                "text": "vs",
                "confidence": 0.977
              }
            ]
          }
        ]
      }
    ]
  }
}

Handwritten classification for text lines (Latin languages only)

The response includes a classification of whether each line of text is in handwritten style or not, along with a confidence score. This feature is only available for Latin languages. The following example shows the handwritten classification for the text in the image.

Next steps

• Get started with the OCR (Read) REST API or client library quickstarts.
• Read 3.2 REST API reference.