Azure AI Contentsafety Py

1---
2name: azure-ai-contentsafety-py
3description: |
4  Azure AI Content Safety SDK for Python. Use for detecting harmful content in text and images with multi-severity classification.
5  Triggers: "azure-ai-contentsafety", "ContentSafetyClient", "content moderation", "harmful content", "text analysis", "image analysis".
6package: azure-ai-contentsafety
7---
8 
9# Azure AI Content Safety SDK for Python
10 
11Detect harmful user-generated and AI-generated content in applications.
12 
13## Installation
14 
15```bash
16pip install azure-ai-contentsafety
17```
18 
19## Environment Variables
20 
21```bash
22CONTENT_SAFETY_ENDPOINT=https://<resource>.cognitiveservices.azure.com
23CONTENT_SAFETY_KEY=<your-api-key>
24```
25 
26## Authentication
27 
28### API Key
29 
30```python
31from azure.ai.contentsafety import ContentSafetyClient
32from azure.core.credentials import AzureKeyCredential
33import os
34 
35client = ContentSafetyClient(
36    endpoint=os.environ["CONTENT_SAFETY_ENDPOINT"],
37    credential=AzureKeyCredential(os.environ["CONTENT_SAFETY_KEY"])
38)
39```
40 
41### Entra ID
42 
43```python
44from azure.ai.contentsafety import ContentSafetyClient
45from azure.identity import DefaultAzureCredential
46 
47client = ContentSafetyClient(
48    endpoint=os.environ["CONTENT_SAFETY_ENDPOINT"],
49    credential=DefaultAzureCredential()
50)
51```
52 
53## Analyze Text
54 
55```python
56from azure.ai.contentsafety import ContentSafetyClient
57from azure.ai.contentsafety.models import AnalyzeTextOptions, TextCategory
58from azure.core.credentials import AzureKeyCredential
59 
60client = ContentSafetyClient(endpoint, AzureKeyCredential(key))
61 
62request = AnalyzeTextOptions(text="Your text content to analyze")
63response = client.analyze_text(request)
64 
65# Check each category
66for category in [TextCategory.HATE, TextCategory.SELF_HARM, 
67                 TextCategory.SEXUAL, TextCategory.VIOLENCE]:
68    result = next((r for r in response.categories_analysis 
69                   if r.category == category), None)
70    if result:
71        print(f"{category}: severity {result.severity}")
72```
73 
74## Analyze Image
75 
76```python
77from azure.ai.contentsafety import ContentSafetyClient
78from azure.ai.contentsafety.models import AnalyzeImageOptions, ImageData
79from azure.core.credentials import AzureKeyCredential
80import base64
81 
82client = ContentSafetyClient(endpoint, AzureKeyCredential(key))
83 
84# From file
85with open("image.jpg", "rb") as f:
86    image_data = base64.b64encode(f.read()).decode("utf-8")
87 
88request = AnalyzeImageOptions(
89    image=ImageData(content=image_data)
90)
91 
92response = client.analyze_image(request)
93 
94for result in response.categories_analysis:
95    print(f"{result.category}: severity {result.severity}")
96```
97 
98### Image from URL
99 
100```python
101from azure.ai.contentsafety.models import AnalyzeImageOptions, ImageData
102 
103request = AnalyzeImageOptions(
104    image=ImageData(blob_url="https://example.com/image.jpg")
105)
106 
107response = client.analyze_image(request)
108```
109 
110## Text Blocklist Management
111 
112### Create Blocklist
113 
114```python
115from azure.ai.contentsafety import BlocklistClient
116from azure.ai.contentsafety.models import TextBlocklist
117from azure.core.credentials import AzureKeyCredential
118 
119blocklist_client = BlocklistClient(endpoint, AzureKeyCredential(key))
120 
121blocklist = TextBlocklist(
122    blocklist_name="my-blocklist",
123    description="Custom terms to block"
124)
125 
126result = blocklist_client.create_or_update_text_blocklist(
127    blocklist_name="my-blocklist",
128    options=blocklist
129)
130```
131 
132### Add Block Items
133 
134```python
135from azure.ai.contentsafety.models import AddOrUpdateTextBlocklistItemsOptions, TextBlocklistItem
136 
137items = AddOrUpdateTextBlocklistItemsOptions(
138    blocklist_items=[
139        TextBlocklistItem(text="blocked-term-1"),
140        TextBlocklistItem(text="blocked-term-2")
141    ]
142)
143 
144result = blocklist_client.add_or_update_blocklist_items(
145    blocklist_name="my-blocklist",
146    options=items
147)
148```
149 
150### Analyze with Blocklist
151 
152```python
153from azure.ai.contentsafety.models import AnalyzeTextOptions
154 
155request = AnalyzeTextOptions(
156    text="Text containing blocked-term-1",
157    blocklist_names=["my-blocklist"],
158    halt_on_blocklist_hit=True
159)
160 
161response = client.analyze_text(request)
162 
163if response.blocklists_match:
164    for match in response.blocklists_match:
165        print(f"Blocked: {match.blocklist_item_text}")
166```
167 
168## Severity Levels
169 
170Text analysis returns 4 severity levels (0, 2, 4, 6) by default. For 8 levels (0-7):
171 
172```python
173from azure.ai.contentsafety.models import AnalyzeTextOptions, AnalyzeTextOutputType
174 
175request = AnalyzeTextOptions(
176    text="Your text",
177    output_type=AnalyzeTextOutputType.EIGHT_SEVERITY_LEVELS
178)
179```
180 
181## Harm Categories
182 
183| Category | Description |
184|----------|-------------|
185| `Hate` | Attacks based on identity (race, religion, gender, etc.) |
186| `Sexual` | Sexual content, relationships, anatomy |
187| `Violence` | Physical harm, weapons, injury |
188| `SelfHarm` | Self-injury, suicide, eating disorders |
189 
190## Severity Scale
191 
192| Level | Text Range | Image Range | Meaning |
193|-------|------------|-------------|---------|
194| 0 | Safe | Safe | No harmful content |
195| 2 | Low | Low | Mild references |
196| 4 | Medium | Medium | Moderate content |
197| 6 | High | High | Severe content |
198 
199## Client Types
200 
201| Client | Purpose |
202|--------|---------|
203| `ContentSafetyClient` | Analyze text and images |
204| `BlocklistClient` | Manage custom blocklists |
205 
206## Best Practices
207 
2081. **Use blocklists** for domain-specific terms
2092. **Set severity thresholds** appropriate for your use case
2103. **Handle multiple categories** — content can be harmful in multiple ways
2114. **Use halt_on_blocklist_hit** for immediate rejection
2125. **Log analysis results** for audit and improvement
2136. **Consider 8-severity mode** for finer-grained control
2147. **Pre-moderate AI outputs** before showing to users
215