Azure AI Vision Image Analysis Client Library

Warnings

• breaking The SDK was extensively rewritten in version 1.0.0-beta.1 to align with other Azure SDKs. All APIs changed significantly from previous preview versions (e.g., `azure-cognitiveservices-vision-computervision`). Users migrating from older SDKs or preview versions must update their code according to the new API surface.
  Fix: Refer to the latest official quickstarts and samples for updated API usage. The current `azure-ai-vision-imageanalysis` library uses the generally available Computer Vision REST API (2023-10-01).
• gotcha Authentication credentials (endpoint and key) must be explicitly passed to the `ImageAnalysisClient` constructor. The library does not automatically read `VISION_ENDPOINT` and `VISION_KEY` from environment variables, although samples often show reading them into variables for good practice.
  Fix: Always pass `endpoint=os.environ.get('VISION_ENDPOINT')` and `credential=AzureKeyCredential(os.environ.get('VISION_KEY'))` (or `DefaultAzureCredential()`) to the `ImageAnalysisClient` constructor.
• gotcha Certain visual features, like 'Caption' or 'Dense Captions', require your Computer Vision resource to be deployed in a GPU-supported Azure region. If your resource is in an unsupported region, requests for these features will fail with a `400 Bad Request` error.
  Fix: Verify that your Azure AI Vision resource is deployed in a region that supports the specific visual features you intend to use. Consult Azure documentation for supported regions.
• gotcha Image analysis has specific constraints: supported formats (JPEG, PNG, GIF, BMP, WEBP, ICO, TIFF, MPO), file size (less than 20 MB), and dimensions (between 50x50 and 16000x16000 pixels). Exceeding these limits will result in `400 Bad Request` errors.
  Fix: Ensure all images conform to the specified formats, size, and dimension limits before sending them for analysis. Resize or reformat as necessary.
• gotcha For Optical Character Recognition (OCR) on document-heavy content like PDFs, Office documents, or HTML, use the Azure Document Intelligence service and its specialized Read model instead of the Image Analysis service. The Image Analysis OCR (`VisualFeatures.READ`) is optimized for general images.
  Fix: For document processing, switch to Azure Document Intelligence. For general image OCR, use `VisualFeatures.READ` with `azure-ai-vision-imageanalysis`.
• deprecated Older Computer Vision API versions (1.0, 2.0, 3.0, 3.1, and 3.2 preview) are scheduled for retirement. The Image Analysis 4.0 Preview APIs (e.g., `2023-04-01-preview`) will be retired on March 31, 2025. This library (`azure-ai-vision-imageanalysis`) targets the GA 4.0 API.
  Fix: Migrate any existing workloads using older Computer Vision APIs to the `azure-ai-vision-imageanalysis` library and the Image Analysis 4.0 GA API to ensure continued service.

Install

• pip install azure-ai-vision-imageanalysis Install stable version
• pip install azure-identity Install for Azure AD authentication
• pip install aiohttp Install for asynchronous client

Imports

• ImageAnalysisClient

  from azure.ai.vision.imageanalysis import ImageAnalysisClient

• VisualFeatures

  from azure.ai.vision.imageanalysis.models import VisualFeatures

• AzureKeyCredential
  wrong:

  from azure.ai.vision.imageanalysis import AzureKeyCredential

  correct:

  from azure.core.credentials import AzureKeyCredential

  AzureKeyCredential is part of azure-core, not directly the imageanalysis library.
• DefaultAzureCredential
  wrong:

  from azure.ai.vision.imageanalysis import DefaultAzureCredential

  correct:

  from azure.identity import DefaultAzureCredential

  DefaultAzureCredential is part of azure-identity, which needs to be installed separately.

Quickstart

This quickstart demonstrates how to authenticate with an Azure AI Vision Image Analysis resource using an API key and analyze an image from a URL to generate a caption and extract tags. Ensure `VISION_ENDPOINT` and `VISION_KEY` environment variables are set with your resource's endpoint and API key.

import os
from azure.ai.vision.imageanalysis import ImageAnalysisClient
from azure.ai.vision.imageanalysis.models import VisualFeatures
from azure.core.credentials import AzureKeyCredential

# Set environment variables or replace with actual values
# For authentication with AzureKeyCredential
vision_endpoint = os.environ.get('VISION_ENDPOINT', 'YOUR_VISION_ENDPOINT')
vision_key = os.environ.get('VISION_KEY', 'YOUR_VISION_KEY')

# For authentication with DefaultAzureCredential (uncomment and configure if needed)
# from azure.identity import DefaultAzureCredential
# credential = DefaultAzureCredential()

# Authenticate the client
# Using AzureKeyCredential (most common for quickstarts)
credential = AzureKeyCredential(vision_key)
client = ImageAnalysisClient(endpoint=vision_endpoint, credential=credential)

# Image to analyze
image_url = "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png"

print("Analyzing image from URL...")

# Analyze the image for a caption
result = client.analyze_from_url(
    image_url,
    visual_features=[VisualFeatures.CAPTION, VisualFeatures.TAGS]
)

if result.caption is not None:
    print(f" Caption: '{result.caption.text}' (confidence: {result.caption.confidence:.2f})")

if result.tags is not None:
    print(" Tags:")
    for tag in result.tags.list:
        print(f"   '{tag.name}' (confidence: {tag.confidence:.2f})")