> ## 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.

# Responses (ZeroClick)

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

This is the [Responses](/api-reference/responses) endpoint behind **ZeroClick**, ZeroGPU's agent-payment layer. Same request/response bodies and same model routing as `/v1/responses` — only authentication, authorization, and metering differ.

* **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** — actual token usage is settled with ZeroClick and reported via the `zc-usage` response header. Stripe metering is bypassed; ZeroClick is the sole biller.

The `input` and `output` shapes vary by model; open a [model page](/api-reference/models) for a prefilled playground. 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/responses
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` and

    `/v1/responses` 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 token usage is reported back to ZeroClick via the
        `zc-usage` response header on success. 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/responses:
    post:
      tags:
        - ZeroClick
      summary: Create a response (ZeroClick-authenticated)
      description: |
        OpenAI-style Responses endpoint, authenticated by verifying the
        `zc-signature` HMAC over the raw request bytes. The request is routed by
        `model` using model metadata, and the same orchestration as
        `/v1/responses` runs behind it.

        On success, actual token usage is settled with ZeroClick and reported
        via the `zc-usage` response header.
      operationId: zeroclickCreateResponse
      parameters:
        - $ref: '#/components/parameters/ZcRequestId'
        - $ref: '#/components/parameters/ZcAgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
            examples:
              basic:
                summary: Basic responses request
                value:
                  model: LFM2.5-1.2B-Instruct
                  instructions: You are a concise assistant.
                  input: 'Summarize the following article: ...'
      responses:
        '200':
          description: >-
            OpenAI Responses `response` object. Includes the `zc-usage` header
            settling actual usage with ZeroClick.
          headers:
            zc-usage:
              $ref: '#/components/headers/ZcUsage'
            x-request-id:
              $ref: '#/components/headers/XRequestId'
            x-inference-type:
              $ref: '#/components/headers/XInferenceType'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesResponse'
        '400':
          $ref: '#/components/responses/ResponsesBadRequest'
        '401':
          $ref: '#/components/responses/ZeroClickUnauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '420':
          $ref: '#/components/responses/ResponsesContextLengthExceeded'
        '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:
    ResponsesRequest:
      type: object
      required:
        - model
        - input
      additionalProperties: true
      properties:
        model:
          type: string
          example: LFM2.5-1.2B-Instruct
        input:
          type: string
          description: >-
            Prompt text. Combined with `instructions` (as a system message) to
            form the model input.
        instructions:
          type: string
          description: >-
            System-style instructions prepended to the input. Classification
            models may pass comma-separated or bracketed candidate labels here.
        max_output_tokens:
          type: integer
          nullable: true
        parallel_tool_calls:
          type: boolean
          default: true
        previous_response_id:
          type: string
          nullable: true
        store:
          type: boolean
          default: true
        temperature:
          type: number
          nullable: true
        top_p:
          type: number
          nullable: true
        truncation:
          type: string
          enum:
            - auto
            - disabled
          default: auto
        categories:
          type: array
          description: Candidate labels for text-classification models.
          items:
            type: string
        multilingual:
          type: boolean
        metadata:
          type: object
          description: >-
            Up to 16 string key/value pairs echoed back in the response
            envelope. Also carries GLiNER usecase options (`usecase`, `schema`,
            `labels`, `threshold`, `mask`, `replacement_char`), which are
            consumed and not necessarily echoed.
          additionalProperties:
            type: string
        text:
          type: object
          properties:
            format:
              type: object
              properties:
                type:
                  type: string
                  description: >-
                    Output format. `text` is supported; `json` is currently
                    rejected.
                  enum:
                    - text
    ResponsesResponse:
      type: object
      description: >-
        OpenAI Responses `response` object. On error, `status` is `failed` and
        `error` is populated.
      properties:
        id:
          type: string
        object:
          type: string
          const: response
        created_at:
          type: integer
        status:
          type: string
          enum:
            - completed
            - failed
        completed_at:
          type: integer
          nullable: true
        error:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ResponsesError'
        incomplete_details:
          nullable: true
        instructions:
          type: string
          nullable: true
        max_output_tokens:
          type: integer
          nullable: true
        model:
          type: string
        output:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                const: message
              id:
                type: string
              status:
                type: string
              role:
                type: string
                const: assistant
              content:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      const: output_text
                    text:
                      type: string
                    annotations:
                      type: array
                      items: {}
        parallel_tool_calls:
          type: boolean
        previous_response_id:
          type: string
          nullable: true
        reasoning:
          type: object
          properties:
            effort:
              nullable: true
            summary:
              nullable: true
        store:
          type: boolean
        temperature:
          type: number
          nullable: true
        text:
          type: object
          properties:
            format:
              type: object
              properties:
                type:
                  type: string
        tool_choice:
          type: string
        tools:
          type: array
          items: {}
        top_p:
          type: number
          nullable: true
        truncation:
          type: string
          enum:
            - auto
            - disabled
        usage:
          $ref: '#/components/schemas/ResponsesUsage'
        user:
          type: string
          nullable: true
        metadata:
          type: object
          additionalProperties:
            type: string
      additionalProperties: true
    ResponsesError:
      type: object
      required:
        - message
      description: |
        Error attached to a Responses envelope. OpenAI's ResponseError carries
        `code` and `message`; `type` and `param` are also emitted by some error
        sites on this endpoint.
      properties:
        type:
          type: string
        message:
          type: string
        param:
          type: string
        code:
          type: string
    ResponsesUsage:
      type: object
      nullable: true
      properties:
        input_tokens:
          type: integer
        input_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
        output_tokens:
          type: integer
        output_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
        total_tokens:
          type: integer
    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
    ErrorEnvelope:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type: string
            code:
              type: string
  headers:
    ZcUsage:
      description: |
        Usage report settled with ZeroClick, present on `200` responses. Encodes
        the actual `input_tokens` and `output_tokens` metered against the
        request's ZeroClick service slug.
      schema:
        type: string
    XRequestId:
      description: Correlation id for this request, present on every response.
      schema:
        type: string
    XInferenceType:
      description: >-
        Where inference executed (e.g. `cloud` or an on-device route). Absent
        when inference ran neither on the edge nor in the cloud.
      schema:
        type: string
  responses:
    ResponsesBadRequest:
      description: >-
        Invalid request — malformed JSON, or a missing/invalid required field
        such as `model` or `input`. Errors use the Responses error envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponsesResponse'
    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'
    ResponsesContextLengthExceeded:
      description: >-
        Input token count exceeds the resolved model's `max_tokens` and the
        model is configured to error rather than truncate. Returned in the
        Responses error envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponsesResponse'
    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.

````