Análisis de texto: sentimiento, spam e idioma en una sola llamada

El análisis de texto de Discuse puntúa un mensaje por toxicidad, spam e idioma en una única solicitud POST https://api.discuse.com/api/v2/check. Envía tu texto en content.text, autentícate con el encabezado X-API-Key y consulta los resultados de cada comprobación en results.

¿Qué comprueba el endpoint de texto?

Una llamada a /api/v2/check puede ejecutar tres comprobaciones de texto a la vez:

• Sentimiento: puntuación de toxicidad, lenguaje soez, amenazas e insultos, además de un veredicto negativo/tóxico.
• Spam: spam promocional, estafas y texto generado por bots, devuelto como un label junto con una puntuación de confianza.
• Idioma: el código de idioma detectado, con aplicación opcional frente a un idioma esperado.

Cada comprobación solo se ejecuta cuando está habilitada, ya sea en la configuración de tu proyecto o mediante el objeto settings de cada solicitud.

¿Cómo llamo al endpoint de texto?

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 acepta hasta 10.000 caracteres. La clave de API puede enviarse en el encabezado X-API-Key o como api_key en el cuerpo de la solicitud.

Respuesta

{
  "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 refleja results.hits: es true cuando cualquier comprobación habilitada activa su indicador hit. processing_time_ms solo aparece cuando el registro de tiempos está habilitado en la configuración de tu proyecto.

Análisis de sentimiento

La comprobación de sentimiento devuelve tanto un veredicto como puntuaciones por dimensión de 0,0 a 1,0.

Campo	Tipo	Significado
is_negative	bool	El mensaje se interpreta como negativo
is_toxic	bool	El mensaje supera el umbral de toxicidad
score	number	Puntuación general de sentimiento/gravedad
toxicity	number	Confianza de toxicidad (0,0–1,0)
toxic	number	Confianza de toxicidad (alias heredado de toxicity)
profanity	number	Confianza de lenguaje explícito
threat	number	Confianza de amenaza de daño
insult	number	Confianza de ataque personal
hit	bool	Verdadero cuando el mensaje infringe los umbrales de sentimiento
message	string	Explicación opcional

¿Cómo interpreto una puntuación de sentimiento?

Una puntuación es la confianza del modelo en que esa dimensión se aplica:

• 0,0 – 0,3: baja, generalmente segura.
• 0,3 – 0,6: moderada, puede requerir revisión.
• 0,6 – 0,8: alta, probablemente problemática.
• 0,8 – 1,0: muy alta, casi con total seguridad infractora.

Ejemplo: contenido tóxico

Solicitud:

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

Respuesta:

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

Detección de spam

La comprobación de spam clasifica el texto y devuelve un único label con una puntuación de confianza. Detecta los patrones que esquivan las listas de bloqueo por palabras clave: spam promocional, estafas y phishing, y texto generado por bots.

Ejemplo: contenido de spam

Solicitud:

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

Respuesta:

{
  "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 es el veredicto bruto del modelo (el modelo etiquetó el texto como spam). hit es la decisión que tiene en cuenta el umbral: solo es true cuando is_spam es true y confidence supera el umbral de spam de tu proyecto. Basa la moderación en hit, no en is_spam. Consulta la guía de detección de spam para más detalles.

Detección de idioma

Establece check_language para detectar el código de idioma de content.text. El resultado está en results.language.language (por ejemplo, "en", "fr", "es").

Solicitud:

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

Respuesta:

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

Para marcar contenido que no esté en el idioma esperado, establece expected_language. Cuando el idioma detectado difiere, language.hit es true y se rellenan expected/detected:

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

Consulta detección de idioma para ver la lista completa de idiomas y los patrones de aplicación.

¿Qué comprobaciones puedo activar o desactivar?

El objeto opcional settings sobrescribe los valores predeterminados de tu proyecto para una sola solicitud. Los ajustes relevantes para texto son:

Ajuste	Tipo	Efecto
check_sentiment	bool	Ejecutar análisis de sentimiento
check_spam	bool	Ejecutar detección de spam
check_language	bool	Ejecutar detección de idioma
check_badwords	bool	Ejecutar la lista de bloqueo de palabras prohibidas
expected_language	string	Código de idioma que se debe aplicar (p. ej., "en")

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

Límites de uso

La detección de sentimiento, spam e idioma consume la cuota de análisis de sentimiento de cada plan:

Plan	Análisis de sentimiento/mes
Basic	1.000
Gold	5.000
Platinum	15.000
Ultimate	30.000

Las respuestas en caché no cuentan contra tu cuota. El objeto usage de cada respuesta informa de api_requests_used, api_requests_limit y api_requests_remaining.

Buenas prácticas

Establece umbrales por plataforma

Aplica distintos límites de sentimiento para diferentes audiencias:

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

Ten en cuenta el contexto

El contenido clínico, periodístico y de ficción puede activar legítimamente puntuaciones de toxicidad y lenguaje soez. Combina la puntuación automatizada con la revisión humana en los casos límite:

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

Ejemplos de integración

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

¿Listo para implementar el análisis de texto? Consulta la guía de inicio rápido para ver la configuración paso a paso.