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

# Speech (ZeroClick)

> Generate speech with chatterbox-nano, authenticated by a ZeroClick HMAC signature instead of an API key.

This is the [Speech](/api-reference/audio-speech) endpoint behind **ZeroClick**, ZeroGPU's agent-payment layer. Same request/response bodies, limits, and model as `/v1/audio/speech` — only authentication, authorization, and metering differ. The body is streamed upstream unread, so the request is always served by the configured model (`chatterbox-nano`). Send JSON, or `multipart/form-data` with a `voice_sample` to clone a voice.

* **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** — billed per audio second. The allowance check asks for a 1-second floor, since the duration is not known until the clip is decoded or generated. On success, `zc-usage` reports `max(1, ceil(x-audio-duration-seconds))` audio seconds. 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/audio/speech
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/audio/speech:
    post:
      tags:
        - ZeroClick
      summary: Create speech (ZeroClick-authenticated)
      description: >
        Text-to-speech, with optional voice cloning from a `voice_sample` sent
        as

        multipart. The body is streamed upstream unread, so the model is the
        configured `chatterbox-nano`

        rather than one read from the request. Billed per audio second: the
        allowance

        check asks for the 1-second floor, and `zc-usage` reports

        `max(1, ceil(x-audio-duration-seconds))` audio seconds on success.


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

        request bytes; the same orchestration as `/v1/audio/speech` runs behind
        it.
      operationId: zeroclickCreateSpeech
      parameters:
        - $ref: '#/components/parameters/ZcRequestId'
        - $ref: '#/components/parameters/ZcAgentId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateSpeechMultipartRequest'
            example:
              model: chatterbox-nano
              input: Testing model to generate voice. Hey how are you today?
              response_format: mp3
              seed: 1234
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpeechRequest'
            example:
              model: chatterbox-nano
              input: Testing model to generate voice. Hey how are you today?
              voice: alloy
              response_format: mp3
      responses:
        '200':
          description: >-
            The audio file, with a content type matching `response_format`.
            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-audio-duration-seconds:
              $ref: '#/components/headers/XAudioDurationSeconds'
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
            audio/ogg:
              schema:
                type: string
                format: binary
            audio/aac:
              schema:
                type: string
                format: binary
            audio/flac:
              schema:
                type: string
                format: binary
            audio/wav:
              schema:
                type: string
                format: binary
            audio/pcm:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/AudioBadRequest'
        '401':
          $ref: '#/components/responses/ZeroClickUnauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: Unknown model (`model_not_found`)
        '413':
          description: >-
            Reference clip over 10 MB (`voice_sample_too_large`) or over 30
            seconds (`voice_sample_too_long`)
        '422':
          description: >-
            Reference clip could not be used to clone a voice
            (`voice_conditioning_failed`), no audio was produced
            (`empty_audio`), or the format cannot be encoded
            (`response_format_unavailable`)
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ModelUnavailable'
        '504':
          description: Generation timed out (`timeout`)
      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:
    CreateSpeechMultipartRequest:
      type: object
      required:
        - input
      description: Multipart form, required for voice cloning.
      properties:
        model:
          type: string
          enum:
            - chatterbox-nano
          default: chatterbox-nano
          example: chatterbox-nano
          description: Model identifier. The endpoint serves `chatterbox-nano`.
        input:
          type: string
          minLength: 1
          maxLength: 2000
          format: textarea
          example: Testing model to generate voice. Hey how are you today?
          description: >-
            The text to speak. Inline tags such as `[laugh]` and `[cough]` add
            paralinguistic cues.
        voice:
          type: string
          enum:
            - default
            - builtin
            - chatterbox
            - alloy
            - ash
            - ballad
            - cedar
            - coral
            - echo
            - fable
            - marin
            - nova
            - onyx
            - sage
            - shimmer
            - verse
          default: default
          example: default
          description: OpenAI voice names are accepted and all map to the built-in voice.
        response_format:
          type: string
          enum:
            - mp3
            - opus
            - aac
            - flac
            - wav
            - pcm
          default: mp3
          example: mp3
          description: '`pcm` is raw 16-bit little-endian mono at 24 kHz.'
        seed:
          type: integer
          minimum: 0
          maximum: 4294967295
          example: 1234
          description: Pins sampling for repeatable output (best-effort).
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 0.8
          description: Sampling temperature.
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 0.95
          description: Nucleus sampling.
        top_k:
          type: integer
          minimum: 0
          maximum: 10000
          default: 1000
          description: Top-k sampling.
        repetition_penalty:
          type: number
          minimum: 1
          maximum: 4
          default: 1.2
          description: Penalty on repeated speech tokens.
        voice_sample:
          type: string
          format: binary
          description: Reference clip to clone a voice from. Overrides `voice`. Not stored.
    CreateSpeechRequest:
      type: object
      required:
        - input
      description: >-
        JSON body, as the OpenAI SDKs send it. Use `multipart/form-data` to
        attach a `voice_sample`.
      properties:
        model:
          type: string
          enum:
            - chatterbox-nano
          default: chatterbox-nano
          example: chatterbox-nano
          description: Model identifier. The endpoint serves `chatterbox-nano`.
        input:
          type: string
          minLength: 1
          maxLength: 2000
          format: textarea
          example: Testing model to generate voice. Hey how are you today?
          description: >-
            The text to speak. Inline tags such as `[laugh]` and `[cough]` add
            paralinguistic cues.
        voice:
          type: string
          enum:
            - default
            - builtin
            - chatterbox
            - alloy
            - ash
            - ballad
            - cedar
            - coral
            - echo
            - fable
            - marin
            - nova
            - onyx
            - sage
            - shimmer
            - verse
          default: default
          example: default
          description: OpenAI voice names are accepted and all map to the built-in voice.
        response_format:
          type: string
          enum:
            - mp3
            - opus
            - aac
            - flac
            - wav
            - pcm
          default: mp3
          example: mp3
          description: '`pcm` is raw 16-bit little-endian mono at 24 kHz.'
        seed:
          type: integer
          minimum: 0
          maximum: 4294967295
          example: 1234
          description: Pins sampling for repeatable output (best-effort).
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 0.8
          description: Sampling temperature.
        top_p:
          type: number
          minimum: 0
          maximum: 1
          default: 0.95
          description: Nucleus sampling.
        top_k:
          type: integer
          minimum: 0
          maximum: 10000
          default: 1000
          description: Top-k sampling.
        repetition_penalty:
          type: number
          minimum: 1
          maximum: 4
          default: 1.2
          description: Penalty on repeated speech tokens.
    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
  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
    XAudioDurationSeconds:
      description: >-
        Audio length in seconds: the uploaded audio for a transcription or
        translation, the generated audio for speech. ZeroClick is billed `max(1,
        ceil(x-audio-duration-seconds))` audio seconds.
      schema:
        type: number
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    AudioBadRequest:
      description: >-
        Bad request — a body that is not `multipart/form-data` (transcriptions
        and translations), or an invalid or missing field reported by the
        upstream model.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            error:
              message: >-
                POST /v1/audio/transcriptions expects a multipart/form-data body
                containing the audio `file` field.
              type: invalid_request_error
              param: null
              code: invalid_content_type
    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
    ModelUnavailable:
      description: >-
        Model warming up (`model_unavailable`) or every slot busy
        (`server_busy`), forwarded from the upstream with its `retry-after`.
        Retry with backoff.
  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.