Content moderation with Python

Prerequisites

You'll need an API key to use the Moderation API. To get one, you'll need to create a project.

Create a project

1. Install the SDK

pip install moderation_api

uv add moderation_api

poetry add moderation_api

Requires Python 3.10 or higher.

2. Submit content

Grab the API key from your project and begin submitting text, images, or other media to your project for moderation.

import os
from moderation_api import ModerationAPI

# Initialize the client with your secret key
client = ModerationAPI(secret_key=os.environ["MODAPI_SECRET_KEY"])

# Submit text for moderation
response = client.content.submit(
    content={
        "type": "text",
        "text": "Hello world!"
    },
    content_id="message-123",
    author_id="user-123",
    conversation_id="room-456",
    metadata={
        "custom_field": "value"
    }
)

# Check if content was flagged
if response.evaluation.flagged:
    print("Content was flagged")

# Act on the recommendation
if response.recommendation.action == "allow":
    print("Text content is safe.")
    # Save to database or proceed...
elif response.recommendation.action == "review":
    print("Text content needs review")
    # Send to review queue
elif response.recommendation.action == "reject":
    print("Text content rejected")
    # Block the content, show an error, etc...

import os
from moderation_api import ModerationAPI

# Initialize the client with your secret key
client = ModerationAPI(secret_key=os.environ["MODAPI_SECRET_KEY"])

# Submit image for moderation
response = client.content.submit(
    content={
        "type": "image",
        "url": "https://example.com/image.jpg"
    },
    content_id="image-456",
    author_id="user-123",
    conversation_id="room-456",
    metadata={
        "custom_field": "value"
    }
)

# Check if content was flagged
if response.evaluation.flagged:
    print("Image was flagged")

# Act on the recommendation
if response.recommendation.action == "allow":
    print("Image is safe.")
    # Save to database or proceed...
elif response.recommendation.action == "review":
    print("Image needs review")
    # Send to review queue
elif response.recommendation.action == "reject":
    print("Image rejected")
    # Block or require review

import os
from moderation_api import ModerationAPI

# Initialize the client with your secret key
client = ModerationAPI(secret_key=os.environ["MODAPI_SECRET_KEY"])

# Submit object for moderation
response = client.content.submit(
    content={
        "type": "object",
        "data": {
            "name": {
                "type": "text",
                "text": "John Doe"
            },
            "email": {
                "type": "text",
                "text": "john.doe@example.com"
            },
            "picture": {
                "type": "image",
                "url": "https://example.com/image.jpg"
            }
        }
    },
    content_id="post-789",
    author_id="user-123",
    conversation_id="room-456",
    metadata={
        "custom_field": "value"
    }
)

# Check if content was flagged
if response.evaluation.flagged:
    print("Object was flagged")

# Act on the recommendation
if response.recommendation.action == "allow":
    print("Object is safe.")
    # Save to database or proceed...
elif response.recommendation.action == "review":
    print("Object needs review")
    # Send to review queue
elif response.recommendation.action == "reject":
    print("Object rejected")
    # Block or require review

3. Handle errors

The SDK raises specific exception types for different error scenarios:

import os
from moderation_api import ModerationAPI, errors

client = ModerationAPI(secret_key=os.environ["MODAPI_SECRET_KEY"])

try:
    response = client.content.submit(
        content={
            "type": "text",
            "text": "Hello world!"
        }
    )

    print(f"Recommendation: {response.recommendation.action}")

except errors.RateLimitError as e:
    print(f"Rate limit exceeded: {e.message}")
except errors.ModerationAPIError as e:
    print(f"API error {e.status_code}: {e.message}")
except Exception as e:  # network errors, for example a timeout
    print(f"Request failed: {e}")

4. Use async

Every method has an async version with the suffix _async:

import asyncio
import os
from moderation_api import ModerationAPI

async def main():
    async with ModerationAPI(secret_key=os.environ["MODAPI_SECRET_KEY"]) as client:
        response = await client.content.submit_async(
            content={
                "type": "text",
                "text": "Hello world!"
            }
        )
        print(response.recommendation.action)

asyncio.run(main())

To retry failed requests, pass retry_config when you create the client, or retries for one request. You can also set timeout_ms on the client or on one request.

Dry-run mode: If you want to analyze production data but don't want to block content, enable "dry-run" in your project settings.

With dry-run enabled, the API still analyzes content but it always returns flagged: false - yet content still shows in the review queue. This way you can implement your moderation workflows and start testing your project configuration without actually blocking content.

3. Review flagged content (optional)

If the AI flags the content, it will appear in the Review inbox. Head to the review queue to validate that the content is submitted correctly.

Review queue for reviewing and improving automated moderation

You can use review queues to implement moderation workflows or simply check how the AI is performing.

All Done!

Congratulations! You've run your first moderation checks. Here are a few next steps:

Continue tweaking your project settings and models to find the best moderation outcomes.
Add custom Guidelines to a channel for rules specific to your platform.
Explore advanced features like context-aware moderation.
If you have questions, reach out to our support team.

We love hearing from you—please share how you're using the service and let us know if you have suggestions or need help. Happy moderating!

Documentation

AI agents

Learn

Migrations

Resources

Content moderation with Python

Prerequisites

1. Install the SDK

2. Submit content

3. Handle errors

4. Use async

3. Review flagged content (optional)

All Done!

​Prerequisites

​1. Install the SDK

​2. Submit content

​3. Handle errors

​4. Use async

​3. Review flagged content (optional)

​All Done!

Prerequisites

1. Install the SDK

2. Submit content

3. Handle errors

4. Use async

3. Review flagged content (optional)

All Done!