Guía de inicio rápido

Para moderar contenido con Discuse, envía una solicitud POST a https://api.discuse.com/api/v2/check con un encabezado X-API-Key y un cuerpo JSON que contenga el texto, las URL de imágenes o las URL de archivos que quieras analizar. La respuesta devuelve un desglose por categoría y un único indicador has_violations. Esta guía te acompaña en esa primera llamada, el formato de la respuesta y el manejo básico de errores, todo de principio a fin en unos cinco minutos.

Requisitos previos

Antes de empezar, asegúrate de tener:

1. Una cuenta de Discuse (regístrate en discuse.com)
2. Una clave API desde tu panel
3. Una herramienta para realizar solicitudes HTTP (cURL, Postman o el código de tu aplicación)

Paso 1: Obtén tu clave API

Después de registrarte, ve a tu panel y busca la sección de claves API. Haz clic en "Crear nueva clave" para generar una nueva clave API. Mantén esta clave segura: proporciona acceso a tu cuenta y a tu cuota de uso.

Todas las claves de Discuse empiezan con el prefijo disc_, por ejemplo:

disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345-_6789

Paso 2: Haz tu primera llamada a la API

La forma más sencilla de probar la API es con una solicitud de análisis de texto. Aquí tienes un ejemplo 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!"
    }
  }'

Paso 3: Entiende la respuesta

Una solicitud correcta devuelve una respuesta JSON con los resultados del análisis:

{
  "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 solo se incluye cuando la medición de tiempo está activada en la configuración de tu proyecto, y message solo se establece en respuestas por cuota excedida; por eso ambos se omiten en el ejemplo anterior.

Explicación de los campos de la respuesta

Campo	Descripción
has_violations	Booleano: true si alguna comprobación habilitada marcó el contenido (refleja results.hits)
cached	Indica si este resultado se sirvió desde la caché (aun así cuenta como una solicitud contra la cuota)
results.hits	Indicador global de coincidencia en todas las comprobaciones
results.sentiment	Puntuaciones de toxicidad de 0.0 (seguro) a 1.0 (altamente tóxico), además de los indicadores de decisión is_toxic/hit
results.spamfinder	Veredicto de spam: label, confidence, is_spam (sin procesar) y hit (teniendo en cuenta el umbral)
results.language	Código de language detectado y confidence
usage	Tu recuento de solicitudes API, límite y cuota restante para el periodo de facturación actual

Paso 4: Analiza una imagen

Para comprobar si una imagen contiene contenido NSFW, incluye la URL de la imagen en tu solicitud:

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

Paso 5: Combina varias comprobaciones

Puedes analizar texto e imágenes juntos en una sola solicitud:

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

Ejemplos de integración

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

¿El almacenamiento en caché cuenta contra mi cuota?

Discuse almacena en caché los resultados de contenido idéntico durante unos minutos. Cuando una respuesta llega con "cached": true, se sirvió desde la caché, por lo que se devuelve más rápido y evita volver a ejecutar las comprobaciones. La solicitud sigue contando como una solicitud API contra tu cuota, pero no se te vuelve a cobrar por los análisis subyacentes por función (imagen, antivirus). El almacenamiento en caché ayuda sobre todo cuando el mismo contenido se envía repetidamente en un intervalo breve.

¿Cómo manejo los errores?

Una comprobación correcta devuelve HTTP 200. Una clave incorrecta, un límite de frecuencia o una solicitud mal formada devuelven un estado que no es 2xx. Ten en cuenta que el agotamiento de la cuota no es un error HTTP: cuando se agota la cuota de tu periodo de facturación, la API sigue devolviendo 200 con has_violations: false y un message que explica que se superó la cuota; comprueba los campos message y usage en lugar de confiar en un código de estado.

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

Siguientes pasos

Ahora que ya hiciste tu primera llamada a la API, explora estos recursos:

• Autenticación y claves API - Aprende sobre la gestión segura de claves
• Análisis de texto - Profundiza en la detección de sentimiento y spam
• Detección de NSFW en imágenes - Protege tu plataforma de imágenes inapropiadas
• Configuración de umbrales - Ajusta con precisión la sensibilidad de detección