> ## 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
> Generate speech from text with chatterbox-nano, with optional voice cloning from a reference clip.
## Limits
| Limit | Value |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| `input` length | 2,000 characters, English only. 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 |
| Unsupported parameters | `instructions`, `exaggeration`, `cfg_weight`, `min_p`, and `speed` other than `1.0` return `400` |
```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-nano"' \
--form 'input="Testing model to generate voice. Hey how are you today?"' \
--form 'response_format="mp3"' \
--form 'seed="1234"' \
--form 'voice_sample=@"/path/to/file"' \
--output speech.mp3
```
```bash cURL (JSON) theme={null}
curl --location 'https://api.zerogpu.ai/v1/audio/speech' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
"model": "chatterbox-nano",
"input": "Hello from ZeroGPU.",
"voice": "alloy",
"response_format": "mp3"
}' \
--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-nano",
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-nano",
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()));
```
```text 200 theme={null}
HTTP/2 200
content-type: audio/mpeg
x-audio-duration-seconds: 1.76
```
## OpenAPI
````yaml api-reference/openapi/zerogpu.openapi.json POST /audio/speech
openapi: 3.1.0
info:
title: ZeroGPU API
version: '1.0'
description: >-
REST API for ZeroGPU model inference: `POST /v1/responses` and `POST
/v1/chat/completions` (model-dependent).
Authentication uses the `x-api-key` header on every request. The
`x-project-id` header is optional.
Documentation: https://docs.zerogpu.ai
**Per-model playgrounds** are listed on [Model
playgrounds](/api-reference/models) with request examples for each model's
use cases.
These endpoint pages show a generic shape only.
servers:
- url: https://api.zerogpu.ai/v1
description: Production
security:
- ApiKey: []
paths:
/audio/speech:
post:
tags:
- Audio
summary: Create speech
operationId: createSpeech
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`.
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
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.
ErrorResponse:
type: object
description: Error payload returned on a failed request.
properties:
error:
type: object
properties:
code:
type: string
description: Machine-readable error code, for example `insufficient_quota`.
example: insufficient_quota
message:
type: string
description: Human-readable description of the error.
example: You have insufficient quota to complete this request.
securitySchemes:
ApiKey:
type: apiKey
in: header
name: x-api-key
description: >-
Your ZeroGPU API key. Create one in the dashboard under API keys. Send
it on every request.
BearerAuth:
type: http
scheme: bearer
description: >-
OpenAI-compatible: send your ZeroGPU API key as `Authorization: Bearer
`.
````