> ## Documentation Index
> Fetch the complete documentation index at: https://evolink.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# EvoLink Moderation 1.0 - Referencia completa de la API

> - Endpoint síncrono que detecta contenido nocivo en **texto** y/o **imágenes** a través de 13 dimensiones
- En la respuesta, el campo `evolink_summary` devuelve un resumen unificado con cinco propiedades: `risk_level` / `flagged` / `violations` / `max_score` / `max_category`

**Capacidades principales**:
- **Moderación multimodal**: admite entradas de solo texto, solo imagen o combinaciones de texto + imagen
- **13 categorías**: harassment, hate, sexual, violence, self-harm, illicit, sexual/minors, etc.
- **Clasificación de riesgo**: cada categoría define umbrales medium / high independientes y se evalúa con sensibilidad diferenciada (la categoría crítica sexual/minors aplica los umbrales más estrictos)
- **Explicable**: la respuesta devuelve simultáneamente los `category_scores` por categoría y el `evolink_summary` simplificado; el negocio puede usar uno u otro

**Limitaciones de entrada**:
- Como máximo 1 imagen por solicitud (si necesitas moderar varias imágenes, divide la carga en solicitudes paralelas)
- Las imágenes solo se aceptan como URL HTTPS

**Uso típico**: consulta los ejemplos de abajo, que cubren los tres escenarios habituales: solo texto, texto + imagen y solo imagen.

<Note>
  **BaseURL**: La BaseURL predeterminada es `https://direct.evolink.ai`, que ofrece mejor compatibilidad con modelos de texto y admite conexiones persistentes. `https://api.evolink.ai` es el endpoint principal para servicios multimodales y actúa como dirección de respaldo para los modelos de texto.
</Note>


## OpenAPI

````yaml es/api-manual/language-series/evolink-moderation-1.0/evolink-moderation-1.0-api.json POST /v1/moderations
openapi: 3.1.0
info:
  title: EvoLink Moderation 1.0 - Referencia completa de la API
  description: >-
    API de moderación de contenido de EvoLink: detecta contenido nocivo en
    textos e imágenes y devuelve un resumen unificado de riesgo a través del
    campo `evolink_summary`, para que el lado de negocio pueda evaluar el nivel
    de riesgo de un solo vistazo.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: Producción (recomendado)
  - url: https://api.evolink.ai
    description: Endpoint de respaldo
security:
  - bearerAuth: []
tags:
  - name: Moderación de contenido
    description: API de moderación de contenido de EvoLink (texto + imagen)
