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

# chatterbox

> Model details for chatterbox. The original 0.5B ChatterboxTTS, with zero-shot voice cloning.

> [!NOTE]
>
> This model is routable only on `/v1/audio/speech`. To clone a voice, send
> `multipart/form-data` with a `voice_sample` file.

> Resemble AI's Chatterbox is the original 0.5B-parameter ChatterboxTTS model, the larger sibling of chatterbox-nano. It speaks your text in a built-in voice, or clones a speaker zero-shot from a short reference clip you upload with the request, and inline tags such as `[dramatic]`, `[sarcastic]`, and `[happy]` steer delivery. It runs on the same `POST /v1/audio/speech` endpoint, and its generated audio is billed per second, rounded up to the next whole second per request, rather than per whole minute.

**References:** [Model card](https://huggingface.co/ResembleAI/chatterbox) • [License](https://github.com/resemble-ai/chatterbox/blob/master/LICENSE) • [Terms](https://zerogpu.ai/terms) • [Privacy](https://zerogpu.ai/privacy-policy)

## Limits

| Limit | Value |
| - | - |
| `input` length | 2,000 characters. Requests near the limit can time out with `524`. |
| `voice_sample` duration | 6 to 30 seconds |
| `voice_sample` size | 10 MB |
| `voice_sample` formats | mp3, m4a, wav, flac, ogg, webm, mp4 |

Billing is per second of generated audio, rounded up to the next whole second per request, at \$0.015 per minute. See [Speech](https://docs.zerogpu.ai/api-reference/audio-speech.md) for the full field list.

```bash cURL (JSON) theme={null}
curl --location 'https://api.zerogpu.ai/v1/audio/speech' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
  "model": "chatterbox",
  "input": "[dramatic] Oh, another AI model that needs eight GPUs just to say hello? [sarcastic] How adorable. [shush] Do not tell anyone... [happy] I run on the edge.",
  "voice": "default",
  "response_format": "mp3",
  "seed": 42,
  "temperature": 0.8,
  "top_p": 0.95,
  "repetition_penalty": 1.2
}' \
  --output speech.mp3
```

```bash cURL (voice cloning) theme={null}
curl --location 'https://api.zerogpu.ai/v1/audio/speech' \
  --header 'x-api-key: YOUR_API_KEY' \
  --form 'model="chatterbox"' \
  --form 'input="Testing model to generate voice. Hey how are you today?"' \
  --form 'response_format="mp3"' \
  --form 'seed="42"' \
  --form 'voice_sample=@"/path/to/file"' \
  --output speech.mp3
```

```python Python theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.zerogpu.ai/v1",
    api_key="YOUR_API_KEY",  # sent as Authorization: Bearer
)

with client.audio.speech.with_streaming_response.create(
    model="chatterbox",
    voice="alloy",  # OpenAI voice names map to the built-in voice
    input="Hello from ZeroGPU.",
    response_format="mp3",
) as response:
    response.stream_to_file("speech.mp3")
```

```javascript JavaScript theme={null}
import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.zerogpu.ai/v1",
  apiKey: "YOUR_API_KEY", // sent as Authorization: Bearer
});

const speech = await client.audio.speech.create({
  model: "chatterbox",
  voice: "alloy", // OpenAI voice names map to the built-in voice
  input: "Hello from ZeroGPU.",
  response_format: "mp3",
});

fs.writeFileSync("speech.mp3", Buffer.from(await speech.arrayBuffer()));
```


## OpenAPI

````yaml api-reference/openapi/playgrounds/chatterbox.openapi.json POST /audio/speech
openapi: 3.1.0
info:
  title: chatterbox playground
  version: '1.0'
  description: >-
    Interactive playground for **chatterbox**.

    Model is always `chatterbox` on this page (shown in the form, not editable).

    Authentication: `x-api-key`, or the OpenAI-compatible `Authorization:
    Bearer` header.
servers:
  - url: https://api.zerogpu.ai/v1
    description: Production
security:
  - ApiKey: []
  - BearerAuth: []
paths:
  /audio/speech:
    post:
      tags:
        - chatterbox
      summary: 'chatterbox: Speech'
      operationId: createSpeech_chatterbox
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateSpeechMultipartRequest'
            example:
              model: chatterbox
              input: Testing model to generate voice. Hey how are you today?
              response_format: mp3
              seed: 42
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpeechRequest'
            example:
              model: chatterbox
              input: >-
                [dramatic] Oh, another AI model that needs eight GPUs just to
                say hello? [sarcastic] How adorable. [shush] Do not tell
                anyone... [happy] I run on the edge.
              voice: default
              response_format: mp3
              seed: 42
              temperature: 0.8
              top_p: 0.95
              repetition_penalty: 1.2
      responses:
        '200':
          description: The audio file, with a content type matching `response_format`.
          headers:
            x-audio-duration-seconds:
              description: >-
                Audio length in seconds: the uploaded audio for a transcription,
                the generated audio for speech.
              schema:
                type: number
          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':
          description: >-
            Bad request (invalid or missing field, or a body that is not the
            expected content type)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: '''input'' is required'
                  type: invalid_request_error
                  param: input
                  code: input_required
        '401':
          description: Unauthorized (missing API key). Plain-text body.
        '402':
          description: Insufficient quota (insufficient_quota)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: >-
                    You exceeded your current quota, please check your plan and
                    billing details.
                  type: insufficient_quota
                  param: null
                  code: insufficient_quota
        '403':
          description: Forbidden (invalid API key). Plain-text body.
        '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':
          description: Rate limit reached. Wait at least `Retry-After` seconds, then retry.
        '500':
          description: Internal server error
        '503':
          description: >-
            Model warming up (model_unavailable) or every slot busy
            (server_busy). Retry with backoff.
        '504':
          description: Generation timed out (timeout)
      security:
        - ApiKey: []
        - BearerAuth: []
components:
  schemas:
    CreateSpeechMultipartRequest:
      type: object
      required:
        - input
      description: Multipart form, required for voice cloning.
      properties:
        model:
          type: string
          const: chatterbox
          default: chatterbox
          example: chatterbox
          description: Model identifier (fixed for this playground).
        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
          const: chatterbox
          default: chatterbox
          example: chatterbox
          description: Model identifier (fixed for this playground).
        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.
    ErrorResponse:
      type: object
      additionalProperties: true
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        OpenAI-compatible: send your ZeroGPU API key as `Authorization: Bearer
        <key>`.

````

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