Usernames & Images

Check usernames and profile images before you create or update a user.

Warning:

This endpoint usage will be counted towards your text and image moderation quota.

Overview

User profile moderation allows you to check both usernames and profile images using a single API endpoint and unified policy configuration. You can:

Moderate usernames using AI (LLM), custom blocklists, or pattern-based detection
Moderate profile images with the image engine and OCR
Combine multiple providers for layered protection
Configure once - the same policy handles both usernames and images

User profile policies vs. username policies

There are two kinds of policy for user profiles. Pick one based on what you need to check:

	User profile policy (`user_profile:default`)	Username policy (`username:<name>`)
Use it when	You want to check a username and a profile image together, with the same policy	You only check usernames and want the fastest, cheapest check
Checks	Username text and profile images	Username text only
API	Check with `entity_type: "stream:v1:user_profile"`	Labels with `content_type: "username"` and `policy: "username:<name>"`
Engines	AI text (LLM or NLP), blocklists, image engine, and OCR	A username-tuned classifier plus blocklists, which run first
Severity rules	Supported	Not supported: one action per label
Review queue	Flagged profiles appear as user profile items	No; results are returned inline

Configuring User Profile Moderation

Username and profile image moderation can operate in different modes depending on your configuration. You can combine multiple moderation providers (LLM, blocklists, OCR, etc.) for comprehensive protection.

Step 1: Configure Your Moderation Policy

Navigate to the Stream Dashboard
Go to Moderation → Policies
Select or create a policy for user profile moderation (e.g., User Profile)
Configure the providers you want to use

Username Moderation

Before creating or updating a user profile, you can check if the username complies with basic moderation rules to help maintain a safe environment for your users.

AI Text - Recommended

Most advanced detection using Large Language Models
Catches nuanced violations and creative circumvention
Out-of-the-box labels provided include PROFANITY, HATE_SPEECH, IMPERSONATION, SCAM, MISLEADING_IDENTITY

These labels cover the most common moderation scenarios and help you get started quickly. You can customize actions for each label or add your own.

AI Text (NLP)

With the NLP engine, usernames are classified against their own label set. The engine reads the whole string in context, so a term that is harmful on its own (such as "plug") isn't flagged when it's clearly part of something harmless (such as "spark_plug"). Usernames have no severity levels: set one action per label.

Label	Description
`BODY_SHAMING`	Mocks, degrades, or attacks physical appearance or weight.
`DRUG_EXPLICIT`	Promotes or references illegal drugs, narcotics, or drug dealing.
`EXTREMISM`	Promotes terrorist organizations, violent extremism, or radicalization.
`INSULT`	Direct, targeted profanity or degrading insults.
`LGBTQIAPLUS_PHOBIA`	Slurs, mockery, or hate speech aimed at the LGBTQIA+ community.
`MISOGYNY`	Hatred, prejudice, or harmful stereotypes about women.
`PII`	Sensitive personal information, such as a phone number, email address, physical address, or government ID. A plain first and last name is `PII_REAL_NAME` instead.
`PII_REAL_NAME`	A person's real first and last name. Username policies only.
`RACISM`	Racial slurs, stereotypes, or hate speech based on race or ethnicity.
`SEXUALLY_EXPLICIT`	Explicit sexual acts, crude anatomical references, or pornography.

Blocklists

Create custom blocklists in Moderation → Advanced Filters
Fast pattern matching for known bad words
Uses substring matching for usernames (e.g., blocking "bad" matches "baduser123")

Check Username

For a low-latency username check, call POST /api/v2/moderation/labels. content is required. Set content_type to username and policy to a key that starts with username: (for example username:default). Blocklists answer first. The response recommended_action is keep, flag, or remove.

const response = await client.moderation.labels({
  content: "username_to_check",
  content_type: "username",
  policy: "username:default",
});

if (response.recommended_action === "keep") {
  // Username is acceptable
}

The samples below are the general check path, for a full user-profile policy rather than the username fast path.

response = client.moderation.check(
    entity_type="stream:v1:user_profile",
    entity_id=user_id,
    entity_creator_id=user_id,
    moderation_payload=ModerationPayload(texts=["username_to_check"]),
    config_key="user_profile:default",
)

# Response will indicate if the username is acceptable
if response.recommended_action == "keep":
    # Username is acceptable, proceed with user creation/update
    pass
else:
    # Username violates moderation rules, ask user to choose a different name
    pass

Profile Image Moderation

You can moderate images using Stream's AI Image Moderation Engine. This helps detect inappropriate or harmful image content before it's published on your platform.

Check Profile Images

response = client.moderation.check(
    entity_type="stream:v1:user_profile",
    entity_id=user_id,
    entity_creator_id=user_id,
    moderation_payload=ModerationPayload(images=["https://example.com/profile.jpg"]),
    config_key="user_profile:default",
)

# Handle the moderation result
if response.recommended_action == "keep":
    # Image is safe to use as profile picture
    pass
else:
    # Image violates moderation rules
    pass

Dashboard Integration

When LLM or blocklists are configured for usernames, or when image moderation is enabled, flagged content appears in your moderation dashboard.