Анализ текста: тональность, спам и язык одним запросом
Анализ текста Discuse оценивает сообщение на токсичность, спам и язык одним запросом POST https://api.discuse.com/api/v2/check. Передайте текст в content.text, выполните аутентификацию через заголовок X-API-Key и получите результаты по каждой проверке в results.
Что проверяет текстовый endpoint?
Один вызов /api/v2/check может выполнить сразу три текстовые проверки:
- Тональность: оценка токсичности, ненормативной лексики, угроз и оскорблений, а также вердикт о негативности/токсичности.
- Спам: рекламный спам, мошеннические сообщения и текст, сгенерированный ботами; возвращается как
labelвместе с оценкой уверенности. - Язык: определённый код языка с возможной проверкой на соответствие ожидаемому языку.
Каждая проверка выполняется только тогда, когда она включена — в настройках проекта или через объект settings в конкретном запросе.
Как вызвать текстовый endpoint?
curl -X POST https://api.discuse.com/api/v2/check \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"content": {
"text": "This is an example message to analyze"
},
"settings": {
"check_sentiment": true,
"check_spam": true,
"check_language": true
}
}'
content.text принимает до 10 000 символов. API-ключ можно передать в заголовке X-API-Key или как api_key в теле запроса.
Ответ
{
"has_violations": false,
"cached": false,
"message": "Content appears safe",
"results": {
"hits": false,
"sentiment": {
"hit": false,
"is_negative": false,
"is_toxic": false,
"score": 0.04,
"toxicity": 0.02,
"toxic": 0.02,
"profanity": 0.01,
"threat": 0.00,
"insult": 0.03
},
"spamfinder": {
"text": "This is an example message to analyze",
"label": "ham",
"confidence": 0.12,
"is_spam": false,
"hit": false
},
"language": {
"language": "en",
"confidence": 0.98,
"hit": false
}
},
"usage": {
"api_requests_used": 41,
"api_requests_limit": 5000,
"api_requests_remaining": 4959
}
}
has_violations повторяет results.hits: значение равно true, когда у любой включённой проверки срабатывает флаг hit. processing_time_ms присутствует только в том случае, если замер времени включён в настройках проекта.
Анализ тональности
Проверка тональности возвращает и вердикт, и оценки по отдельным параметрам в диапазоне от 0.0 до 1.0.
| Поле | Тип | Значение |
|---|---|---|
is_negative |
bool | Сообщение воспринимается как негативное |
is_toxic |
bool | Сообщение превышает порог токсичности |
score |
number | Общая оценка тональности/серьёзности |
toxicity |
number | Уверенность в токсичности (0.0–1.0) |
toxic |
number | Уверенность в токсичности (устаревший алиас toxicity) |
profanity |
number | Уверенность в наличии ненормативной лексики |
threat |
number | Уверенность в наличии угрозы причинения вреда |
insult |
number | Уверенность в наличии личного оскорбления |
hit |
bool | True, когда сообщение нарушает пороги тональности |
message |
string | Необязательное пояснение |
Как интерпретировать оценку тональности?
Оценка показывает, насколько модель уверена, что соответствующий параметр применим:
- 0.0 – 0.3: низкая, обычно безопасно.
- 0.3 – 0.6: умеренная, может потребоваться проверка.
- 0.6 – 0.8: высокая, вероятно проблемное содержание.
- 0.8 – 1.0: очень высокая, почти наверняка нарушение.
Пример: токсичный контент
Запрос:
{
"content": {
"text": "You're the worst person I've ever met. I hate everything about you."
},
"settings": { "check_sentiment": true }
}
Ответ:
{
"has_violations": true,
"results": {
"hits": true,
"sentiment": {
"hit": true,
"is_negative": true,
"is_toxic": true,
"score": 0.91,
"toxicity": 0.89,
"toxic": 0.89,
"profanity": 0.15,
"threat": 0.22,
"insult": 0.95
}
}
}
Обнаружение спама
Проверка спама классифицирует текст и возвращает один label с оценкой уверенности. Она выявляет шаблоны, которые обходят блок-листы по ключевым словам: рекламный спам, мошенничество и фишинг, а также текст, сгенерированный ботами.
Пример: спам-контент
Запрос:
{
"content": {
"text": "CONGRATULATIONS! You've won $10,000! Click here to claim: www.fake-prize.com"
},
"settings": { "check_spam": true }
}
Ответ:
{
"has_violations": true,
"results": {
"hits": true,
"spamfinder": {
"text": "CONGRATULATIONS! You've won $10,000! Click here to claim: www.fake-prize.com",
"label": "spam",
"confidence": 0.97,
"is_spam": true,
"hit": true
}
}
}
is_spam — это прямой вердикт модели (модель пометила текст как спам). hit — решение с учётом порога: оно равно true только тогда, когда is_spam истинно и confidence превышает порог спама вашего проекта. В модерации ориентируйтесь на hit, а не на is_spam. Подробности см. в руководстве Обнаружение спама.
Определение языка
Установите check_language, чтобы определить код языка для content.text. Результат находится в results.language.language (например, "en", "fr", "es").
Запрос:
{
"content": { "text": "Bonjour, comment allez-vous aujourd'hui?" },
"settings": { "check_language": true }
}
Ответ:
{
"results": {
"language": {
"language": "fr",
"confidence": 0.99,
"hit": false
}
}
}
Чтобы помечать контент, написанный не на ожидаемом языке, задайте expected_language. Когда определённый язык отличается, language.hit получает значение true, а поля expected/detected заполняются:
{
"content": { "text": "Hola, cómo estás?" },
"settings": { "check_language": true, "expected_language": "en" }
}
{
"results": {
"language": {
"language": "es",
"detected": "es",
"expected": "en",
"confidence": 0.95,
"hit": true
}
}
}
Полный список языков и схемы принудительной проверки см. в разделе Определение языка.
Какие проверки можно включать и отключать?
Необязательный объект settings переопределяет настройки проекта по умолчанию для одного запроса. Переключатели, относящиеся к тексту:
| Настройка | Тип | Эффект |
|---|---|---|
check_sentiment |
bool | Выполнить анализ тональности |
check_spam |
bool | Выполнить обнаружение спама |
check_language |
bool | Выполнить определение языка |
check_badwords |
bool | Запустить блок-лист запрещённых слов |
expected_language |
string | Код языка, который нужно требовать (например, "en") |
{
"content": { "text": "Your message here" },
"settings": {
"check_sentiment": true,
"check_spam": true,
"check_language": true,
"expected_language": "en"
}
}
Лимиты использования
Определение тональности, спама и языка расходует квоту анализа тональности, зависящую от тарифного плана:
| План | Анализов тональности в месяц |
|---|---|
| Basic | 1,000 |
| Gold | 5,000 |
| Platinum | 15,000 |
| Ultimate | 30,000 |
Кэшированные ответы не расходуют квоту. Объект usage в каждом ответе сообщает api_requests_used, api_requests_limit и api_requests_remaining.
Рекомендации
Настраивайте пороги под платформу
Используйте разные пороги тональности для разных аудиторий:
const THRESHOLDS = {
kids: { toxicity: 0.3, profanity: 0.2, threat: 0.2, insult: 0.3 },
general: { toxicity: 0.5, profanity: 0.5, threat: 0.4, insult: 0.5 },
adult: { toxicity: 0.7, profanity: 0.8, threat: 0.5, insult: 0.7 }
};
Учитывайте контекст
Медицинские, журналистские и художественные тексты могут обоснованно получать высокие оценки токсичности и ненормативной лексики. Для пограничных случаев сочетайте автоматическую оценку с ручной проверкой:
const sentiment = result.results.sentiment;
if (sentiment.toxicity > 0.9) {
await removeContent(contentId); // high confidence: auto-remove
} else if (sentiment.toxicity > 0.5) {
await queueForReview(contentId); // borderline: human review
} else {
await approveContent(contentId);
}
Примеры интеграции
JavaScript
async function analyzeText(text) {
const response = await fetch('https://api.discuse.com/api/v2/check', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': process.env.DISCUSE_API_KEY
},
body: JSON.stringify({
content: { text },
settings: { check_sentiment: true, check_spam: true, check_language: true }
})
});
return response.json();
}
const result = await analyzeText('Hello, how are you?');
console.log(result.has_violations); // false
Python
import os
import requests
def analyze_text(text):
response = requests.post(
'https://api.discuse.com/api/v2/check',
headers={
'Content-Type': 'application/json',
'X-API-Key': os.environ['DISCUSE_API_KEY']
},
json={
'content': {'text': text},
'settings': {
'check_sentiment': True,
'check_spam': True,
'check_language': True
}
}
)
return response.json()
result = analyze_text('Hello, how are you?')
print(result['has_violations']) # False
Готовы внедрить анализ текста? Пошаговую настройку см. в руководстве по быстрому старту.