API de Moderación de ZPK - Documentación técnica

Conexión a la API

Servidor:	https://zpk.systems
Esquema:	HTTPS, solo conexiones seguras SSL.
Protocolo:	JSON recomendado Enviando un JSON en el body del request, y especificando una cabecera Content-Type: application/json en el request Si envia ficheros como imágenes o documentos, estos deberán estar codificados en base64. Form-Data no recomendado Formato usado en los formularios web, no recomendado. Al enviar una solicitud tipo form_data puede enviar todos los campos como parámetros POST separados. Sin embargo si la solicitud es muy grande recomendamos que envie el contenido de la peticion en un único campo de texto llamado _json (con un guión bajo). Este parametro especial sera procesado por nuestro backend como si se tratase de una solicitud JSON habitual.

POST /api/moderator/scan

Parámetro	Descripción
application_id	alfanumérico requerido Una id de aplicación, puede obtener la id de una aplicación haciendo click en 'detalles' en su panel
api_key	alfanumérico requerido La API KEY de la aplicación que efectúa la llamada a esta API, puede obtenerla en su panel, haciendo click en 'detalles' de una aplicación
messages	array requerido Max: 30 Un array de elementos conteniendo cada uno un elemento a analizar, estos elementos deben contener como mínimo el texto a analizar, y opcionalmente un identificador de fuente y/o identificador de mensaje. Parámetro Descripción text string requerido Max: 5.000 caracteres. El texto a analizar, que no puede superar los 5000 caracteres source_id alfanumérico opcional Max: 15 caracteres. Un identificador único de la fuente del mensaje, para detectar patrones dañinos que se repiten en una misma fuente de mensajes. El identificador puede estar vinculado a una fuente de la red social auto-importada en concreto, a comentarios escritos por un usuario esppecífico, a un hilo concreto de un foro, a los mensajes de un usuario en una conversación específica de un chat, o a cualquier otra fuente que considere oportuna. message_id alfanumérico opcional Max: 15 caracteres. Un identificador único del texto a analizar en concreto. Este identificador no se usa internamente pero es devuelto en los requests, para que pueda identificar el origen de cada texto si es necesario.

Estructura de una respuesta

---

El servidor retornará un JSON, con un boleano success si la solicitud de envío se procesó correctamente.

Adicionalmente en el JSON se retornará la lista de elementos results, y cada elemento contendra el mensaje original a analizar y un resultado de ese análisis.

Como en el resto de las peticiones a APIS de ZPK Systems, se dispone un parámetro cost indicando el coste total de la solicitud a la API.

Estructura de respuesta

Parámetro	Descripción
success	boleano Un boleano con valor true si se pudo procesar su solicitud. O false, en caso de errores.
messages	array Un array que contendrá todos los elementos que se solicitaron analizar, con una puntuación en diferentes categorias indicando posibles alertas. Consulte la siguiente tabla para detalles sobre los elementos de este array.
cost	float El coste de la solicitud

Estructura del array messages

Parámetro	Descripción
input	string El texto que usted envió
source_id	string opcional Si se envió un identificador de fuente source_id, contendrá el identificador source_id enviado.
message_id	string opcional Si se envió un identificador de mensaje message_id_id, contendrá el identificador message_id enviado.
categories	Array de categorias Un array conteniendo por cada categoría un identificador de esa categoría, una puntuación, y un flag de alerta si se detecto texto que active esa catagoría en concreto. Las categorias retornadas son: hate Mensajes basados en, o de incitación, tematicas relacionadas con el odio. hate_threatening Mensajes amenazantes de odio, como por ejemplo la incitación a la violencia contra un grupo o colectivo. self_harm Mensajes que promueven, o en menor medida hablan de, tematicas relacionadas con la auto-lesión. sexual Mensajes de contenido sexual. sexual_minors Mensajes de contenido sexual relacionados con menores de edad. violence Mensajes de contenido violento. violence_graphic Mensajes con contenido de violencia grafica. Cada categoria dispone a su vez de: id El identificador de categoría: hate,hate_threatening,self_harm,sexual,sexual_minors,violence o violence_graphic score Una puntuación float que indica la intensidad de esa categoría en el mensaje concreto. danger Un boleando indicando alerta si el mensaje fué catalogado en esta cagegoría true, o no false.

Ejemplo de respuesta con envío correcto.

---

En este ejemplo podemos ver dos mensajes distintos después de procesarse.

El primer mensaje es de un usuario que afirma que esta jugando a un videojuego de disparos, y avisa de que va a disparar a todos los enemigos. En este mensaje la alerta de 'violencia' es disparada, sin embargo la API no detectó odio ni amenzas.

El segundo mensaje también afirma que disparará pero en otro contexto, en esta caso la api de moderación detecta una amenaza mucho mas alta, y vemos como ademas de 'violencia' se activa el detector de 'odio' y el de 'amenaza'.

