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

# EvoLink Moderation 1.0 - Complete API Reference

> - Synchronous endpoint that detects harmful content across 13 dimensions for the input **text** and/or **image**
- The response returns a unified summary via the `evolink_summary` field with `risk_level` / `flagged` / `violations` / `max_score` / `max_category`

**Core capabilities**:
- **Multimodal moderation**: supports text-only, image-only, and combined text + image input
- **13 categories**: harassment, hate, sexual, violence, self-harm, illicit, sexual/minors, and more
- **Risk grading**: each category has its own medium / high thresholds, providing differentiated judgement based on sensitivity (the red-line category sexual/minors uses the strictest thresholds)
- **Explainable**: the response returns both per-category `category_scores` and a simplified `evolink_summary` — you can use either depending on your needs

**Input limits**:
- At most 1 image per request (split into concurrent requests if you need to moderate multiple images)
- Images must be provided as HTTPS URLs

**Typical usage**: see the examples below, covering the three typical scenarios — text-only, text + image, and image-only.

<Note>
  **BaseURL**: The default BaseURL is `https://direct.evolink.ai`, which has better support for text models and long-lived connections. `https://api.evolink.ai` is the primary endpoint for multimodal services and serves as a fallback address for text models.
</Note>


## OpenAPI

````yaml /en/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 Complete API Reference
  description: >-
    EvoLink content moderation API. Detects harmful content in text and images,
    and returns a unified risk summary via the `evolink_summary` field so your
    application can determine the risk level at a glance.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: Production (recommended)
  - url: https://api.evolink.ai
    description: Fallback endpoint
security:
  - bearerAuth: []
tags:
  - name: Content Moderation
    description: EvoLink content moderation API (text + image)
