Quickstart: Analyze a local image using the REST API and Python in Computer Vision

In this quickstart, you analyze a locally stored image to extract visual features by using Computer Vision's REST API. With the Analyze Image method, you can extract visual features based on image content.

You can run this quickstart in a step-by step fashion using a Jupyter notebook on MyBinder. To launch Binder, select the following button:


If you don't have an Azure subscription, create a free account before you begin.


  • You must have Python installed if you want to run the sample locally.
  • You must have a subscription key for Computer Vision. You can get a free trial key from Try Cognitive Services. Or, follow the instructions in Create a Cognitive Services account to subscribe to Computer Vision and get your key.
  • You must have the following Python packages installed. You can use pip to install Python packages.

Create and run the sample

To create and run the sample, do the following steps:

  1. Copy the following code into a text editor.
  2. Make the following changes in code where needed:
    1. Replace the value of subscription_key with your subscription key.
    2. Replace the value of vision_base_url with the endpoint URL for the Computer Vision resource in the Azure region where you obtained your subscription keys, if necessary.
    3. Optionally, replace the value of image_path with the path and file name of a different image that you want to analyze.
  3. Save the code as a file with an .py extension. For example, analyze-local-image.py.
  4. Open a command prompt window.
  5. At the prompt, use the python command to run the sample. For example, python analyze-local-image.py.
import requests
# If you are using a Jupyter notebook, uncomment the following line.
#%matplotlib inline
import matplotlib.pyplot as plt
from PIL import Image
from io import BytesIO

# Replace <Subscription Key> with your valid subscription key.
subscription_key = "<Subscription Key>"
assert subscription_key

# You must use the same region in your REST call as you used to get your
# subscription keys. For example, if you got your subscription keys from
# westus, replace "westcentralus" in the URI below with "westus".
# Free trial subscription keys are generated in the "westus" region.
# If you use a free trial subscription key, you shouldn't need to change
# this region.
vision_base_url = "https://westcentralus.api.cognitive.microsoft.com/vision/v2.0/"

analyze_url = vision_base_url + "analyze"

# Set image_path to the local path of an image that you want to analyze.
image_path = "C:/Documents/ImageToAnalyze.jpg"

# Read the image into a byte array
image_data = open(image_path, "rb").read()
headers    = {'Ocp-Apim-Subscription-Key': subscription_key,
              'Content-Type': 'application/octet-stream'}
params     = {'visualFeatures': 'Categories,Description,Color'}
response = requests.post(
    analyze_url, headers=headers, params=params, data=image_data)

# The 'analysis' object contains various fields that describe the image. The most
# relevant caption for the image is obtained from the 'description' property.
analysis = response.json()
image_caption = analysis["description"]["captions"][0]["text"].capitalize()

# Display the image and overlay it with the caption.
image = Image.open(BytesIO(image_data))
_ = plt.title(image_caption, size="x-large", y=-0.1)

Examine the response

A successful response is returned in JSON. The sample webpage parses and displays a successful response in the command prompt window, similar to the following example:

  "categories": [
      "name": "outdoor_",
      "score": 0.00390625,
      "detail": {
        "landmarks": []
      "name": "outdoor_street",
      "score": 0.33984375,
      "detail": {
        "landmarks": []
  "description": {
    "tags": [
    "captions": [
        "text": "a group of people on a city street at night",
        "confidence": 0.9122243847383961
  "color": {
    "dominantColorForeground": "Brown",
    "dominantColorBackground": "Brown",
    "dominantColors": [
    "accentColor": "B54316",
    "isBwImg": false
  "requestId": "c11894eb-de3e-451b-9257-7c8b168073d1",
  "metadata": {
    "height": 600,
    "width": 450,
    "format": "Jpeg"

Clean up resources

When no longer needed, delete the file.

Next steps

Explore a Python application that uses Computer Vision to perform optical character recognition (OCR); create smart-cropped thumbnails; plus detect, categorize, tag, and describe visual features, including faces, in an image. To rapidly experiment with the Computer Vision API, try the Open API testing console.