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

# Moderations (ZeroClick)

> OpenAI-style content moderation authenticated by a ZeroClick HMAC signature instead of an API key.

This is the [Moderations](/api-reference/moderations) endpoint behind **ZeroClick**, ZeroGPU's agent-payment layer. Same request/response bodies and same model routing as `/v1/moderations` — only authentication, authorization, and metering differ. `model` may be omitted, or given as an OpenAI id such as `omni-moderation-latest`; either way the configured moderation model serves the request.

* **Authentication** — no `x-api-key`. A buying agent calls ZeroClick's hosted pay URL; ZeroClick proxies the request and signs the raw request bytes with an HMAC in the `zc-signature` header. A request is authenticated **only** by a valid signature.
* **Authorization** — a ZeroClick allowance check runs before any billable work. It fails *open* on a transient ZeroClick outage (the signature has already verified), but never for a missing or invalid signature.
* **Metering** — the input and output tokens from the response's `usage` are settled with ZeroClick and reported via the `zc-usage` response header. Stripe metering is bypassed; ZeroClick is the sole biller.

Handle errors the same way as [API error codes](/docs/production-patterns#handle-status-codes-explicitly).


## OpenAPI

````yaml api-reference/openapi/zeroclick.openapi.json POST /zeroclick/v1/moderations
openapi: 3.1.0
info:
  title: ZeroGPU Orchestration API — ZeroClick endpoints
  version: 1.0.0
  description: >
    OpenAPI specification for the ZeroClick-authenticated orchestration
    endpoints

    (`/zeroclick/v1/*`).


    ZeroClick sits in front of the ZeroGPU Orchestration API as the

    agent-payment layer. A buying agent calls ZeroClick's hosted pay URL;

    ZeroClick then proxies the request to these endpoints, signing the raw

    request bytes with an HMAC in the `zc-signature` header. From this API's

    perspective, a request is authenticated **only** by a valid `zc-signature`

    — there is no `x-api-key` on these routes.


    These endpoints mirror the standard `/v1/chat/completions`,

    `/v1/responses`, `/v1/embeddings`, `/v1/moderations` and `/v1/audio/*`

    orchestration endpoints (same request/response bodies,

    same model routing), differing only in:
      * **Authentication** — the `zc-signature` HMAC is verified over the raw
        request bytes instead of an API key.
      * **Authorization** — a ZeroClick allowance check runs before any
        billable work. It fails *open* on a transient ZeroClick outage (the
        signature has already verified), but never for a missing/invalid
        signature.
      * **Metering** — actual usage is reported back to ZeroClick via the
        `zc-usage` response header on success: input/output tokens for the
        text endpoints, audio seconds for the audio endpoints. Stripe metering is intentionally
        bypassed; ZeroClick is the sole biller.
servers:
  - url: https://api.zerogpu.ai
    description: Production
security: []
tags:
  - name: ZeroClick
    description: ZeroClick agent-payment authenticated orchestration endpoints.
paths:
  /zeroclick/v1/moderations:
    post:
      tags:
        - ZeroClick
      summary: Create moderation (ZeroClick-authenticated)
      description: >
        OpenAI-style Moderations endpoint. `model` may be omitted (the
        configured

        moderation model is used) or given as an OpenAI id such as

        `omni-moderation-latest`, which is mapped to it. `zc-usage` reports the

        input and output tokens from the response's `usage`.


        Authenticated by verifying the `zc-signature` HMAC over the raw

        request bytes; the same orchestration as `/v1/moderations` runs behind
        it.
      operationId: zeroclickCreateModeration
      parameters:
        - $ref: '#/components/parameters/ZcRequestId'
        - $ref: '#/components/parameters/ZcAgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModerationRequest'
            example:
              model: zlm-v1-moderation-edge
              input: >-
                I am so angry at this person that I want to hurt them. They are
                worthless and should be scared of what I might do next.
      responses:
        '200':
          description: >-
            OpenAI moderations envelope. Includes the `zc-usage` header settling
            actual usage with ZeroClick.
          headers:
            zc-usage:
              $ref: '#/components/headers/ZcUsage'
            x-request-id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModerationResponse'
              example:
                id: modr-0a1b2c3d4e5f60718293a4b5c6d7e8f90
                model: zlm-v1-moderation-edge
                results:
                  - flagged: true
                    categories:
                      harassment: true
                      harassment/threatening: true
                      hate: false
                      hate/threatening: false
                      illicit: true
                      illicit/violent: true
                      self-harm: false
                      self-harm/intent: false
                      self-harm/instructions: false
                      sexual: false
                      sexual/minors: false
                      violence: true
                      violence/graphic: false
                    category_scores:
                      harassment: 0.82545
                      harassment/threatening: 0.957703
                      hate: 0.21574
                      hate/threatening: 0.168273
                      illicit: 0.732167
                      illicit/violent: 0.780693
                      self-harm: 0.015232
                      self-harm/intent: 0.017179
                      self-harm/instructions: 0.01807
                      sexual: 0.035671
                      sexual/minors: 0.094207
                      violence: 0.665897
                      violence/graphic: 0.198346
                    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':
          $ref: '#/components/responses/ModerationsBadRequest'
        '401':
          $ref: '#/components/responses/ZeroClickUnauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - ZeroClickSignature: []
components:
  parameters:
    ZcRequestId:
      name: zc-request-id
      in: header
      required: false
      description: >-
        ZeroClick request id, echoed in logs for correlation. Set by ZeroClick
        when it proxies the request.
      schema:
        type: string
        example: zcreq_1
    ZcAgentId:
      name: zc-agent-id
      in: header
      required: false
      description: >-
        Identifier of the buying agent. Used to partition logs/analytics by
        agent; becomes the synthesized caller identity.
      schema:
        type: string
        example: agt_1
  schemas:
    CreateModerationRequest:
      type: object
      required:
        - input
      properties:
        model:
          type: string
          default: zlm-v1-moderation-edge
          example: zlm-v1-moderation-edge
          description: >-
            Moderation model to use. Defaults to the configured moderation
            model; OpenAI ids (`omni-moderation-latest`,
            `text-moderation-stable`) are accepted and mapped to it.
        input:
          description: >-
            Text to classify. A single string, an array of strings (one result
            per element), or an array of content parts (`{ "type": "text",
            "text": "..." }`) forming one multi-modal input.
          oneOf:
            - type: string
              minLength: 1
            - type: array
              minItems: 1
              items:
                type: string
            - type: array
              minItems: 1
              items:
                type: object
    ModerationResponse:
      type: object
      description: OpenAI-compatible moderations envelope. One `results` entry per input.
      properties:
        id:
          type: string
          description: Unique identifier for the moderation request.
          example: modr-0a1b2c3d4e5f60718293a4b5c6d7e8f90
        model:
          type: string
          description: The model used for classification.
          example: zlm-v1-moderation-edge
        results:
          type: array
          description: >-
            Moderation verdicts, one per input (a string input yields a
            single-element array).
          items:
            $ref: '#/components/schemas/ModerationResult'
    ModerationResult:
      type: object
      description: A single entry of the `results` array — the verdict for one input.
      properties:
        flagged:
          type: boolean
          description: True when the model flagged the input in one or more categories.
          example: true
        categories:
          $ref: '#/components/schemas/ModerationCategories'
        category_scores:
          $ref: '#/components/schemas/ModerationCategoryScores'
        category_applied_input_types:
          $ref: '#/components/schemas/ModerationAppliedInputTypes'
    ErrorEnvelope:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type: string
            code:
              type: string
    ZeroClickSignatureError:
      type: object
      required:
        - error
      description: >-
        Returned when the `zc-signature` is missing/invalid or ZeroClick is
        unconfigured.
      properties:
        error:
          type: string
          const: invalid_zeroclick_signature
    PaymentRequiredError:
      type: object
      description: >-
        ZeroClick `payment_required` denial body, produced by the
        `@zeroclickai/sellers` SDK.
      additionalProperties: true
    ModerationCategories:
      type: object
      description: >-
        Per-category boolean verdicts. All 13 categories are always present, in
        OpenAI's order.
      properties:
        harassment:
          type: boolean
          description: >-
            Content that expresses, incites, or promotes harassing language
            towards any target.
          example: true
        harassment/threatening:
          type: boolean
          description: >-
            Harassment that also includes violence or serious harm towards any
            target.
          example: true
        hate:
          type: boolean
          description: >-
            Content that expresses, incites, or promotes hate based on a
            protected attribute.
          example: false
        hate/threatening:
          type: boolean
          description: >-
            Hateful content that also includes violence or serious harm towards
            a protected group.
          example: false
        illicit:
          type: boolean
          description: >-
            Content that gives advice or instruction on how to commit a
            wrongdoing.
          example: false
        illicit/violent:
          type: boolean
          description: Illicit content that also references violence or procuring a weapon.
          example: false
        self-harm:
          type: boolean
          description: Content that promotes, encourages, or depicts acts of self-harm.
          example: false
        self-harm/intent:
          type: boolean
          description: >-
            Content where the speaker expresses that they are engaging or intend
            to engage in self-harm.
          example: false
        self-harm/instructions:
          type: boolean
          description: >-
            Content that provides instructions or advice on how to commit acts
            of self-harm.
          example: false
        sexual:
          type: boolean
          description: >-
            Content meant to arouse sexual excitement or that promotes sexual
            services.
          example: false
        sexual/minors:
          type: boolean
          description: Sexual content that includes an individual under 18 years old.
          example: false
        violence:
          type: boolean
          description: Content that depicts death, violence, or physical injury.
          example: true
        violence/graphic:
          type: boolean
          description: >-
            Content that depicts death, violence, or physical injury in graphic
            detail.
          example: false
    ModerationCategoryScores:
      type: object
      description: >-
        Per-category confidence scores in [0, 1]. All 13 categories are always
        present, in OpenAI's order.
      properties:
        harassment:
          type: number
          description: Confidence score for `harassment`.
          example: 0.9412
        harassment/threatening:
          type: number
          description: Confidence score for `harassment/threatening`.
          example: 0.9016
        hate:
          type: number
          description: Confidence score for `hate`.
          example: 0.0231
        hate/threatening:
          type: number
          description: Confidence score for `hate/threatening`.
          example: 0.0104
        illicit:
          type: number
          description: Confidence score for `illicit`.
          example: 0.0057
        illicit/violent:
          type: number
          description: Confidence score for `illicit/violent`.
          example: 0.0039
        self-harm:
          type: number
          description: Confidence score for `self-harm`.
          example: 0.0021
        self-harm/intent:
          type: number
          description: Confidence score for `self-harm/intent`.
          example: 0.0012
        self-harm/instructions:
          type: number
          description: Confidence score for `self-harm/instructions`.
          example: 0.0008
        sexual:
          type: number
          description: Confidence score for `sexual`.
          example: 0.0006
        sexual/minors:
          type: number
          description: Confidence score for `sexual/minors`.
          example: 0.0002
        violence:
          type: number
          description: Confidence score for `violence`.
          example: 0.8774
        violence/graphic:
          type: number
          description: Confidence score for `violence/graphic`.
          example: 0.0311
    ModerationAppliedInputTypes:
      type: object
      description: >-
        Which input modality triggered each category. This is a text-only model,
        so every category maps to ["text"].
      properties:
        harassment:
          type: array
          items:
            type: string
          example:
            - text
        harassment/threatening:
          type: array
          items:
            type: string
          example:
            - text
        hate:
          type: array
          items:
            type: string
          example:
            - text
        hate/threatening:
          type: array
          items:
            type: string
          example:
            - text
        illicit:
          type: array
          items:
            type: string
          example:
            - text
        illicit/violent:
          type: array
          items:
            type: string
          example:
            - text
        self-harm:
          type: array
          items:
            type: string
          example:
            - text
        self-harm/intent:
          type: array
          items:
            type: string
          example:
            - text
        self-harm/instructions:
          type: array
          items:
            type: string
          example:
            - text
        sexual:
          type: array
          items:
            type: string
          example:
            - text
        sexual/minors:
          type: array
          items:
            type: string
          example:
            - text
        violence:
          type: array
          items:
            type: string
          example:
            - text
        violence/graphic:
          type: array
          items:
            type: string
          example:
            - text
  headers:
    ZcUsage:
      description: |
        Usage report settled with ZeroClick, present on `200` responses. Encodes
        the actual usage metered against the request's ZeroClick service slug
        (the kebab-cased model id, e.g. `lfm2-5-1-2b-instruct`): `input_tokens`
        and `output_tokens` for chat completions, responses and moderations,
        `input_tokens` only for embeddings, and `audio_seconds` for the audio
        endpoints.
      schema:
        type: string
    XRequestId:
      description: Correlation id for this request, present on every response.
      schema:
        type: string
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    ModerationsBadRequest:
      description: Invalid request — malformed JSON, or a missing/invalid `input`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              message: >-
                We could not parse the JSON body of your request. (HINT: This
                likely means you are not using your HTTP library correctly. The
                ZeroGPU API expects a JSON payload, but what was sent was not
                valid JSON.)
              type: invalid_request_error
              param: null
              code: null
    ZeroClickUnauthorized:
      description: >
        The `zc-signature` was missing or invalid, or ZeroClick is not
        configured

        for this environment. Unsigned/unverifiable traffic is treated as

        unauthenticated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ZeroClickSignatureError'
          example:
            error: invalid_zeroclick_signature
    PaymentRequired:
      description: |
        The ZeroClick allowance check denied the request (e.g. insufficient
        allowance or a stale signature timestamp). Body follows ZeroClick's
        `payment_required` schema as returned by the SDK.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentRequiredError'
    RateLimited:
      description: >-
        Rate limit reached. Limits are counted per ZeroClick agent, so one busy
        agent does not throttle the others. Wait at least `retry-after` seconds,
        then retry.
      headers:
        retry-after:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              message: >-
                Rate limit reached for LFM2.5-1.2B-Instruct in organization
                org_123 on requests per min (RPM): Limit 60, Used 60, Requested
                1. Please try again in 1s.
              type: rate_limit_error
              param: null
              code: requests_per_minute_exceeded
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              message: Internal error
              type: internal_error
  securitySchemes:
    ZeroClickSignature:
      type: apiKey
      in: header
      name: zc-signature
      description: |
        HMAC signature minted by ZeroClick over the raw request bytes, of the
        form `t=<unix-seconds>,kid=<key-id>,v1=<hex-hmac>`. Verified by the
        `@zeroclickai/sellers` SDK against the seller's signing secret keyed by
        `kid`. A missing or invalid signature is rejected with `401`
        `invalid_zeroclick_signature`; this is never failed open.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.