Краткое руководство по началу работы

Чтобы модерировать контент с помощью Discuse, отправьте POST на https://api.discuse.com/api/v2/check с заголовком X-API-Key и JSON-телом, содержащим текст, URL изображений или URL файлов, которые нужно проверить. В ответе возвращается разбивка по категориям и единый флаг has_violations. В этом руководстве мы разберём первый вызов, формат ответа и базовую обработку ошибок — всё это займёт около пяти минут.

Требования

Перед началом убедитесь, что у вас есть:

Учётная запись Discuse (зарегистрируйтесь на discuse.com)
API-ключ из вашей панели управления
Инструмент для выполнения HTTP-запросов (cURL, Postman или код вашего приложения)

Шаг 1: Получите API-ключ

После регистрации перейдите в панель управления и найдите раздел API-ключей. Нажмите "Create New Key", чтобы сгенерировать новый API-ключ. Храните этот ключ в безопасности - он предоставляет доступ к вашей учётной записи и квоте использования.

Каждый ключ Discuse начинается с префикса disc_, например:

disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345-_6789

Шаг 2: Выполните первый вызов API

Самый простой способ проверить API — отправить запрос на анализ текста. Вот базовый пример с использованием 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!"
    }
  }'

Шаг 3: Разберитесь с ответом

При успешном запросе возвращается JSON-ответ с результатами анализа:

{
  "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 включается только тогда, когда в настройках проекта включено измерение времени, а message задаётся только в ответах о превышении квоты — поэтому оба поля отсутствуют в примере выше.

Поля ответа

Поле	Описание
`has_violations`	Логическое значение: `true`, если любая включённая проверка отметила контент (дублирует `results.hits`)
`cached`	Был ли этот результат получен из кэша (всё равно засчитывается как один запрос в квоту)
`results.hits`	Общий флаг срабатывания по всем проверкам
`results.sentiment`	Оценки токсичности от 0.0 (безопасно) до 1.0 (крайне токсично), а также флаги решений `is_toxic`/`hit`
`results.spamfinder`	Вердикт по спаму: `label`, `confidence`, `is_spam` (сырое значение) и `hit` (с учётом порога)
`results.language`	Обнаруженный код `language` и `confidence`
`usage`	Количество ваших API-запросов, лимит и оставшаяся квота за текущий расчётный период

Шаг 4: Проанализируйте изображение

Чтобы проверить изображение на NSFW-контент, включите URL изображения в запрос:

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

Шаг 5: Объедините несколько проверок

Вы можете анализировать текст и изображения вместе в одном запросе:

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

Примеры интеграции

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']}")

Учитывается ли кэширование в моей квоте?

Discuse кэширует результаты для одинакового контента на несколько минут. Если в ответе приходит "cached": true, значит он был отдан из кэша, поэтому возвращается быстрее и проверки не запускаются повторно. Запрос всё равно засчитывается как один API-запрос в вашей квоте, но вам не начисляется повторная плата за базовые проверки по отдельным функциям (изображение, антивирус). Кэширование особенно полезно, когда один и тот же контент многократно отправляется в течение короткого промежутка времени.

Как обрабатывать ошибки?

Успешная проверка возвращает HTTP 200. Неверный ключ, превышение лимита частоты запросов или некорректно сформированный запрос возвращают статус не из диапазона 2xx. Обратите внимание, что исчерпание квоты не является HTTP-ошибкой: когда квота за расчётный период израсходована, API всё равно возвращает 200 с has_violations: false и message, объясняющим, что квота превышена — проверяйте поля message и usage, а не полагайтесь только на код статуса.

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

Что дальше

Теперь, когда вы выполнили первый вызов API, изучите эти материалы:

Аутентификация и API-ключи - Узнайте о безопасном управлении ключами
Анализ текста - Подробный разбор анализа тональности и обнаружения спама
Обнаружение NSFW на изображениях - Защитите свою платформу от неприемлемых изображений
Настройка пороговых значений - Точно настройте чувствительность обнаружения