{
   "success": true,
   "messages": [
      {
         "input": {
            "text": "Estoy jugando al videojuego este, pero los enemigos no paran de matarme xd los matare a todos",
            "source_id": "test",
            "message_id": ""
         },
         "categories": {
            "hate": {
               "id": "hate",
               "score": "0.000185327",
               "danger": false
            },
            "hate_threatening": {
               "id": "hate_threatening",
               "score": "0.000000335",
               "danger": false
            },
            "self_harm": {
               "id": "self_harm",
               "score": "0.000000909",
               "danger": false
            },
            "sexual": {
               "id": "sexual",
               "score": "0.000002828",
               "danger": false
            },
            "sexual_minors": {
               "id": "sexual_minors",
               "score": "0.000000048",
               "danger": false
            },
            "violence": {
               "id": "violence",
               "score": "0.767623782",
               "danger": true
            },
            "violence_graphic": {
               "id": "violence_graphic",
               "score": "0.000000240",
               "danger": false
            }
         }
      },
      {
         "input": {
            "text": "Los matare a todos",
            "source_id": "test",
            "message_id": ""
         },
         "categories": {
            "hate": {
               "id": "hate",
               "score": "0.960755408",
               "danger": true
            },
            "hate_threatening": {
               "id": "hate_threatening",
               "score": "0.702908933",
               "danger": true
            },
            "self_harm": {
               "id": "self_harm",
               "score": "0.000000001",
               "danger": false
            },
            "sexual": {
               "id": "sexual",
               "score": "0.000002006",
               "danger": false
            },
            "sexual_minors": {
               "id": "sexual_minors",
               "score": "0.000000261",
               "danger": false
            },
            "violence": {
               "id": "violence",
               "score": "0.997496307",
               "danger": true
            },
            "violence_graphic": {
               "id": "violence_graphic",
               "score": "0.000001936",
               "danger": false
            }
         }
      }
   ],
   "cost": 0.003
}

Ejemplo de respuesta con error general

Ejemplo con un envío incorrecto que NO será procesado.

{
   "success": false,
   "errors": [
      {
         "id": "INVALID_PARAMETER",
         "message": "Messages array is empty.",
		 "on": "messages"
      }
	]
}
				

Esta API asigna a cada mensaje una puntuación score y una alerta danger.

Las alertas suelen activarse cuando la puntuación se acerca a 0.7, sin embargo la IA puede decidir si disparar la alerta o no dependiendo se un analisis de contextualización del mensaje.

Por ejemplo: Un mensaje podría contener texto hablando sobre la violencia y por lo tanto tener una puntuación de violence.score relativamente alta, pero la IA podría decidir no disparar una alerta violence.danger si ese mensaje hace referencia a un videojuego de disparos y no a una amenaza real.

En todo caso, es usted el que debe determinar cual es el umbral de cada categoría que su aplicación debe tolerar, puesto que habitualmente no se aplicaran las mismas restricciones en una comunidad de publico adulto donde todos los usuarios son mayores de edad, o en una comunidad apta para todos los publicos.

La API de moderación de ZPK asignará aquellos analisis en los que se haya especificado un source_id a una fuente concreta.

Cuando se analiza una fuente, o cuando se consulta el endpoint de estado de fuente, se retorna una puntuación media total que usted puede usar para determinar la actitud 'global' del emisor de los mensajes.

Una fuente puede ser cualquier origen de mensaje que su aplicación determine, por ejemplo, un usuario concreto, o una conversación de chat concreta.

Este endpoint retornará para una fuente concreta, la puntuación actual asociada a esa fuente en cada categoría peligrosa.

Retorna además información sobre número de mensajes procesados, y una puntuación de actitud 'global'.

Endpoint de consulta

---

GET /api/moderator/source-info

Parámetro	Descripción
application_id	alfanumérico requerido Una ID de aplicación, puede obtener la id de una aplicación haciendo click en 'detalles' en su panel
api_key	alfanumérico requerido La API KEY de la aplicación que efectúa la llamada a esta API, puede obtenerla en su panel, haciendo click en 'detalles' de una aplicación
source_id	alfanumérico opcional Un identificador único de la fuente a consultar.

Estructura de la respuesta

---

Estructura de respuesta

Parámetro	Descripción
success	boleano Un boleano con valor true si se pudo procesar su solicitud. O false, en caso de errores.
scores	array Un array asociativo que contendrá las medias para cada categoría de amenaza. Cada elemento de esta lista contendrá: average_score float La puntuación media de todos los mensajes enviados por esta fuente en la categoría concreta. percentage_total_messages float El porcentaje de mensajes que han sido catalogados como peligrosos danger en esta categoría.
cost	float El coste de la solicitud

Ejemplo de respuesta, medias de fuente.

---

{
   "success": true,
   "source_id": "test",
   "scores": {
      "hate": {
         "average_score": 0.3245996,
         "percentage_total_messages": 29.63
      },
      "hate_threatening": {
         "average_score": 0.1642738,
         "percentage_total_messages": 29.63
      },
      "self_harm": {
         "average_score": 0.0004603,
         "percentage_total_messages": 0
      },
      "sexual": {
         "average_score": 0.0018926,
         "percentage_total_messages": 0
      },
      "sexual_minors": {
         "average_score": 0.0001772,
         "percentage_total_messages": 0
      },
      "violence": {
         "average_score": 0.5734031,
         "percentage_total_messages": 44.44
      },
      "violence_graphic": {
         "average_score": 0.0218495,
         "percentage_total_messages": 0
      }
   },
   "cost": 0.005
}

SDK en PHP para detectar mensajes peligrosos

ZPK-PHP es una librería de código abierto instalable mediante composer que le permitirá integrar nuestras APIs en su proyecto PHP con un mínimo esfuerzo.

Documentación del SDK para PHP

Instalando ZPK-PHP con composer

composer require zpksystems/phpzpk

Ejemplo de request para analizar mensajes

<?php

$application = new zpkApplication('app_id','api_key');
$moderator = new zpkModerator($application);

$moderator->addText( ['text'=>'I want to k**l myself.'] );

echo json_encode($moderator->scan(),
 JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE);