Guia de início rápido

Para moderar conteúdo com o Discuse, envie um POST para https://api.discuse.com/api/v2/check com um cabeçalho X-API-Key e um corpo JSON contendo o texto, URLs de imagens ou URLs de arquivos que você deseja verificar. A resposta retorna um detalhamento por categoria e um único sinalizador has_violations. Este guia mostra essa primeira chamada, o formato da resposta e o tratamento básico de erros — em cerca de cinco minutos, do início ao fim.

Pré-requisitos

Antes de começar, certifique-se de que você tem:

Uma conta Discuse (cadastre-se em discuse.com)
Uma chave de API do seu painel
Uma ferramenta para fazer requisições HTTP (cURL, Postman ou o código da sua aplicação)

Etapa 1: Obtenha sua chave de API

Depois de se cadastrar, acesse o painel e localize a seção de chaves de API. Clique em "Criar nova chave" para gerar uma nova chave de API. Mantenha essa chave segura — ela fornece acesso à sua conta e à sua cota de uso.

Toda chave Discuse começa com o prefixo disc_, por exemplo:

disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345-_6789

Etapa 2: Faça sua primeira chamada à API

A maneira mais simples de testar a API é com uma requisição de análise de texto. Veja um exemplo básico usando 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!"
    }
  }'

Etapa 3: Entenda a resposta

Uma requisição bem-sucedida retorna uma resposta JSON com os resultados da análise:

{
  "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 só é incluído quando a medição de tempo está ativada nas configurações do seu projeto, e message só é definido em respostas de cota excedida — por isso, ambos foram omitidos do exemplo acima.

Campos da resposta explicados

Field	Description
`has_violations`	Booleano: `true` se qualquer verificação habilitada sinalizou o conteúdo (espelha `results.hits`)
`cached`	Se este resultado foi servido a partir do cache (ainda conta como uma requisição na cota)
`results.hits`	Sinalizador geral de ocorrência em todas as verificações
`results.sentiment`	Pontuações de toxicidade de 0.0 (seguro) a 1.0 (altamente tóxico), além dos sinalizadores de decisão `is_toxic`/`hit`
`results.spamfinder`	Veredito de spam: `label`, `confidence`, `is_spam` (bruto) e `hit` (considerando o limite configurado)
`results.language`	Código de `language` detectado e `confidence`
`usage`	Contagem de requisições da sua API, limite e cota restante para o período de cobrança atual

Etapa 4: Analise uma imagem

Para verificar uma imagem em busca de conteúdo NSFW, inclua a URL da imagem na sua requisição:

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

Etapa 5: Combine várias verificações

Você pode analisar texto e imagens juntos em uma única requisição:

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

Exemplos de integração

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

O cache conta para a minha cota?

O Discuse armazena em cache os resultados de conteúdos idênticos por alguns minutos. Quando uma resposta vem com "cached": true, ela foi servida a partir do cache, portanto retorna mais rápido e evita executar novamente as verificações. A requisição ainda conta como uma requisição de API na sua cota, mas você não é cobrado novamente pelas varreduras subjacentes por recurso (imagem, antivírus). O cache ajuda principalmente quando o mesmo conteúdo é enviado repetidamente em um curto intervalo.

Como lidar com erros?

Uma verificação bem-sucedida retorna HTTP 200. Uma chave inválida, limite de taxa atingido ou requisição malformada retorna um status não 2xx. Observe que o esgotamento da cota não é um erro HTTP: quando a cota do seu período de cobrança é totalmente usada, a API ainda retorna 200 com has_violations: false e uma message explicando que a cota foi excedida — verifique os campos message e usage em vez de depender de um código de status.

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

Próximos passos

Agora que você fez sua primeira chamada à API, explore estes recursos:

Autenticação e chaves de API - Saiba mais sobre o gerenciamento seguro de chaves
Análise de texto - Aprofunde-se na detecção de sentimento e spam
Detecção de NSFW em imagens - Proteja sua plataforma contra imagens inadequadas
Configuração de limites - Ajuste a sensibilidade da detecção