Registry /
azure / azure-ai-vision-imageanalysis
Install & Compatibility
Where this runs
tested against v1.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.960 runs
installs and imports cleanly · install 0.0s · import 0.429s · 97.3MB
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 3.2s · import 0.389s · 24MB
58MB installed
● package 58MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ImageAnalysisClient
✓ from azure.ai.vision.imageanalysis import ImageAnalysisClient
VisualFeatures
✓ from azure.ai.vision.imageanalysis.models import VisualFeatures
AzureKeyCredential
✓ from azure.core.credentials import AzureKeyCredential
✗ from azure.ai.vision.imageanalysis import AzureKeyCredential
AzureKeyCredential is part of azure-core, not directly the imageanalysis library.
DefaultAzureCredential
✓ from azure.identity import DefaultAzureCredential
✗ from azure.ai.vision.imageanalysis import DefaultAzureCredential
DefaultAzureCredential is part of azure-identity, which needs to be installed separately.
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})")
Debug
Known issues
breakingThe 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.fixRefer 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).
affects: <1.0.0-beta.1
gotchaAuthentication 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.fixAlways pass `endpoint=os.environ.get('VISION_ENDPOINT')` and `credential=AzureKeyCredential(os.environ.get('VISION_KEY'))` (or `DefaultAzureCredential()`) to the `ImageAnalysisClient` constructor. affects: All versions
gotchaCertain 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.fixVerify 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.
affects: All versions
gotchaImage 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.fixEnsure all images conform to the specified formats, size, and dimension limits before sending them for analysis. Resize or reformat as necessary.
affects: All versions
gotchaFor 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.fixFor document processing, switch to Azure Document Intelligence. For general image OCR, use `VisualFeatures.READ` with `azure-ai-vision-imageanalysis`.
affects: All versions
deprecatedOlder 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.fixMigrate 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.
affects: Older Azure Computer Vision SDKs/APIs (not this library itself)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.ai.vision.imageanalysis'
The 'azure-ai-vision-imageanalysis' package is not installed in the Python environment.
fixInstall the package using 'pip install azure-ai-vision-imageanalysis'.
ModuleNotFoundError: No module named 'azure.ai'
The 'azure-ai' module is not installed or the script is running in an environment where it is not available.
fixInstall the required Azure AI package, such as 'pip install azure-ai-ml', and ensure the script runs in the correct environment.
ModuleNotFoundError: No module named 'azure'
The 'azure' module is not installed or the script is running in an environment where it is not available.
fixInstall the necessary Azure package, such as 'pip install azure-identity', and ensure the script runs in the correct environment.
HttpResponseError: Status code: 401 Reason: PermissionDenied Message: Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource.
The Azure Vision key or endpoint provided to the `ImageAnalysisClient` is incorrect, expired, or the resource is not in a region that supports the requested features.
fixVerify that the `VISION_KEY` and `VISION_ENDPOINT` (or directly provided values) exactly match the credentials from your Azure AI Vision resource in the Azure portal, and confirm the resource is in a supported region for the features you are using.
HttpResponseError: Status code: 400 Reason: Bad Request Message: The provided image url is not accessible.
The URL provided for image analysis is either malformed, not publicly accessible, or the service cannot reach it.
fixEnsure the image URL is valid, publicly accessible over HTTP/HTTPS, and that there are no network restrictions preventing Azure AI Vision from accessing it. If providing local files, they must be sent as binary data, not local paths.
Upgrade
Version history
1.0.0latest on PyPI · released Oct 16, 2024
Audit
Dependencies
azure-identityoptionalRequired for Azure Active Directory (Azure AD) authentication using DefaultAzureCredential.
azure-corerequiredProvides core functionalities like AzureKeyCredential and HTTP pipeline components for Azure SDKs.
aiohttpoptionalRequired for using the asynchronous ImageAnalysisClient (from azure.ai.vision.imageanalysis.aio).