Azure AI Content Safety for Java: Setup, Usage & Best Practices

Azure AI Content Safety delivers machine learning-powered content moderation for text and images through a Java SDK. This skill automatically detects harmful content across four categories—hate speech, violence, sexual content, and self-harm—with multi-level severity scoring, enabling you to implement automated moderation policies without building custom classification models.

What This Skill Does

This SDK wraps Azure's Content Safety service, analyzing text and images for harmful content and returning severity scores (0-6) across four harm categories. Each category measures different types of harmful content: hate speech based on identity groups, violent imagery or language, sexual content, and self-harm references. The service supports both detection and prevention workflows through two client types: ContentSafetyClient for analyzing content, and BlocklistClient for managing custom term lists.

Text analysis processes strings and returns category-specific severity scores. You specify which categories to check and set output granularity to either 4 levels (0, 2, 4, 6) or 8 levels (0-7). Image analysis works similarly but only supports the 4-level scale. Custom blocklists supplement ML-based detection with exact-match term filtering—useful for domain-specific profanity, brand names, or industry jargon that general models might miss.

The detection workflow is synchronous: send content, receive results immediately. Blocklist management is asynchronous: creating blocklists and adding terms takes about 5 minutes to propagate across the service. Once active, blocklists return matched terms with their IDs, enabling you to track which specific words triggered moderation. You can halt analysis immediately upon blocklist hits or continue checking all categories for comprehensive reporting.

Getting Started

Add the SDK to your Maven pom.xml:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-contentsafety</artifactId>
    <version>1.1.0-beta.1</version>
</dependency>

Configure environment variables:

export CONTENT_SAFETY_ENDPOINT=https://<resource>.cognitiveservices.azure.com/
export CONTENT_SAFETY_KEY=<your-api-key>

Create clients with API key authentication:

import com.azure.ai.contentsafety.*;
import com.azure.core.credential.KeyCredential;

String endpoint = System.getenv("CONTENT_SAFETY_ENDPOINT");
String key = System.getenv("CONTENT_SAFETY_KEY");

ContentSafetyClient contentClient = new ContentSafetyClientBuilder()
    .credential(new KeyCredential(key))
    .endpoint(endpoint)
    .buildClient();

BlocklistClient blocklistClient = new BlocklistClientBuilder()
    .credential(new KeyCredential(key))
    .endpoint(endpoint)
    .buildClient();

For production, use DefaultAzureCredential to support managed identities.

Key Features

Multi-Category Detection: Simultaneously analyze text or images across hate, violence, sexual, and self-harm categories. Each category returns independent severity scores with confidence values.

Granular Severity Levels: Choose between 4-level (default: 0, 2, 4, 6) or 8-level (0-7) scoring for text. Higher granularity enables finer-grained moderation policies.

Custom Blocklists: Supplement ML detection with exact-match term lists. Create multiple blocklists for different contexts (general profanity, brand protection, domain-specific terms).

Blocklist Match Details: When terms match, the service returns the blocklist name, matched item ID, and the exact text that triggered the match—useful for audit trails and policy refinement.

Selective Category Analysis: Request only the categories you need to reduce latency and costs. If you only care about hate speech, skip violence and sexual categories.

Halt-on-Match Option: Configure blocklist analysis to stop immediately upon finding a match, or continue checking all categories for comprehensive reports.

Usage Examples

Basic Text Analysis: Detect harmful content with default settings:

import com.azure.ai.contentsafety.models.*;

AnalyzeTextResult result = contentClient.analyzeText(
    new AnalyzeTextOptions("Text to analyze for harmful content"));

for (TextCategoriesAnalysis category : result.getCategoriesAnalysis()) {
    System.out.printf("%s: severity %d%n",
        category.getCategory(), category.getSeverity());
}

Text Analysis with Specific Categories and 8 Levels:

AnalyzeTextOptions options = new AnalyzeTextOptions("Content to check")
    .setCategories(Arrays.asList(TextCategory.HATE, TextCategory.VIOLENCE))
    .setOutputType(AnalyzeTextOutputType.EIGHT_SEVERITY_LEVELS);

AnalyzeTextResult result = contentClient.analyzeText(options);
// Scores now range 0-7 instead of just 0, 2, 4, 6

