Text classification is a cornerstone of modern applications. Whether you’re building a chat system, social platform, or customer support tool, you need reliable ways to detect spam, insults, toxic messages, and irrelevant content. Without automation, content moderation becomes a bottleneck and significantly slows down user experience.

The Kolas.Ai Clean Talk API provides developers with a ready-to-use spam detection API that classifies messages into categories like Neutral, Spam, Insult, and more. It supports multiple languages (English, Russian, Ukrainian) and can be extended to new languages on demand.

To make integration seamless, we’ve released the official Python client on PyPI. This article will guide you through installation, authentication, and message classification—covering both synchronous (real-time) and asynchronous (batch/webhook) workflows.

Why Use Kolas.Ai for Python Text Classification?

  • Automatic moderation: Detect spam, insults, and toxic content in real time.
  • Multilingual support: English, Russian, Ukrainian, with more available upon request.
  • High accuracy: Predictions include probability scores for confidence tracking.
  • Flexible integration: Real-time predictions via sync requests or scalable async processing via webhooks.
  • Developer-friendly: Based on OpenAPI 3.1 for easy adoption into Python projects.

If you’re looking for a content moderation solution in Python, this client provides a simple and production-ready path.

1. Installing the Python Client

The client is published on PyPi as clean-talk-client:

pip install clean-talk-client

Links:

2. Configuring Your Kolas.Ai Project

To use the API, you’ll need to create a project on the Kolas.Ai platform:

  1. Register a new account.
  2. Create a Clean Talk project.
  3. Configure your datasets..
  4. (Optional) Set up a webhook for asynchronous predictions.
  5. Generate OAuth2 credentials (client ID and client secret).

3. Authentication via OAuth2

The API uses the OAuth2 client credentials flow. The Python client makes this simple:

from clean_talk_client.kolas_ai_oauth_client import KolasAiOAuthClient

YOUR_CLIENT_ID = ''       # Replace with your client ID
YOUR_CLIENT_SECRET = ''   # Replace with your client secret

oauth_client = KolasAiOAuthClient()
auth_result = oauth_client.auth(YOUR_CLIENT_ID, YOUR_CLIENT_SECRET)

auth_result contains:

  • access_token — used in API calls
  • expires_in — token lifetime

You should refresh the token once it expires.

4. Real-Time Spam Detection (Synchronous Requests)

For chat systems, gaming platforms, or any service that requires instant filtering, synchronous classification is the right choice:

from clean_talk_client.clean_talk_prediction_client import CleanTalkPredictionClient
from clean_talk_client.message import Message
from clean_talk_client.predict_request import PredictRequest

YOUR_PROJECT_ID = '11'  # Replace with your project ID

client = CleanTalkPredictionClient(auth_result.access_token)
request = PredictRequest(
    YOUR_PROJECT_ID,
    [
        Message('11177c92-1266-4817-ace5-cda430481111', 'Hello world!'),
        Message('22277c92-1266-4817-ace5-cda430482222', 'Buy cheap products now!'),
    ]
)

response = client.predict(request)
for prediction in response.get_predictions():
    print("MessageId:", prediction.message_id)
    print("Message:", prediction.message)
    print("Prediction:", prediction.prediction)
    print("Probability:", prediction.probability)
    print("Categories:", ", ".join(prediction.categories))

Example output:

MessageId: 11177c92-1266-4817-ace5-cda430481111
Message: Hello world!
Prediction: Neutral
Probability: 0.9036
Categories: Insult, Neutral, Spam

MessageId: 22277c92-1266-4817-ace5-cda430482222
Message: Buy cheap products now!
Prediction: Spam
Probability: 0.9912
Categories: Insult, Neutral, Spam

5. Asynchronous Message Classification

For large-scale systems (social networks, forums, marketplaces), asynchronous classification is more efficient. Messages are submitted, and results are delivered via a webhook:

client = CleanTalkPredictionClient(auth_result.access_token)
request = PredictRequest(
    YOUR_PROJECT_ID,
    [Message('33377c92-1266-4817-ace5-cda430483333', 'This is an async test')]
)

client.async_predict(request)

The API sends predictions back to your webhook in JSON format.

6. Practical Use Cases

  • Python chatbots → filter toxic and spam messages automatically.
  • Gaming platforms → moderate in-game chat to prevent abuse.
  • Social media & forums → real-time spam detection to maintain community quality.
  • Customer support → automatically classify requests into neutral vs offensive complaints.
  • Email security → use the spam detection API to block junk emails.

7. Key Benefits at a Glance

  • Python text classification API
  • Spam detection with high accuracy
  • Automatic moderation for chat, games, and social media
  • Scalable, production-ready Python client
  • Multilingual NLP out of the box

Conclusion

If you’re building an application that relies on user-generated content, integrating automatic moderation is essential. The Kolas.Ai Clean Talk Python client provides an out-of-the-box solution for text classification, spam detection, and toxic content filtering.

With just a few lines of Python, you can add powerful moderation features to your platform—whether you need real-time filtering or batch classification at scale.

👉 Try it today: clean-talk-client on PyPI
👉 Learn more: Kolas.Ai Platform