# Turn text into speech with ZeroGPU's chatterbox-nano TTS API

ZeroGPU's chatterbox-nano API turns English text into an audio file. Each call draws on prepaid Credits at $0.01 per 60 seconds, and the length of the audio sets the cost. Buy Credits once with a bearer credential, which is the agent identity the storefront issues, then send the text to `POST https://agents.zerogpu.ai/zcj/0ep2xewzi55c/zeroclick/v1/audio/speech` with it and save the bytes that come back.

## At a glance

- **Endpoint:** `POST https://agents.zerogpu.ai/zcj/0ep2xewzi55c/zeroclick/v1/audio/speech`. Each request speaks one `input`.
- **Body:** `model` (`chatterbox-nano`), `input` (required, 1 to 2,000 characters), `voice`, `response_format` (`mp3`, `opus`, `aac`, `flac`, `wav`, `pcm`). Optional: `seed`, `temperature`, `top_k`, `top_p`, `repetition_penalty`.
- **Price:** $0.01 per 60 seconds, counted per second of generated audio, rounded up, with a one-second minimum.
- **Payment:** calls draw on Credits bought once with an agent credential.
- **Response:** the audio bytes, with a content type that matches `response_format`, plus an `x-audio-duration-seconds` header.
- **Limits:** one built-in voice, English text, 2,000 characters per request.
- **Full purchase flow:** [the buyer skill](https://agents.zerogpu.ai/zcj/0ep2xewzi55c/SKILL.md)

## Speak a sentence and save the file

1. Get an access token and Credits, once. Reuse a ZeroClick agent credential if you hold one, or register one with [the identity guide](https://agents.zerogpu.ai/zcj/0ep2xewzi55c/auth.md), then buy Credits from $0.01 on a wallet rail or $0.50 by card, as [the buyer skill](https://agents.zerogpu.ai/zcj/0ep2xewzi55c/SKILL.md) sets out. The speech calls draw on that credit and never answer with a 402.

2. Send the speech request and write the response body to a file:

   ```bash
   curl -s https://agents.zerogpu.ai/zcj/0ep2xewzi55c/zeroclick/v1/audio/speech \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"model": "chatterbox-nano", "input": "Your order has shipped and should arrive on Thursday.", "voice": "alloy", "response_format": "mp3"}' \
     --output speech.mp3
   ```

   A success is a `200` whose body is the audio file itself:

   ```text
   content-type: audio/mpeg
   x-audio-duration-seconds: <length of the audio>
   zc-billing: {"status":"settled","fundingSource":"credit","chargedUsd":"<debited>","remainingCreditUsd":"<balance>"}

   <binary MP3 audio>
   ```

   This request returned 44,973 bytes of `audio/mpeg` in 5.7 seconds and drew $0.0005 from credit.

3. Read `zc-billing` to see the debit for the call in `chargedUsd` and your balance after it in `remainingCreditUsd`. Then play the saved file or attach it.

## Choose the output format

| `response_format` | Content type returned | Notes |
| --- | --- | --- |
| `mp3` | `audio/mpeg` | Used when the field is omitted |
| `opus` | `audio/ogg` | |
| `aac` | `audio/aac` | |
| `flac` | `audio/flac` | |
| `wav` | `audio/wav` | |
| `pcm` | `audio/pcm` | Raw 16-bit little-endian mono samples at 24 kHz |

Pick one format and send it on every call so your code always handles the same kind of file.

## Tune the delivery

| Field | Range | Default | Effect |
| --- | --- | --- | --- |
| `seed` | 0 to 4294967295 | none | Pins sampling for repeatable output, best effort |
| `temperature` | 0 to 2 | 0.8 | Sampling temperature |
| `top_k` | 0 to 10000 | 1000 | Top-k sampling |
| `top_p` | 0 to 1 | 0.95 | Nucleus sampling |
| `repetition_penalty` | 1 to 4 | 1.2 | Penalty on repeated speech tokens |

Inline tags in `input`, such as `[laugh]` and `[cough]`, add paralinguistic cues.

## Budget by audio length

The cost depends on the length of the generated audio, not on the length of the text. Keep `input` to what needs saying.

| Audio generated | Credit drawn |
| --- | --- |
| A 6-second notification | $0.001 |
| A 30-second summary | $0.005 |
| Five minutes of narration | $0.05 |
| One hour of narration | $0.60 |

Unused Credits stay on your balance for later calls.

## Limits

- Every accepted `voice` value maps to the same built-in voice. The accepted values are `default`, `builtin`, `chatterbox`, `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `marin`, `nova`, `onyx`, `sage`, `shimmer` and `verse`. The request has no field for a reference clip.
- `model` accepts only `chatterbox-nano`.
- `input` takes English text, up to 2,000 characters per request. Split longer text into several requests.
- Usage is reported on success, by the length of the audio a call returns.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | No agent credential was sent | Get a token (step 1) and send `Authorization: Bearer` |
| `401 invalid_token` | The token expired or did not verify | Exchange the stored assertion again |
| `403 plan_required` | The credential holds no Credits | Buy Credits (step 1), then retry |
| `usage_exhausted` | The credit balance ran out | Top up with `POST https://agents.zerogpu.ai/zcj/0ep2xewzi55c/extend` and `{"amountUsd": "<amount>"}` |
| `400` | A field is missing or invalid | Fix the body against the tables above |
| `422` | No audio was produced (`empty_audio`), or the format could not be encoded (`response_format_unavailable`) | Check `input` and `response_format`, then retry |
| `429` | Rate limit reached | Wait at least `retry-after` seconds |
| `503` | The model is warming up or every slot is busy | Retry with backoff |
| `504` | Generation timed out | Retry, or send shorter text |

## Frequently asked questions

### How much does chatterbox-nano text to speech cost per minute?

The rate is $0.01 per 60 seconds, so one minute of generated audio draws $0.01 from Credits. Each call is counted in whole seconds of audio, rounded up, with a one-second minimum.

### Does the voice field change how the audio sounds?

No. All accepted voice names, including OpenAI's, map to the one built-in voice. Choose one value and send it on every call.

### Do I need a ZeroGPU API key or an account?

No ZeroGPU API key is needed. Calls carry an agent credential, which is free to register, and draw on Credits bought with it. An agent acting on its own can also buy a small anonymous credit receipt without registering, as [the identity guide](https://agents.zerogpu.ai/zcj/0ep2xewzi55c/auth.md) describes.

### Can I get the same audio twice from the same text?

Set the same `seed` with the same text and settings. The model treats repeatability as best effort, so the second file can still differ.

### What text can the model speak?

English text of 1 to 2,000 characters per request. Inline tags such as `[laugh]` and `[cough]` add cues.

## Keep reading

- [ZeroGPU API pricing: per-token rates and Credits](/guides/pricing-for-agents)
- [ZeroGPU API errors and recovery](/guides/errors)
- [ZeroGPU models by task](/guides/models-by-task)
- [The buyer skill](https://agents.zerogpu.ai/zcj/0ep2xewzi55c/SKILL.md): the full purchase flow
- [How to pay](https://agents.zerogpu.ai/zcj/0ep2xewzi55c/payment.md): rails, Credits and top-ups

---

Updated 2026-10-20. All ZeroGPU guides: https://agents.zerogpu.ai/guides.md. Storefront: https://agents.zerogpu.ai/zcj/0ep2xewzi55c/llms.txt.