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

In this quickstart, you will analyze a locally stored image to extract visual features using the Computer Vision 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. Then, create environment variables for the key and service endpoint string, named COMPUTER_VISION_SUBSCRIPTION_KEY and COMPUTER_VISION_ENDPOINT, respectively.
  • 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. 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

# Add your Computer Vision subscription key and endpoint to your environment variables.
    subscription_key = os.environ['COMPUTER_VISION_SUBSCRIPTION_KEY']
    print("\nSet the COMPUTER_VISION_SUBSCRIPTION_KEY environment variable.\n**Restart your shell or IDE for changes to take effect.**")

if 'COMPUTER_VISION_ENDPOINT' in os.environ:
    endpoint = os.environ['COMPUTER_VISION_ENDPOINT']

analyze_url = endpoint + "vision/v2.1/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"

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.