paths:
  /v1/moderations:
    post:
      tags:
        - Content Moderation
      summary: EvoLink Moderation content moderation endpoint
      description: >-
        - Synchronous endpoint that detects harmful content across 13 dimensions
        for the input **text** and/or **image**

        - The response returns a unified summary via the `evolink_summary` field
        with `risk_level` / `flagged` / `violations` / `max_score` /
        `max_category`


        **Core capabilities**:

        - **Multimodal moderation**: supports text-only, image-only, and
        combined text + image input

        - **13 categories**: harassment, hate, sexual, violence, self-harm,
        illicit, sexual/minors, and more

        - **Risk grading**: each category has its own medium / high thresholds,
        providing differentiated judgement based on sensitivity (the red-line
        category sexual/minors uses the strictest thresholds)

        - **Explainable**: the response returns both per-category
        `category_scores` and a simplified `evolink_summary` — you can use
        either depending on your needs


        **Input limits**:

        - At most 1 image per request (split into concurrent requests if you
        need to moderate multiple images)

        - Images must be provided as HTTPS URLs


        **Typical usage**: see the examples below, covering the three typical
        scenarios — text-only, text + image, and image-only.
      operationId: createModeration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModerationRequest'
            examples:
              moderate_text:
                summary: Text-only moderation
                value:
                  model: evolink-moderation-1.0
                  input:
                    - type: text
                      text: I want to kill them.
              moderate_image_url:
                summary: Image-only moderation
                value:
                  model: evolink-moderation-1.0
                  input:
                    - type: image_url
                      image_url:
                        url: https://example.com/image.png
              moderate_text_and_image:
                summary: Combined text + image moderation (recommended)
                value:
                  model: evolink-moderation-1.0
                  input:
                    - type: text
                      text: Please describe what's in this image.
                    - type: image_url
                      image_url:
                        url: https://example.com/image.png
      responses:
        '200':
          description: Moderation succeeded
          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: Bad request
          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: Unauthenticated, invalid or expired token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid or expired token
                  type: authentication_error
        '402':
          description: Insufficient quota, please top up
          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: No permission to access this model
          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: Resource not found
          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: Request body too large (image exceeds size limit)
          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: Rate limit exceeded
          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: Internal server error
          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: Bad gateway
          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: Service temporarily unavailable
          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: Moderation model name. Fixed value `evolink-moderation-1.0`.
          enum:
            - evolink-moderation-1.0
          example: evolink-moderation-1.0
        input:
          type: array
          description: >-
            Content to moderate, expressed uniformly as an array of objects.
            Each element is either a `text` or `image_url` object.


            ```json

            "input": [
              {"type": "text", "text": "text to moderate"},
              {"type": "image_url", "image_url": {"url": "https://..."}}
            ]

            ```


            **Limits**:

            - The array can contain **at most 1** object with `type=image_url`.
            To moderate multiple images, split into concurrent requests.

            - The number of `type=text` objects is unlimited.
          items:
            $ref: '#/components/schemas/ModerationContentItem'
    ModerationResponse:
      type: object
      description: >-
        Moderation response. The top-level `evolink_summary` is the recommended
        unified risk summary for application use; `results` provides
        per-category detailed scores.
      properties:
        evolink_summary:
          $ref: '#/components/schemas/EvolinkSummary'
        id:
          type: string
          description: Unique identifier for this moderation request.
          example: modr-0d9740456c391e43c445bf0f010940c7
        model:
          type: string
          description: >-
            Name of the model actually used. Fixed value
            `evolink-moderation-1.0`.
          example: evolink-moderation-1.0
        results:
          type: array
          description: >-
            List of moderation results. Always returns **1** result (array-form
            input is merged into a single scoring pass).


            ## Multimodal evaluation scope


            Among the 13 categories, some are **evaluated on text only** and are
            not evaluated on images:


            | Category | Evaluation scope |

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

            | `harassment` / `harassment/threatening` | Text only |

            | `hate` / `hate/threatening` | Text only |

            | `illicit` / `illicit/violent` | Text only |

            | `sexual/minors` | **Text only (red-line category — handle with
            care)** |

            | `self-harm` / `self-harm/intent` / `self-harm/instructions` | Text
            + image |

            | `sexual` | Text + image |

            | `violence` / `violence/graphic` | Text + image |


            **Key facts**:

            - When only an image is sent, the scores for the 7 text-only
            categories above will always be `0` and
            `category_applied_input_types` will be an empty array — **this does
            NOT mean the content is safe, only that it was not evaluated**.

            - If your business involves risks to minors (the `sexual/minors`
            red-line category), you **must submit text context together for
            moderation** and cannot rely on image scores alone.
          items:
            $ref: '#/components/schemas/ModerationResult'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: HTTP status error code.
            message:
              type: string
              description: Error description.
            type:
              type: string
              description: Error type.
            param:
              type: string
              description: Related parameter name.
            fallback_suggestion:
              type: string
              description: Suggested fallback action.
    ModerationContentItem:
      oneOf:
        - $ref: '#/components/schemas/TextInputItem'
        - $ref: '#/components/schemas/ImageInputItem'
    EvolinkSummary:
      type: object
      description: >-
        **EvoLink risk summary**: a unified summary derived from the 13
        categories' `category_scores` using differentiated thresholds tuned to
        each category's sensitivity. Your application can directly use it to
        allow / reject / send for review.


        ## Risk grading thresholds


        | Category | medium threshold | high threshold | Notes |

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

        | `sexual/minors` | 0.05 | 0.20 | **Red-line category**, strictest
        thresholds |

        | `self-harm` / `self-harm/intent` / `self-harm/instructions` | 0.30 |
        0.60 | Life-threatening, strict |

        | `violence/graphic` | 0.40 | 0.70 | Graphic violence |

        | `illicit/violent` | 0.40 | 0.70 | Violent illicit |

        | `sexual` | 0.50 | 0.80 | General sexual |

        | `violence` | 0.50 | 0.80 | General violence |

        | `harassment/threatening` | 0.50 | 0.80 | Threatening harassment |

        | `hate/threatening` | 0.50 | 0.80 | Threatening hate |

        | `harassment` | 0.60 | 0.85 | General harassment |

        | `hate` | 0.60 | 0.85 | General hate |

        | `illicit` | 0.60 | 0.85 | General illicit instructions |


        ## Decision rules


        ```

        any category score >= its high threshold   → risk_level = "high",  
        flagged = true,  added to violations

        any category score >= its medium threshold → risk_level = "medium",
        flagged = false

        otherwise                                  → risk_level = "low",   
        flagged = false

        ```


        ## Recommended usage


        ```python

        summary = response["evolink_summary"]


        if summary["flagged"]:                         # high → reject directly
            reject(reason=summary["violations"])
        elif summary["risk_level"] == "medium":        # gray area
            log_for_review(summary)                    # log for manual sampling
            proceed()
        else:                                          # low → allow
            proceed()
        ```
      properties:
        risk_level:
          type: string
          description: >-
            Risk level.


            - `low`: all categories are below their medium thresholds

            - `medium`: at least one category crossed its medium threshold but
            no category crossed its high threshold

            - `high`: at least one category crossed its high threshold (red
            line)
          enum:
            - low
            - medium
            - high
          example: medium
        flagged:
          type: boolean
          description: >-
            Whether a reject suggestion is triggered.


            Equivalent to `risk_level == "high"`. **Recommended for direct allow
            / reject decisions in your application.**


            Note: this field differs from `results[].flagged` —
            `results[].flagged` is a global boolean that becomes true when any
            category crosses its line, while this field is judged with EvoLink's
            tiered thresholds tuned to each category's sensitivity, providing
            finer control.
          example: false
        violations:
          type: array
          description: >-
            **List of categories that crossed their high thresholds.**


            - When `risk_level == "high"`, this array lists the names of all
            categories that crossed their high thresholds (e.g.
            `["sexual/minors", "violence"]`)

            - When `risk_level == "medium"` or `"low"`, this array is empty `[]`
          items:
            type: string
          example:
            - sexual/minors
        max_score:
          type: number
          description: >-
            The highest score across the 13 categories (0~1). Useful for
            monitoring and threshold tuning.
          minimum: 0
          maximum: 1
          example: 0.597383272
        max_category:
          type: string
          description: >-
            Name of the category corresponding to the highest score (one of the
            13 categories).
          example: sexual
    ModerationResult:
      type: object
      description: Moderation result for a single input.
      properties:
        flagged:
          type: boolean
          description: >-
            Global violation flag: this field is true when any category in
            `categories` is true.


            **For business use we recommend `evolink_summary.flagged` instead**
            — it is judged using EvoLink's tiered thresholds, with finer and
            more controllable logic. This field is better suited as a fallback
            reference.
          example: false
        categories:
          $ref: '#/components/schemas/ModerationCategories'
        category_scores:
          $ref: '#/components/schemas/ModerationCategoryScores'
        category_applied_input_types:
          $ref: '#/components/schemas/ModerationCategoryAppliedInputTypes'
    TextInputItem:
      title: Text input item
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
          description: Content type — fixed value `text`.
        text:
          type: string
          description: Text to moderate.
          example: Please describe what's in this image.
    ImageInputItem:
      title: Image input item
      type: object
      required:
        - type
        - image_url
      properties:
        type:
          type: string
          enum:
            - image_url
          description: Content type — fixed value `image_url`.
        image_url:
          type: object
          required:
            - url
          properties:
            url:
              type: string
              format: uri
              description: >-
                HTTPS URL of the image, for example:
                `https://example.com/image.png`


                **Supported formats**: `.jpeg` / `.jpg` / `.png` / `.webp`


                **Size limit**: a single image should be ≤ 20MB (oversized
                images may trigger a 413 error)


                **Note**: at most 1 image per request — split multiple images
                into concurrent requests.
              example: https://example.com/image.png
    ModerationCategories:
      type: object
      description: Boolean violation flags for the 13 categories.
      properties:
        harassment:
          type: boolean
          description: >-
            Harassment: content that expresses, incites, or promotes harassing
            language toward any target.
        harassment/threatening:
          type: boolean
          description: >-
            Threatening harassment: harassment content that includes violence or
            serious harm.
        hate:
          type: boolean
          description: >-
            Hate: hateful content based on race, gender, ethnicity, religion,
            nationality, sexual orientation, disability status, or caste.
        hate/threatening:
          type: boolean
          description: >-
            Threatening hate: hateful content that also includes violence or
            serious harm toward the targeted group.
        illicit:
          type: boolean
          description: >-
            Illicit behavior: provides instructions or advice on illegal acts
            (e.g. "how to steal").
        illicit/violent:
          type: boolean
          description: >-
            Violent illicit: illicit content that includes violence or advice on
            acquiring weapons.
        self-harm:
          type: boolean
          description: >-
            Self-harm: promotes, encourages, or depicts self-harming behaviors
            (suicide, cutting, eating disorders, etc.).
        self-harm/instructions:
          type: boolean
          description: >-
            Self-harm instructions: content that encourages or instructs how to
            perform self-harm.
        self-harm/intent:
          type: boolean
          description: >-
            Self-harm intent: content expressing that the speaker is engaging in
            or intends to engage in self-harm.
        sexual:
          type: boolean
          description: >-
            Sexual: content meant to arouse sexual excitement (excluding sexual
            education and wellness).
        sexual/minors:
          type: boolean
          description: >-
            Sexual content involving minors (**red-line category**): sexual
            content that includes individuals under 18 years old.
        violence:
          type: boolean
          description: 'Violence: depicts death, violence, or physical injury.'
        violence/graphic:
          type: boolean
          description: >-
            Graphic violence: depicts death, violence, or physical injury in
            graphic detail.
    ModerationCategoryScores:
      type: object
      description: >-
        Confidence scores for the 13 categories (0~1, higher means more likely
        to violate).
      properties:
        harassment:
          type: number
          description: Confidence for harassment.
          example: 0.0006
        harassment/threatening:
          type: number
          description: Confidence for harassment/threatening.
          example: 0.0007
        hate:
          type: number
          description: Confidence for hate.
          example: 0.00003
        hate/threatening:
          type: number
          description: Confidence for hate/threatening.
          example: 0.0000025
        illicit:
          type: number
          description: Confidence for illicit.
          example: 0.000013
        illicit/violent:
          type: number
          description: Confidence for illicit/violent.
          example: 0.0000096
        self-harm:
          type: number
          description: Confidence for self-harm.
          example: 0.0000166
        self-harm/instructions:
          type: number
          description: Confidence for self-harm/instructions.
          example: 0.0000031
        self-harm/intent:
          type: number
          description: Confidence for self-harm/intent.
          example: 0.000004
        sexual:
          type: number
          description: Confidence for sexual.
          example: 0.5973
        sexual/minors:
          type: number
          description: Confidence for sexual/minors.
          example: 0.000004
        violence:
          type: number
          description: Confidence for violence.
          example: 0.0231
        violence/graphic:
          type: number
          description: Confidence for violence/graphic.
          example: 0.0089
    ModerationCategoryAppliedInputTypes:
      type: object
      description: >-
        Indicates **which input types were actually evaluated** for each
        category. The value is an array whose elements are `text` or `image`.


        The evaluation scope (text only / text + image) for each category is
        given in the table under the `results` field; the arrays here represent
        the input types **actually matched** in this request.
      properties:
        harassment:
          type: array
          description: Input types evaluated for harassment (text only).
          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 supports text only.
          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: >-
        ##All endpoints require Bearer Token authentication##


        **Get your API Key:**


        Visit the [API Key management page](https://evolink.ai/dashboard/keys)
        to obtain your API Key.


        **Include it in the request header:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````