Análise de texto: sentimento, spam e idioma em uma única chamada

A análise de texto da Discuse avalia uma mensagem quanto a toxicidade, spam e idioma em uma única solicitação POST https://api.discuse.com/api/v2/check. Envie seu texto em content.text, autentique-se com o cabeçalho X-API-Key e leia os resultados de cada verificação em results.

O que o endpoint de texto verifica?

Uma chamada para /api/v2/check pode executar três verificações de texto ao mesmo tempo:

Sentimento: pontuação de toxicidade, palavrões, ameaça e insulto, além de um veredito negativo/tóxico.
Spam: spam promocional, golpes e texto gerado por bots, retornado como um label junto com uma pontuação de confiança.
Idioma: o código do idioma detectado, com aplicação opcional em relação a um idioma esperado.

Cada verificação é executada apenas quando habilitada, seja nas configurações do seu projeto ou por meio do objeto settings por solicitação.

Como chamo o endpoint de texto?

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 aceita até 10.000 caracteres. A chave de API pode ser enviada no cabeçalho X-API-Key ou como api_key no corpo da solicitação.

Resposta

{
  "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 espelha results.hits: é true quando qualquer verificação habilitada aciona sua flag hit. processing_time_ms só aparece quando a medição de tempo está habilitada nas configurações do seu projeto.

Análise de sentimento

A verificação de sentimento retorna tanto um veredito quanto pontuações por dimensão, de 0.0 a 1.0.

Campo	Tipo	Significado
`is_negative`	bool	A mensagem soa negativa
`is_toxic`	bool	A mensagem ultrapassa o limite de toxicidade
`score`	number	Pontuação geral de sentimento/severidade
`toxicity`	number	Confiança de toxicidade (0.0–1.0)
`toxic`	number	Confiança de toxicidade (alias legado de `toxicity`)
`profanity`	number	Confiança de linguagem explícita
`threat`	number	Confiança de ameaça de dano
`insult`	number	Confiança de ataque pessoal
`hit`	bool	Verdadeiro quando a mensagem viola os limites de sentimento
`message`	string	Explicação opcional

Como interpreto uma pontuação de sentimento?

Uma pontuação representa a confiança do modelo de que a dimensão se aplica:

0.0 – 0.3: baixa, geralmente segura.
0.3 – 0.6: moderada, pode justificar revisão.
0.6 – 0.8: alta, provavelmente problemática.
0.8 – 1.0: muito alta, quase certamente em violação.

Exemplo: conteúdo tóxico

Solicitação:

{
  "content": {
    "text": "You're the worst person I've ever met. I hate everything about you."
  },
  "settings": { "check_sentiment": true }
}

Resposta:

{
  "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
    }
  }
}

Detecção de spam

A verificação de spam classifica o texto e retorna um único label com uma pontuação de confiança. Ela identifica os padrões que escapam de listas de bloqueio por palavras-chave: spam promocional, golpes e phishing, e texto gerado por bots.

Exemplo: conteúdo de spam

Solicitação:

{
  "content": {
    "text": "CONGRATULATIONS! You've won $10,000! Click here to claim: www.fake-prize.com"
  },
  "settings": { "check_spam": true }
}

Resposta:

{
  "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 é o veredito bruto do modelo (o modelo classificou o texto como spam). hit é a decisão consciente do limite: é true apenas quando is_spam é true e confidence ultrapassa o limite de spam do seu projeto. Baseie a moderação em hit, não em is_spam. Consulte o guia Detecção de spam para mais detalhes.

Detecção de idioma

Defina check_language para detectar o código do idioma de content.text. O resultado fica em results.language.language (por exemplo, "en", "fr", "es").

Solicitação:

{
  "content": { "text": "Bonjour, comment allez-vous aujourd'hui?" },
  "settings": { "check_language": true }
}

Resposta:

{
  "results": {
    "language": {
      "language": "fr",
      "confidence": 0.99,
      "hit": false
    }
  }
}

Para sinalizar conteúdo que não esteja no idioma esperado, defina expected_language. Quando o idioma detectado é diferente, language.hit é true e expected/detected são preenchidos:

{
  "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
    }
  }
}

Consulte Detecção de idioma para ver a lista completa de idiomas e os padrões de aplicação.

Quais verificações posso alternar?

O objeto opcional settings substitui os padrões do seu projeto para uma única solicitação. As opções relevantes para texto são:

Configuração	Tipo	Efeito
`check_sentiment`	bool	Executa análise de sentimento
`check_spam`	bool	Executa detecção de spam
`check_language`	bool	Executa detecção de idioma
`check_badwords`	bool	Executa a lista de bloqueio de badwords
`expected_language`	string	Código de idioma a aplicar (ex.: `"en"`)

{
  "content": { "text": "Your message here" },
  "settings": {
    "check_sentiment": true,
    "check_spam": true,
    "check_language": true,
    "expected_language": "en"
  }
}

Limites de uso

Detecção de sentimento, spam e idioma consomem a cota de análise de sentimento por plano:

Plano	Análises de sentimento/mês
Basic	1,000
Gold	5,000
Platinum	15,000
Ultimate	30,000

Respostas em cache não contam para a sua cota. O objeto usage em cada resposta informa api_requests_used, api_requests_limit e api_requests_remaining.

Boas práticas

Defina limites por plataforma

Aplique pontos de corte de sentimento diferentes para públicos diferentes:

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 }
};

Leve o contexto em conta

Conteúdo clínico, jornalístico e de ficção pode acionar pontuações de toxicidade e palavrões de forma legítima. Combine a pontuação automatizada com revisão humana para casos limítrofes:

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);
}

Exemplos de integração

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

Pronto para implementar análise de texto? Consulte o Guia de início rápido para uma configuração passo a passo.

Análise de texto: sentimento, spam e idioma em uma única chamada

O que o endpoint de texto verifica?

Como chamo o endpoint de texto?

Resposta

Análise de sentimento

Como interpreto uma pontuação de sentimento?

Exemplo: conteúdo tóxico

Detecção de spam

Exemplo: conteúdo de spam

Detecção de idioma

Quais verificações posso alternar?

Limites de uso

Boas práticas

Defina limites por plataforma

Leve o contexto em conta

Exemplos de integração

JavaScript

Python

Artigos relacionados

Detecção de NSFW em imagens

Detecção de spam

Verificação antivírus de arquivos