Guide de démarrage rapide

Pour modérer du contenu avec Discuse, envoyez une requête POST à https://api.discuse.com/api/v2/check avec un en-tête X-API-Key et un corps JSON contenant le texte, les URL d’images ou les URL de fichiers que vous souhaitez analyser. La réponse fournit le détail par catégorie ainsi qu’un indicateur unique has_violations. Ce guide vous accompagne dans ce premier appel, le format de la réponse et la gestion de base des erreurs — comptez environ cinq minutes du début à la fin.

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

Un compte Discuse (inscription sur discuse.com)
Une clé API depuis votre tableau de bord
Un outil pour effectuer des requêtes HTTP (cURL, Postman ou le code de votre application)

Étape 1 : Obtenir votre clé API

Après votre inscription, accédez à votre tableau de bord et repérez la section des clés API. Cliquez sur "Create New Key" pour générer une nouvelle clé API. Conservez cette clé en lieu sûr : elle donne accès à votre compte et à votre quota d’utilisation.

Toutes les clés Discuse commencent par le préfixe disc_, par exemple :

disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345-_6789

Étape 2 : Effectuer votre premier appel API

Le moyen le plus simple de tester l’API consiste à envoyer une requête d’analyse de texte. Voici un exemple de base avec cURL :

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": "Hello, this is a test message to analyze!"
    }
  }'

Étape 3 : Comprendre la réponse

Une requête réussie renvoie une réponse JSON contenant les résultats de l’analyse :

{
  "has_violations": false,
  "cached": false,
  "results": {
    "hits": false,
    "sentiment": {
      "is_negative": false,
      "is_toxic": false,
      "score": 0.03,
      "toxic": 0.02,
      "profanity": 0.01,
      "threat": 0.00,
      "insult": 0.03,
      "hit": false
    },
    "spamfinder": {
      "label": "ham",
      "confidence": 0.08,
      "is_spam": false,
      "hit": false
    },
    "language": {
      "language": "en",
      "confidence": 0.98
    }
  },
  "usage": {
    "api_requests_used": 42,
    "api_requests_limit": 1000,
    "api_requests_remaining": 958
  }
}

processing_time_ms n’est inclus que lorsque la mesure du temps est activée dans les paramètres de votre projet, et message n’est défini que dans les réponses indiquant un dépassement de quota — ces deux champs sont donc absents de l’exemple ci-dessus.

Explication des champs de la réponse

Champ	Description
`has_violations`	Booléen : `true` si une vérification activée a signalé le contenu (reflète `results.hits`)
`cached`	Indique si ce résultat a été servi depuis le cache (compte tout de même comme une requête dans le quota)
`results.hits`	Indicateur global de détection sur l’ensemble des vérifications
`results.sentiment`	Scores de toxicité de 0.0 (sûr) à 1.0 (très toxique), ainsi que les indicateurs de décision `is_toxic`/`hit`
`results.spamfinder`	Verdict de spam : `label`, `confidence`, `is_spam` (brut) et `hit` (tenant compte du seuil)
`results.language`	Code de `language` détecté et `confidence`
`usage`	Nombre de requêtes API utilisées, limite et quota restant pour la période de facturation en cours

Étape 4 : Analyser une image

Pour vérifier si une image contient du contenu NSFW, incluez l’URL de l’image dans votre requête :

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": {
      "image_urls": ["https://example.com/image.jpg"]
    },
    "settings": {
      "check_images": true
    }
  }'

Étape 5 : Combiner plusieurs vérifications

Vous pouvez analyser du texte et des images ensemble dans une seule requête :

{
  "content": {
    "text": "Check out this amazing photo!",
    "image_urls": ["https://example.com/photo.jpg"]
  },
  "settings": {
    "check_sentiment": true,
    "check_spam": true,
    "check_images": true,
    "check_language": true
  }
}

Exemples d’intégration

JavaScript/Node.js

async function checkContent(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 }
    })
  });

  return response.json();
}

// Usage
const result = await checkContent('Hello world!');
if (result.has_violations) {
  console.log('Content flagged:', result.message);
}

Python

import requests
import os

def check_content(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}
        }
    )
    return response.json()

# Usage
result = check_content('Hello world!')
if result['has_violations']:
    print(f"Content flagged: {result['message']}")

La mise en cache est-elle décomptée de mon quota ?

Discuse met en cache les résultats pour un contenu identique pendant quelques minutes. Lorsqu’une réponse revient avec "cached": true, elle a été servie depuis le cache : elle est donc renvoyée plus rapidement et les vérifications ne sont pas relancées. La requête compte tout de même comme une requête API dans votre quota, mais vous n’êtes pas refacturé pour les analyses sous-jacentes facturées par fonctionnalité (image, antivirus). La mise en cache est surtout utile lorsque le même contenu est soumis à plusieurs reprises sur une courte période.

Comment gérer les erreurs ?

Une vérification réussie renvoie HTTP 200. Une clé invalide, une limite de débit atteinte ou une requête mal formée renvoie un statut non-2xx. Notez que l’épuisement du quota n’est pas une erreur HTTP : lorsque le quota de votre période de facturation est épuisé, l’API renvoie toujours 200 avec has_violations: false et un message expliquant que le quota a été dépassé — vérifiez les champs message et usage plutôt que de vous fier uniquement au code de statut.

try {
  const response = await fetch('https://api.discuse.com/api/v2/check', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': apiKey
    },
    body: JSON.stringify({ content: { text } })
  });

  if (!response.ok) {
    if (response.status === 401 || response.status === 403) {
      throw new Error('Invalid or unauthorized API key');
    } else if (response.status === 429) {
      throw new Error('Rate limit exceeded - slow down requests');
    }
    throw new Error(`API error: ${response.status}`);
  }

  const result = await response.json();

  // Quota exhaustion is returned as a 200 with a message, not an error status.
  if (result.message && result.usage && result.usage.api_requests_remaining === 0) {
    console.warn('Quota exceeded:', result.message);
  }

  return result;
} catch (error) {
  console.error('Content check failed:', error);
  throw error;
}

Prochaines étapes

Maintenant que vous avez effectué votre premier appel API, explorez ces ressources :

Authentification et clés API - Découvrez la gestion sécurisée des clés
Analyse de texte - Approfondissez la détection du sentiment et du spam
Détection NSFW des images - Protégez votre plateforme contre les images inappropriées
Configuration des seuils - Ajustez finement la sensibilité de détection