Call the Image Analysis API

This article demonstrates how to call the Image Analysis API to return information about an image's visual features. It also shows you how to parse the returned information using the client SDKs or REST API.

This guide assumes you have already created a Computer Vision resource and obtained a key and endpoint URL. If you're using a client SDK, you'll also need to authenticate a client object. If you haven't done these steps, follow the quickstart to get started.

Submit data to the service

The code in this guide uses remote images referenced by URL. You may want to try different images on your own to see the full capability of the Image Analysis features.

When analyzing a remote image, you specify the image's URL by formatting the request body like this: {"url":"http://example.com/images/test.jpg"}.

To analyze a local image, you'd put the binary image data in the HTTP request body.

Determine how to process the data

Select visual features

The Analyze API gives you access to all of the service's image analysis features. Choose which operations to do based on your own use case. See the overview for a description of each feature. The examples below add all of the available visual features, but for practical usage you'll likely only need one or two.

You can specify which features you want to use by setting the URL query parameters of the Analyze API. A parameter can have multiple values, separated by commas. Each feature you specify will require more computation time, so only specify what you need.

URL parameter Value Description
features Read reads the visible text in the image and outputs it as structured JSON data.
features Description describes the image content with a complete sentence in supported languages.
features SmartCrops finds the rectangle coordinates that would crop the image to a desired aspect ratio while preserving the area of interest.
features Objects detects various objects within an image, including the approximate location. The Objects argument is only available in English.
features Tags tags the image with a detailed list of words related to the image content.

A populated URL might look like this:

https://{endpoint}/computervision/imageanalysis:analyze?api-version=2022-10-12-preview&features=Tags

Specify languages

You can also specify the language of the returned data.

The following URL query parameter specifies the language. The default value is en.

URL parameter Value Description
language en English
language es Spanish
language ja Japanese
language pt Portuguese
language zh Simplified Chinese

A populated URL might look like this:

https://{endpoint}/computervision/imageanalysis:analyze?api-version=2022-10-12-preview&features=Tags&language=en

Get results from the service

This section shows you how to parse the results of the API call. It includes the API call itself.

Note

Scoped API calls

Some of the features in Image Analysis can be called directly as well as through the Analyze API call. For example, you can do a scoped analysis of only image tags by making a request to https://{endpoint}/vision/v3.2/tag (or to the corresponding method in the SDK). See the reference documentation for other features that can be called separately.

The service returns a 200 HTTP response, and the body contains the returned data in the form of a JSON string. The following text is an example of a JSON response.

{
    "metadata":
    {
        "width": 300,
        "height": 200
    },
    "tagsResult":
    {
        "values":
        [
            {
                "name": "grass",
                "confidence": 0.9960499405860901
            },
            {
                "name": "outdoor",
                "confidence": 0.9956876635551453
            },
            {
                "name": "building",
                "confidence": 0.9893627166748047
            },
            {
                "name": "property",
                "confidence": 0.9853052496910095
            },
            {
                "name": "plant",
                "confidence": 0.9791355729103088
            }
        ]
    }
}

Error codes

See the following list of possible errors and their causes:

  • 400
    • InvalidImageUrl - Image URL is badly formatted or not accessible.
    • InvalidImageFormat - Input data is not a valid image.
    • InvalidImageSize - Input image is too large.
    • NotSupportedVisualFeature - Specified feature type isn't valid.
    • NotSupportedImage - Unsupported image, for example child pornography.
    • InvalidDetails - Unsupported detail parameter value.
    • NotSupportedLanguage - The requested operation isn't supported in the language specified.
    • BadArgument - More details are provided in the error message.
  • 415 - Unsupported media type error. The Content-Type isn't in the allowed types:
    • For an image URL, Content-Type should be application/json
    • For a binary image data, Content-Type should be application/octet-stream or multipart/form-data
  • 500
    • FailedToProcess
    • Timeout - Image processing timed out.
    • InternalServerError

Tip

While working with Computer Vision, you might encounter transient failures caused by rate limits enforced by the service, or other transient problems like network outages. For information about handling these types of failures, see Retry pattern in the Cloud Design Patterns guide, and the related Circuit Breaker pattern.

Next steps