Analyse de texte : sentiment, spam et langue en un seul appel

L’analyse de texte Discuse évalue un message en matière de toxicité, de spam et de langue en une seule requête POST https://api.discuse.com/api/v2/check. Envoyez votre texte dans content.text, authentifiez-vous avec l’en-tête X-API-Key, puis consultez les résultats de chaque vérification sous results.

Que vérifie l’endpoint de texte ?

Un appel à /api/v2/check peut exécuter trois vérifications de texte à la fois :

• Sentiment : évaluation de la toxicité, des grossièretés, des menaces et des insultes, avec verdict négatif/toxique.
• Spam : spam promotionnel, escroqueries et texte généré par des bots, renvoyés sous forme de label avec un score de confiance.
• Langue : code de langue détecté, avec possibilité d’imposer une langue attendue.

Chaque vérification ne s’exécute que lorsqu’elle est activée, soit dans les paramètres de votre projet, soit via l’objet settings propre à la requête.

Comment appeler l’endpoint de texte ?

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 accepte jusqu’à 10 000 caractères. La clé API peut être envoyée dans l’en-tête X-API-Key ou comme api_key dans le corps de la requête.

Réponse

{
  "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 reflète results.hits : sa valeur est true dès qu’une vérification activée déclenche son indicateur hit. processing_time_ms n’est présent que lorsque la mesure du temps est activée dans les paramètres de votre projet.

Analyse du sentiment

La vérification du sentiment renvoie à la fois un verdict et des scores par dimension, de 0.0 à 1.0.

Champ	Type	Signification
is_negative	bool	Le message est perçu comme négatif
is_toxic	bool	Le message dépasse le seuil de toxicité
score	number	Score global de sentiment/gravité
toxicity	number	Confiance de toxicité (0.0–1.0)
toxic	number	Confiance de toxicité (ancien alias de toxicity)
profanity	number	Confiance liée au langage explicite
threat	number	Confiance liée à une menace de préjudice
insult	number	Confiance liée à une attaque personnelle
hit	bool	Vrai lorsque le message enfreint les seuils de sentiment
message	string	Explication facultative

Comment interpréter un score de sentiment ?

Un score correspond au niveau de confiance du modèle quant à l’applicabilité de la dimension :

• 0.0 – 0.3 : faible, généralement sûr.
• 0.3 – 0.6 : modéré, peut justifier une vérification.
• 0.6 – 0.8 : élevé, probablement problématique.
• 0.8 – 1.0 : très élevé, presque certainement en infraction.

Exemple : contenu toxique

Requête :

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

Réponse :

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

Détection du spam

La vérification du spam classe le texte et renvoie un unique label avec un score de confiance. Elle détecte les schémas qui échappent aux listes de blocage par mots-clés : spam promotionnel, escroqueries et hameçonnage, ainsi que texte généré par des bots.

Exemple : contenu spam

Requête :

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

Réponse :

{
  "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 est le verdict brut du modèle (le modèle a étiqueté le texte comme spam). hit est la décision tenant compte du seuil : sa valeur est true uniquement lorsque is_spam est vrai et que confidence dépasse le seuil de spam de votre projet. Basez la modération sur hit, et non sur is_spam. Consultez le guide Détection du spam pour plus de détails.

Détection de la langue

Définissez check_language pour détecter le code de langue de content.text. Le résultat se trouve dans results.language.language (par exemple "en", "fr", "es").

Requête :

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

Réponse :

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

Pour signaler le contenu qui n’est pas dans la langue attendue, définissez expected_language. Lorsque la langue détectée diffère, language.hit vaut true et expected/detected sont renseignés :

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

Consultez Détection de la langue pour obtenir la liste complète des langues et les modèles d’application.

Quelles vérifications puis-je activer ou désactiver ?

L’objet facultatif settings remplace les valeurs par défaut de votre projet pour une seule requête. Les options pertinentes pour le texte sont :

Paramètre	Type	Effet
check_sentiment	bool	Exécute l’analyse du sentiment
check_spam	bool	Exécute la détection du spam
check_language	bool	Exécute la détection de la langue
check_badwords	bool	Exécute la liste de blocage des mots interdits
expected_language	string	Code de langue à imposer (par ex. "en")

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

Limites d’utilisation

La détection du sentiment, du spam et de la langue consomme le quota d’analyse de sentiment propre à chaque offre :

Offre	Analyses de sentiment/mois
Basic	1,000
Gold	5,000
Platinum	15,000
Ultimate	30,000

Les réponses mises en cache ne sont pas décomptées de votre quota. L’objet usage présent dans chaque réponse indique api_requests_used, api_requests_limit et api_requests_remaining.

Bonnes pratiques

Définir des seuils par plateforme

Appliquez des seuils de sentiment différents selon les audiences :

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

Tenir compte du contexte

Les contenus cliniques, journalistiques et fictionnels peuvent légitimement déclencher des scores de toxicité et de grossièretés. Combinez l’évaluation automatisée avec une revue humaine pour les cas limites :

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

Exemples d’intégration

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

Prêt à mettre en œuvre l’analyse de texte ? Consultez le Guide de démarrage rapide pour une configuration étape par étape.