{"id":6532,"library":"azure-ai-vision-imageanalysis","title":"Azure AI Vision Image Analysis Client Library","description":"The `azure-ai-vision-imageanalysis` library is Microsoft's client library for Python, providing AI algorithms to process images and extract visual features such as captions, text (OCR), and detected objects. It is currently at version 1.0.0 and follows the Azure SDK's typical release cadence, with continuous improvements and feature additions.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/vision/azure-ai-vision-imageanalysis","tags":["azure","ai","vision","image analysis","cloud","microsoft","ocr","computer vision"],"install":[{"cmd":"pip install azure-ai-vision-imageanalysis","lang":"bash","label":"Install stable version"},{"cmd":"pip install azure-identity","lang":"bash","label":"Install for Azure AD authentication"},{"cmd":"pip install aiohttp","lang":"bash","label":"Install for asynchronous client"}],"dependencies":[{"reason":"Required for Azure Active Directory (Azure AD) authentication using DefaultAzureCredential.","package":"azure-identity","optional":true},{"reason":"Provides core functionalities like AzureKeyCredential and HTTP pipeline components for Azure SDKs.","package":"azure-core","optional":false},{"reason":"Required for using the asynchronous ImageAnalysisClient (from azure.ai.vision.imageanalysis.aio).","package":"aiohttp","optional":true}],"imports":[{"symbol":"ImageAnalysisClient","correct":"from azure.ai.vision.imageanalysis import ImageAnalysisClient"},{"symbol":"VisualFeatures","correct":"from azure.ai.vision.imageanalysis.models import VisualFeatures"},{"note":"AzureKeyCredential is part of azure-core, not directly the imageanalysis library.","wrong":"from azure.ai.vision.imageanalysis import AzureKeyCredential","symbol":"AzureKeyCredential","correct":"from azure.core.credentials import AzureKeyCredential"},{"note":"DefaultAzureCredential is part of azure-identity, which needs to be installed separately.","wrong":"from azure.ai.vision.imageanalysis import DefaultAzureCredential","symbol":"DefaultAzureCredential","correct":"from azure.identity import DefaultAzureCredential"}],"quickstart":{"code":"import os\nfrom azure.ai.vision.imageanalysis import ImageAnalysisClient\nfrom azure.ai.vision.imageanalysis.models import VisualFeatures\nfrom azure.core.credentials import AzureKeyCredential\n\n# Set environment variables or replace with actual values\n# For authentication with AzureKeyCredential\nvision_endpoint = os.environ.get('VISION_ENDPOINT', 'YOUR_VISION_ENDPOINT')\nvision_key = os.environ.get('VISION_KEY', 'YOUR_VISION_KEY')\n\n# For authentication with DefaultAzureCredential (uncomment and configure if needed)\n# from azure.identity import DefaultAzureCredential\n# credential = DefaultAzureCredential()\n\n# Authenticate the client\n# Using AzureKeyCredential (most common for quickstarts)\ncredential = AzureKeyCredential(vision_key)\nclient = ImageAnalysisClient(endpoint=vision_endpoint, credential=credential)\n\n# Image to analyze\nimage_url = \"https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png\"\n\nprint(\"Analyzing image from URL...\")\n\n# Analyze the image for a caption\nresult = client.analyze_from_url(\n    image_url,\n    visual_features=[VisualFeatures.CAPTION, VisualFeatures.TAGS]\n)\n\nif result.caption is not None:\n    print(f\" Caption: '{result.caption.text}' (confidence: {result.caption.confidence:.2f})\")\n\nif result.tags is not None:\n    print(\" Tags:\")\n    for tag in result.tags.list:\n        print(f\"   '{tag.name}' (confidence: {tag.confidence:.2f})\")\n","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":"<1.0.0-beta.1"},{"fix":"Always pass `endpoint=os.environ.get('VISION_ENDPOINT')` and `credential=AzureKeyCredential(os.environ.get('VISION_KEY'))` (or `DefaultAzureCredential()`) to the `ImageAnalysisClient` constructor.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all images conform to the specified formats, size, and dimension limits before sending them for analysis. Resize or reformat as necessary.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For document processing, switch to Azure Document Intelligence. For general image OCR, use `VisualFeatures.READ` with `azure-ai-vision-imageanalysis`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"Older Azure Computer Vision SDKs/APIs (not this library itself)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the package using 'pip install azure-ai-vision-imageanalysis'.","cause":"The 'azure-ai-vision-imageanalysis' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'azure.ai.vision.imageanalysis'"},{"fix":"Install the required Azure AI package, such as 'pip install azure-ai-ml', and ensure the script runs in the correct environment.","cause":"The 'azure-ai' module is not installed or the script is running in an environment where it is not available.","error":"ModuleNotFoundError: No module named 'azure.ai'"},{"fix":"Install the necessary Azure package, such as 'pip install azure-identity', and ensure the script runs in the correct environment.","cause":"The 'azure' module is not installed or the script is running in an environment where it is not available.","error":"ModuleNotFoundError: No module named 'azure'"},{"fix":"Verify 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.","cause":"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.","error":"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."},{"fix":"Ensure 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.","cause":"The URL provided for image analysis is either malformed, not publicly accessible, or the service cannot reach it.","error":"HttpResponseError: Status code: 400 Reason: Bad Request Message: The provided image url is not accessible."}]}