paths:
  /v1/moderations:
    post:
      tags:
        - Moderación de contenido
      summary: Endpoint de moderación de contenido EvoLink Moderation
      description: >-
        - Endpoint síncrono que detecta contenido nocivo en **texto** y/o
        **imágenes** a través de 13 dimensiones

        - En la respuesta, el campo `evolink_summary` devuelve un resumen
        unificado con cinco propiedades: `risk_level` / `flagged` / `violations`
        / `max_score` / `max_category`


        **Capacidades principales**:

        - **Moderación multimodal**: admite entradas de solo texto, solo imagen
        o combinaciones de texto + imagen

        - **13 categorías**: harassment, hate, sexual, violence, self-harm,
        illicit, sexual/minors, etc.

        - **Clasificación de riesgo**: cada categoría define umbrales medium /
        high independientes y se evalúa con sensibilidad diferenciada (la
        categoría crítica sexual/minors aplica los umbrales más estrictos)

        - **Explicable**: la respuesta devuelve simultáneamente los
        `category_scores` por categoría y el `evolink_summary` simplificado; el
        negocio puede usar uno u otro


        **Limitaciones de entrada**:

        - Como máximo 1 imagen por solicitud (si necesitas moderar varias
        imágenes, divide la carga en solicitudes paralelas)

        - Las imágenes solo se aceptan como URL HTTPS


        **Uso típico**: consulta los ejemplos de abajo, que cubren los tres
        escenarios habituales: solo texto, texto + imagen y solo imagen.
      operationId: createModeration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModerationRequest'
            examples:
              moderate_text:
                summary: Moderación de solo texto
                value:
                  model: evolink-moderation-1.0
                  input:
                    - type: text
                      text: I want to kill them.
              moderate_image_url:
                summary: Moderación de solo imagen
                value:
                  model: evolink-moderation-1.0
                  input:
                    - type: image_url
                      image_url:
                        url: https://example.com/image.png
              moderate_text_and_image:
                summary: Moderación combinada de texto + imagen (recomendado)
                value:
                  model: evolink-moderation-1.0
                  input:
                    - type: text
                      text: Por favor, describe lo que aparece en esta imagen.
                    - type: image_url
                      image_url:
                        url: https://example.com/image.png
      responses:
        '200':
          description: Moderación completada con éxito
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModerationResponse'
              example:
                evolink_summary:
                  risk_level: medium
                  flagged: false
                  violations: []
                  max_score: 0.597383272
                  max_category: sexual
                id: modr-0d9740456c391e43c445bf0f010940c7
                model: evolink-moderation-1.0
                results:
                  - flagged: false
                    categories:
                      harassment: false
                      harassment/threatening: false
                      hate: false
                      hate/threatening: false
                      illicit: false
                      illicit/violent: false
                      self-harm: false
                      self-harm/intent: false
                      self-harm/instructions: false
                      sexual: false
                      sexual/minors: false
                      violence: false
                      violence/graphic: false
                    category_scores:
                      harassment: 0.0006
                      harassment/threatening: 0.0007
                      hate: 0.00003
                      hate/threatening: 0.0000025
                      illicit: 0.000013
                      illicit/violent: 0.0000096
                      self-harm: 0.0000166
                      self-harm/intent: 0.000004
                      self-harm/instructions: 0.0000031
                      sexual: 0.597383272
                      sexual/minors: 0.000004
                      violence: 0.0231
                      violence/graphic: 0.0089
                    category_applied_input_types:
                      harassment:
                        - text
                      harassment/threatening:
                        - text
                      hate:
                        - text
                      hate/threatening:
                        - text
                      illicit:
                        - text
                      illicit/violent:
                        - text
                      self-harm:
                        - text
                      self-harm/intent:
                        - text
                      self-harm/instructions:
                        - text
                      sexual:
                        - text
                      sexual/minors:
                        - text
                      violence:
                        - text
                      violence/graphic:
                        - text
        '400':
          description: Parámetros de la solicitud no válidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 400
                  message: field input is required
                  type: invalid_request_error
                  param: input
        '401':
          description: No autenticado, token no válido o caducado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid or expired token
                  type: authentication_error
        '402':
          description: Cuota insuficiente, se requiere recarga
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 402
                  message: Insufficient quota
                  type: insufficient_quota_error
                  fallback_suggestion: https://evolink.ai/dashboard/billing
        '403':
          description: Sin permisos para acceder a este modelo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 403
                  message: Access denied for this model
                  type: permission_error
                  param: model
        '404':
          description: Recurso no encontrado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 404
                  message: Specified model not found
                  type: not_found_error
                  param: model
                  fallback_suggestion: evolink-moderation-1.0
        '413':
          description: Cuerpo de la solicitud demasiado grande (la imagen supera el límite)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 413
                  message: Image file too large
                  type: request_too_large_error
                  param: input
                  fallback_suggestion: compress image to under 20MB
        '429':
          description: Frecuencia de solicitudes excedida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  type: rate_limit_error
                  fallback_suggestion: retry after 60 seconds
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 500
                  message: Internal server error
                  type: internal_server_error
                  fallback_suggestion: try again later
        '502':
          description: Error de puerta de enlace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 502
                  message: Bad gateway
                  type: bad_gateway_error
                  fallback_suggestion: try again later
        '503':
          description: Servicio temporalmente no disponible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 503
                  message: Service temporarily unavailable
                  type: service_unavailable_error
                  fallback_suggestion: retry after 30 seconds