Image Analysis from File:

import java.nio.file.Files;
import java.nio.file.Paths;
import com.azure.core.util.BinaryData;

byte[] imageBytes = Files.readAllBytes(Paths.get("image.jpg"));
ContentSafetyImageData imageData = new ContentSafetyImageData()
    .setContent(BinaryData.fromBytes(imageBytes));

AnalyzeImageResult result = contentClient.analyzeImage(
    new AnalyzeImageOptions(imageData));

for (ImageCategoriesAnalysis category : result.getCategoriesAnalysis()) {
    if (category.getSeverity() >= 4) {
        System.out.printf("WARNING: %s detected at severity %d%n",
            category.getCategory(), category.getSeverity());
    }
}

Create Blocklist and Add Terms:

// Create blocklist
Map<String, String> description = Map.of("description", "Profanity filter");
BinaryData resource = BinaryData.fromObject(description);

blocklistClient.createOrUpdateTextBlocklistWithResponse(
    "profanity-list", resource, new RequestOptions());

// Add blocked terms
List<TextBlocklistItem> items = Arrays.asList(
    new TextBlocklistItem("badword1").setDescription("Offensive term"),
    new TextBlocklistItem("badword2").setDescription("Slur")
);

AddOrUpdateTextBlocklistItemsResult result = blocklistClient.addOrUpdateBlocklistItems(
    "profanity-list",
    new AddOrUpdateTextBlocklistItemsOptions(items));

for (TextBlocklistItem item : result.getBlocklistItems()) {
    System.out.printf("Added: %s (ID: %s)%n", item.getText(), item.getBlocklistItemId());
}

Analyze with Blocklist:

AnalyzeTextOptions options = new AnalyzeTextOptions("Text with badword1 in it")
    .setBlocklistNames(Arrays.asList("profanity-list"))
    .setHaltOnBlocklistHit(true);

AnalyzeTextResult result = contentClient.analyzeText(options);

if (result.getBlocklistsMatch() != null) {
    for (TextBlocklistMatch match : result.getBlocklistsMatch()) {
        System.out.printf("Blocked by %s: item %s matched '%s'%n",
            match.getBlocklistName(),
            match.getBlocklistItemId(),
            match.getBlocklistItemText());
    }
}

Best Practices

Set Appropriate Severity Thresholds: Typical moderation blocks severity >= 4 for strict policies, >= 6 for lenient policies. Lower thresholds increase false positives; higher thresholds risk missing harmful content.

Use Blocklists for Domain-Specific Terms: ML models generalize well but may miss industry jargon, brand names, or community-specific slang. Blocklists fill these gaps.

Wait for Blocklist Propagation: Changes to blocklists take ~5 minutes to propagate. Don't expect immediate availability after creating or updating items.

Request Only Needed Categories: If you only moderate hate speech and violence, don't request sexual or self-harm categories. Reduces latency and API costs.

Cache Blocklist Results: If analyzing similar content repeatedly, cache blocklist results where appropriate to reduce API calls.

Log Analysis Results: Maintain audit logs of moderation decisions for compliance, debugging, and model improvement.

Handle Errors Gracefully: Catch HttpResponseException and implement retry logic for transient failures (429 rate limits, 503 service unavailable).

When to Use / When NOT to Use

Use this skill when:

• You need automated content moderation for user-generated content


• You're building social platforms, comment systems, or chat applications


• You need multi-category harm detection without training custom models


• You want to supplement ML models with custom blocklists


• You need audit trails of moderation decisions


• You're moderating both text and images


• Compliance requires automated harmful content detection

Avoid this skill when:

• You're moderating non-text, non-image content (use specialized services)


• You need real-time sub-100ms latency (API calls add overhead)


• Your content language isn't supported by Azure's models


• You require on-premise deployment without cloud dependencies


• You're working in Python or .NET (use language-specific SDKs)


• You need context-aware moderation beyond surface-level keyword/image matching

Related Skills

• azure-ai-contentsafety-py: Python version of this SDK
• azure-ai-textanalytics-py: Broader text analysis including sentiment
• azure-ai-vision-imageanalysis-java: General image analysis beyond safety

Source

Maintained by Microsoft. View on GitHub