Azure AI Content Safety Client Library for Python

Warnings

• breaking Public Preview SDKs (versions prior to 1.0.0) were deprecated by March 31, 2024. Applications using older versions must update to the Generally Available (GA) SDK (1.0.0 or later) as API names and return formats have changed significantly.
  Fix: Upgrade to `azure-ai-contentsafety==1.0.0` or later and update your code to match the GA API definitions and return formats. Refer to the official migration guides.
• deprecated All API versions of the Azure AI Content Safety service prior to '2024-09-01' (excluding specific preview versions like '2024-09-15-preview' and '2024-09-30-preview') are scheduled for deprecation by March 1st, 2025.
  Fix: Ensure your client is using an API version supported after March 1st, 2025. The Python SDK's default API version should be kept updated by upgrading the package.
• gotcha Authentication requires either an Azure API Key (via `AzureKeyCredential`) or an Azure Active Directory (Microsoft Entra ID) token credential (via `DefaultAzureCredential` from `azure-identity`). Incorrect endpoint, API key, or insufficient role assignments (e.g., 'Cognitive Services User' role) are common causes of authentication failures.
  Fix: Verify that `CONTENT_SAFETY_ENDPOINT` and `CONTENT_SAFETY_KEY` environment variables (or other credential sources) are correctly set and correspond to an active Content Safety resource. For Entra ID, ensure the service principal has the necessary 'Cognitive Services User' role. Install `azure-identity` for `DefaultAzureCredential`.
• gotcha The library provides two distinct client types: `ContentSafetyClient` for analyzing text and images, and `BlocklistClient` for managing custom blocklists. Ensure you are using the correct client for your intended operation.
  Fix: Instantiate `ContentSafetyClient` for content analysis and `BlocklistClient` for blocklist creation, update, and deletion. Do not attempt blocklist operations with the `ContentSafetyClient` and vice-versa.
• gotcha The Content Safety service has input limitations for text and images (e.g., maximum text length). Exceeding these limits or providing unsupported content types (e.g., non-image files to image analysis) will result in `HttpResponseError`.
  Fix: Consult the official 'Input requirements' documentation for the specific API you are using to ensure your content adheres to size, format, and language support guidelines before sending requests. Handle `HttpResponseError` gracefully to catch validation issues.

Install

• pip install azure-ai-contentsafety Install latest stable version

Imports

• ContentSafetyClient

  from azure.ai.contentsafety import ContentSafetyClient

• BlocklistClient

  from azure.ai.contentsafety import BlocklistClient

• AnalyzeTextOptions

  from azure.ai.contentsafety.models import AnalyzeTextOptions

• TextCategory

  from azure.ai.contentsafety.models import TextCategory

• AzureKeyCredential

  from azure.core.credentials import AzureKeyCredential

  Required for API key authentication.
• DefaultAzureCredential

  from azure.identity import DefaultAzureCredential

  Required for Azure Active Directory (Microsoft Entra ID) authentication. Install 'azure-identity' package.

Quickstart

This quickstart demonstrates how to initialize the `ContentSafetyClient` using an API key and analyze a piece of text for harmful content across different categories. Ensure you have your Azure Content Safety resource endpoint and API key configured as environment variables (`CONTENT_SAFETY_ENDPOINT` and `CONTENT_SAFETY_KEY`). The output will show the detected categories and their severity levels.

import os
from azure.ai.contentsafety import ContentSafetyClient
from azure.ai.contentsafety.models import AnalyzeTextOptions, TextCategory
from azure.core.credentials import AzureKeyCredential
from azure.core.exceptions import HttpResponseError

# Set your Azure Content Safety endpoint and key as environment variables
# e.g., export CONTENT_SAFETY_ENDPOINT="https://<your-resource-name>.cognitiveservices.azure.com/"
# e.g., export CONTENT_SAFETY_KEY="<your-api-key>"
endpoint = os.environ.get("CONTENT_SAFETY_ENDPOINT", "").strip()
key = os.environ.get("CONTENT_SAFETY_KEY", "").strip()

if not endpoint or not key:
    print("Please set the environment variables CONTENT_SAFETY_ENDPOINT and CONTENT_SAFETY_KEY.")
    exit(1)

# Create a Content Safety client
client = ContentSafetyClient(endpoint, AzureKeyCredential(key))

# Text to analyze
text_to_analyze = "I hate you. You are an idiot and I will harm you."

# Construct the analysis request
request = AnalyzeTextOptions(text=text_to_analyze)

try:
    response = client.analyze_text(request)
    print(f"Analyzing text: '{text_to_analyze}'")
    
    for category_result in response.categories_analysis:
        if category_result.severity is not None:
            print(f"  Category: {category_result.category}, Severity: {category_result.severity}")
        else:
            print(f"  Category: {category_result.category}, No severity detected.")

except HttpResponseError as e:
    print(f"Analyze text failed: {e.reason}")
    if e.error:
        print(f"Error code: {e.error.code}")
        print(f"Error message: {e.error.message}")
    raise

print("\nText analysis complete.")