components:
  schemas:
    ModerationRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: Nombre del modelo de moderación, fijo a `evolink-moderation-1.0`
          enum:
            - evolink-moderation-1.0
          example: evolink-moderation-1.0
        input:
          type: array
          description: >-
            Contenido a moderar, unificado en forma de array de objetos. Cada
            elemento es un objeto `text` o `image_url`.


            ```json

            "input": [
              {"type": "text", "text": "texto a moderar"},
              {"type": "image_url", "image_url": {"url": "https://..."}}
            ]

            ```


            **Limitaciones**:

            - Dentro del array puede haber **como máximo 1** objeto con
            `type=image_url`; si necesitas moderar varias imágenes, divide la
            carga en solicitudes paralelas

            - El número de objetos `type=text` no está limitado
          items:
            $ref: '#/components/schemas/ModerationContentItem'
    ModerationResponse:
      type: object
      description: >-
        Respuesta de moderación. El `evolink_summary` del nivel superior es el
        resumen unificado de riesgo recomendado para el lado de negocio;
        `results` ofrece el detalle de puntuaciones por categoría.
      properties:
        evolink_summary:
          $ref: '#/components/schemas/EvolinkSummary'
        id:
          type: string
          description: Identificador único de esta solicitud de moderación
          example: modr-0d9740456c391e43c445bf0f010940c7
        model:
          type: string
          description: >-
            Nombre del modelo realmente utilizado, fijo a
            `evolink-moderation-1.0`
          example: evolink-moderation-1.0
        results:
          type: array
          description: >-
            Lista de resultados de moderación. Devuelve siempre **1** result
            (las entradas en forma de array se consolidan en una única
            evaluación).


            ## Alcance de evaluación multimodal


            De las 13 categorías, algunas se evalúan **solo sobre texto** y no
            se aplican a imágenes:


            | Categoría | Alcance de evaluación |

            |------|----------|

            | `harassment` / `harassment/threatening` | Solo texto |

            | `hate` / `hate/threatening` | Solo texto |

            | `illicit` / `illicit/violent` | Solo texto |

            | `sexual/minors` | **Solo texto (categoría crítica — atención)** |

            | `self-harm` / `self-harm/intent` / `self-harm/instructions` |
            Texto + imagen |

            | `sexual` | Texto + imagen |

            | `violence` / `violence/graphic` | Texto + imagen |


            **Hechos clave**:

            - Cuando solo se envía una imagen, las 7 categorías anteriores de
            solo texto tendrán siempre puntuación `0` y
            `category_applied_input_types` vacío — **esto no significa que el
            contenido sea seguro, solo que no se evaluó**

            - Si tu negocio implica riesgo con menores (la categoría crítica
            `sexual/minors`), **debes enviar siempre el contexto textual junto
            con la imagen**; no puedes apoyarte únicamente en la puntuación de
            la imagen
          items:
            $ref: '#/components/schemas/ModerationResult'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: Código de estado HTTP del error
            message:
              type: string
              description: Descripción del error
            type:
              type: string
              description: Tipo de error
            param:
              type: string
              description: Nombre del parámetro relacionado
            fallback_suggestion:
              type: string
              description: Sugerencia ante el error
    ModerationContentItem:
      oneOf:
        - $ref: '#/components/schemas/TextInputItem'
        - $ref: '#/components/schemas/ImageInputItem'
    EvolinkSummary:
      type: object
      description: >-
        **Resumen de riesgo de EvoLink**: resumen unificado calculado a partir
        de `category_scores` de las 13 categorías, aplicando umbrales
        diferenciados según la sensibilidad de cada categoría. El negocio puede
        usarlo directamente para permitir / rechazar / enviar a revisión.


        ## Tabla de umbrales por nivel de riesgo


        | Categoría | Umbral medium | Umbral high | Notas |

        |------|-----------|----------|------|

        | `sexual/minors` | 0.05 | 0.20 | **Categoría crítica**, umbrales más
        estrictos |

        | `self-harm` / `self-harm/intent` / `self-harm/instructions` | 0.30 |
        0.60 | Riesgo vital, estricto |

        | `violence/graphic` | 0.40 | 0.70 | Violencia gráfica |

        | `illicit/violent` | 0.40 | 0.70 | Ilícito violento |

        | `sexual` | 0.50 | 0.80 | Sexual general |

        | `violence` | 0.50 | 0.80 | Violencia general |

        | `harassment/threatening` | 0.50 | 0.80 | Acoso amenazante |

        | `hate/threatening` | 0.50 | 0.80 | Odio amenazante |

        | `harassment` | 0.60 | 0.85 | Acoso general |

        | `hate` | 0.60 | 0.85 | Odio general |

        | `illicit` | 0.60 | 0.85 | Instrucciones ilícitas generales |


        ## Reglas de decisión


        ```

        Cualquier categoría con score >= umbral high   → risk_level = "high",  
        flagged = true,  se añade a violations

        Cualquier categoría con score >= umbral medium → risk_level = "medium",
        flagged = false

        En caso contrario                              → risk_level = "low",   
        flagged = false

        ```


        ## Recomendaciones de uso para el negocio


        ```python

        summary = response["evolink_summary"]


        if summary["flagged"]:                         # high → rechazar
        directamente
            reject(reason=summary["violations"])
        elif summary["risk_level"] == "medium":        # zona gris
            log_for_review(summary)                    # registrar y revisar manualmente
            proceed()
        else:                                          # low → permitir
            proceed()
        ```
      properties:
        risk_level:
          type: string
          description: >-
            Nivel de riesgo


            - `low`: todas las categorías están por debajo del umbral medium

            - `medium`: al menos una categoría supera el umbral medium pero
            ninguna supera el umbral high

            - `high`: al menos una categoría supera el umbral high (línea roja)
          enum:
            - low
            - medium
            - high
          example: medium
        flagged:
          type: boolean
          description: >-
            Indica si se debe sugerir el rechazo.


            Equivale a `risk_level == "high"`. **Se recomienda al negocio basar
            directamente en este campo la decisión de permitir/rechazar**.


            Nota: este campo es distinto de `results[].flagged` —
            `results[].flagged` es un booleano global que se activa cuando
            cualquier categoría cruza su umbral, mientras que el campo actual se
            calcula con los umbrales por niveles de EvoLink, aplicando
            sensibilidad diferenciada y resultando más controlable.
          example: false
        violations:
          type: array
          description: >-
            **Lista de categorías que han superado el umbral high**.


            - Cuando `risk_level == "high"`, este array enumera todas las
            categorías que superan el umbral high (por ejemplo,
            `["sexual/minors", "violence"]`)

            - Cuando `risk_level == "medium"` o `"low"`, este array está vacío
            `[]`
          items:
            type: string
          example:
            - sexual/minors
        max_score:
          type: number
          description: >-
            Puntuación máxima entre las 13 categorías (0~1). Útil para
            monitorización del negocio y ajuste de umbrales.
          minimum: 0
          maximum: 1
          example: 0.597383272
        max_category:
          type: string
          description: >-
            Nombre de la categoría correspondiente a la puntuación máxima (una
            de las 13 categorías)
          example: sexual
    ModerationResult:
      type: object
      description: Resultado de moderación de una única entrada
      properties:
        flagged:
          type: boolean
          description: >-
            Marca global de infracción: este campo es true cuando cualquier
            categoría dentro de `categories` es true.


            **Se recomienda al lado de negocio dar prioridad a
            `evolink_summary.flagged`**: este se calcula con los umbrales por
            niveles de la plataforma EvoLink, ofrece una lógica más fina y
            controlable; el campo actual es más adecuado como referencia
            secundaria.
          example: false
        categories:
          $ref: '#/components/schemas/ModerationCategories'
        category_scores:
          $ref: '#/components/schemas/ModerationCategoryScores'
        category_applied_input_types:
          $ref: '#/components/schemas/ModerationCategoryAppliedInputTypes'
    TextInputItem:
      title: Elemento de entrada de texto
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
          description: El tipo de contenido es siempre `text`
        text:
          type: string
          description: Texto que se va a moderar
          example: Por favor, describe lo que aparece en esta imagen.
    ImageInputItem:
      title: Elemento de entrada de imagen
      type: object
      required:
        - type
        - image_url
      properties:
        type:
          type: string
          enum:
            - image_url
          description: El tipo de contenido es siempre `image_url`
        image_url:
          type: object
          required:
            - url
          properties:
            url:
              type: string
              format: uri
              description: >-
                URL HTTPS de la imagen, por ejemplo:
                `https://example.com/image.png`


                **Formatos admitidos**: `.jpeg` / `.jpg` / `.png` / `.webp`


                **Límite de tamaño**: se recomienda que cada imagen no supere
                los 20MB (un tamaño excesivo puede provocar un error 413)


                **Aviso**: como máximo 1 imagen por solicitud; para varias
                imágenes, divide en solicitudes paralelas
              example: https://example.com/image.png
    ModerationCategories:
      type: object
      description: Indicadores booleanos de infracción para las 13 categorías
      properties:
        harassment:
          type: boolean
          description: >-
            Acoso: lenguaje que expresa, incita o fomenta acoso contra cualquier
            objetivo
        harassment/threatening:
          type: boolean
          description: >-
            Acoso amenazante: contenido de acoso que incluye violencia o daño
            grave
        hate:
          type: boolean
          description: >-
            Odio: contenido de odio basado en raza, género, etnia, religión,
            nacionalidad, orientación sexual, discapacidad o casta
        hate/threatening:
          type: boolean
          description: >-
            Odio amenazante: contenido de odio acompañado de violencia o daño
            grave hacia el grupo objetivo
        illicit:
          type: boolean
          description: >-
            Conducta ilícita: instrucciones o consejos para cometer actos
            ilegales (por ejemplo, «cómo robar»)
        illicit/violent:
          type: boolean
          description: >-
            Ilícito violento: contenido ilícito que incluye violencia o consejos
            para obtener armas
        self-harm:
          type: boolean
          description: >-
            Autolesión: promueve, alienta o describe conductas autolesivas
            (suicidio, cortes, trastornos alimentarios, etc.)
        self-harm/instructions:
          type: boolean
          description: >-
            Instrucciones de autolesión: contenido que alienta o instruye sobre
            cómo realizar autolesiones
        self-harm/intent:
          type: boolean
          description: >-
            Intención de autolesión: contenido que expresa que el propio emisor
            está realizando o tiene la intención de realizar autolesión
        sexual:
          type: boolean
          description: >-
            Sexual: contenido destinado a la excitación sexual (excepto la
            educación sexual y la salud)
        sexual/minors:
          type: boolean
          description: >-
            Sexual con menores (**categoría crítica**): contenido sexual que
            involucra a personas menores de 18 años
        violence:
          type: boolean
          description: 'Violencia: descripciones de muerte, violencia o daño físico'
        violence/graphic:
          type: boolean
          description: >-
            Violencia gráfica: descripciones de muerte, violencia o daño físico
            con detalles visuales explícitos
    ModerationCategoryScores:
      type: object
      description: >-
        Puntuaciones de confianza para las 13 categorías (0~1; cuanto más alta,
        más probable es la infracción)
      properties:
        harassment:
          type: number
          description: Confianza para harassment
          example: 0.0006
        harassment/threatening:
          type: number
          description: Confianza para harassment/threatening
          example: 0.0007
        hate:
          type: number
          description: Confianza para hate
          example: 0.00003
        hate/threatening:
          type: number
          description: Confianza para hate/threatening
          example: 0.0000025
        illicit:
          type: number
          description: Confianza para illicit
          example: 0.000013
        illicit/violent:
          type: number
          description: Confianza para illicit/violent
          example: 0.0000096
        self-harm:
          type: number
          description: Confianza para self-harm
          example: 0.0000166
        self-harm/instructions:
          type: number
          description: Confianza para self-harm/instructions
          example: 0.0000031
        self-harm/intent:
          type: number
          description: Confianza para self-harm/intent
          example: 0.000004
        sexual:
          type: number
          description: Confianza para sexual
          example: 0.5973
        sexual/minors:
          type: number
          description: Confianza para sexual/minors
          example: 0.000004
        violence:
          type: number
          description: Confianza para violence
          example: 0.0231
        violence/graphic:
          type: number
          description: Confianza para violence/graphic
          example: 0.0089
    ModerationCategoryAppliedInputTypes:
      type: object
      description: >-
        **Qué tipos de entrada se han evaluado realmente** para cada categoría.
        El valor es un array cuyos elementos son `text` o `image`.


        El alcance de evaluación de cada categoría (solo texto / texto + imagen)
        está descrito en la tabla de la propiedad `results`; el array aquí
        indica el tipo de entrada **realmente alcanzado** en la solicitud
        actual.
      properties:
        harassment:
          type: array
          description: Tipos de entrada evaluados para harassment (solo text)
          items:
            type: string
            enum:
              - text
        harassment/threatening:
          type: array
          items:
            type: string
            enum:
              - text
        hate:
          type: array
          items:
            type: string
            enum:
              - text
        hate/threatening:
          type: array
          items:
            type: string
            enum:
              - text
        illicit:
          type: array
          items:
            type: string
            enum:
              - text
        illicit/violent:
          type: array
          items:
            type: string
            enum:
              - text
        self-harm:
          type: array
          items:
            type: string
            enum:
              - text
              - image
        self-harm/instructions:
          type: array
          items:
            type: string
            enum:
              - text
              - image
        self-harm/intent:
          type: array
          items:
            type: string
            enum:
              - text
              - image
        sexual:
          type: array
          items:
            type: string
            enum:
              - text
              - image
        sexual/minors:
          type: array
          description: sexual/minors solo admite text
          items:
            type: string
            enum:
              - text
        violence:
          type: array
          items:
            type: string
            enum:
              - text
              - image
        violence/graphic:
          type: array
          items:
            type: string
            enum:
              - text
              - image
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        ##Todos los endpoints requieren autenticación con Bearer Token##


        **Obtener tu API Key:**


        Visita la [página de gestión de API
        Keys](https://evolink.ai/dashboard/keys) para obtener tu API Key.


        **Inclúyela en el encabezado de la solicitud:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````