> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fish.audio/llms.txt
> Use this file to discover all available pages before exploring further.
# Text to Speech
> Convert text to speech
This endpoint only accepts `application/json` and `application/msgpack`.
For best results, upload reference audio using the [create model](/api-reference/endpoint/model/create-model) before using this one. This improves speech quality and reduces latency.
To upload audio clips directly, without pre-uploading, serialize the request body with MessagePack as per the [instructions](/features/text-to-speech#direct-api-messagepack).
Audio formats supported:
* WAV / PCM
* Sample Rate: 8kHz, 16kHz, 24kHz, 32kHz, 44.1kHz
* Default Sample Rate: 44.1kHz
* 16-bit, mono
* MP3
* Sample Rate: 32kHz, 44.1kHz
* Default Sample Rate: 44.1kHz
* mono
* Bitrate: 64kbps, 128kbps (default), 192kbps
* Opus
* Sample Rate: 48kHz
* Default Sample Rate: 48kHz
* mono
* Bitrate: -1000 (auto), 24kbps, 32kbps (default), 48kbps, 64kbps
## OpenAPI
````yaml post /v1/tts
openapi: 3.1.0
info:
title: FishAudio OpenAPI
version: '1'
servers:
- description: Fish Audio API
url: https://api.fish.audio
security: []
tags: []
paths:
/v1/tts:
post:
tags:
- OpenAPI v1
summary: Text to Speech
parameters:
- in: header
name: model
description: Specify which TTS model to use. We recommend `s2-pro`.
required: true
schema:
default: s2-pro
enum:
- s1
- s2-pro
title: Model
type: string
deprecated: false
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TTSRequest'
application/msgpack:
schema:
$ref: '#/components/schemas/TTSRequest'
responses:
'200':
description: Request fulfilled, document follows
headers:
Transfer-Encoding:
schema:
type: string
description: chunked
'401':
description: No permission -- see authorization schemes
headers: {}
content:
application/json:
schema:
properties:
status:
title: Status
type: integer
message:
title: Message
type: string
required:
- status
- message
type: object
'402':
description: No payment -- see charging schemes
headers: {}
content:
application/json:
schema:
properties:
status:
title: Status
type: integer
message:
title: Message
type: string
required:
- status
- message
type: object
'422':
description: ''
headers: {}
content:
application/json:
schema:
type: array
items:
type: object
properties:
loc:
title: Location
description: error field
type: array
items:
type: string
type:
title: Type
description: error type
type: string
msg:
title: Message
description: error message
type: string
ctx:
title: Context
description: error context
type: string
in:
title: In
type: string
enum:
- path
- query
- header
- cookie
- body
required:
- loc
- type
- msg
security:
- BearerAuth: []
x-codeSamples:
- lang: bash
label: Single Speaker
source: |-
curl --request POST \
--url https://api.fish.audio/v1/tts \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--header 'model: s2-pro' \
--data '{
"text": "Hello! Welcome to Fish Audio.",
"reference_id": "model-id",
"temperature": 0.7,
"top_p": 0.7,
"prosody": {
"speed": 1,
"volume": 0,
"normalize_loudness": true
},
"chunk_length": 300,
"normalize": true,
"format": "mp3",
"sample_rate": 44100,
"mp3_bitrate": 128,
"latency": "normal",
"max_new_tokens": 1024,
"repetition_penalty": 1.2,
"min_chunk_length": 50,
"condition_on_previous_chunks": true,
"early_stop_threshold": 1
}'
- lang: bash
label: Multi Speaker (S2-Pro only)
source: |-
curl --request POST \
--url https://api.fish.audio/v1/tts \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--header 'model: s2-pro' \
--data '{
"text": "<|speaker:0|>Hello!<|speaker:1|>Hi there!",
"reference_id": ["speaker-a-id", "speaker-b-id"],
"temperature": 0.7,
"top_p": 0.7,
"prosody": {
"speed": 1,
"volume": 0,
"normalize_loudness": true
},
"chunk_length": 300,
"normalize": true,
"format": "mp3",
"sample_rate": 44100,
"mp3_bitrate": 128,
"latency": "normal",
"max_new_tokens": 1024,
"repetition_penalty": 1.2,
"min_chunk_length": 50,
"condition_on_previous_chunks": true,
"early_stop_threshold": 1
}'
components:
schemas:
TTSRequest:
description: >-
Request body for text-to-speech synthesis. Supports single-speaker
synthesis on all compatible TTS models. Multi-speaker dialogue synthesis
is only available with the S2-Pro model.
## Single Speaker
Provide either `reference_id` (string) pointing to a voice model, or
`references` (array of ReferenceAudio) for zero-shot cloning.
## Multiple Speakers (Dialogue, S2-Pro only)
For multi-speaker synthesis, provide:
- `reference_id`: array of voice model IDs, e.g., ["speaker-0-id",
"speaker-1-id"]
- `text`: use speaker tags `<|speaker:0|>`, `<|speaker:1|>`, etc. to
indicate speaker changes, e.g., "<|speaker:0|>Hello!<|speaker:1|>Hi
there!"
Alternatively, for zero-shot multi-speaker:
- `references`: 2D array where each inner array contains references for
one speaker
- `reference_id`: array of identifiers (can be arbitrary strings for
zero-shot)
## Example (Multi-Speaker with Model IDs)
```json
{
"text": "<|speaker:0|>Good morning!<|speaker:1|>Good morning! How are you?<|speaker:0|>I'm great, thanks!",
"reference_id": ["model-id-alice", "model-id-bob"]
}
```
properties:
text:
description: Text to convert to speech.
title: Text
type: string
temperature:
default: 0.7
description: >-
Controls expressiveness. Higher is more varied, lower is more
consistent.
maximum: 1
minimum: 0
title: Temperature
type: number
top_p:
default: 0.7
description: Controls diversity via nucleus sampling.
maximum: 1
minimum: 0
title: Top P
type: number
references:
anyOf:
- description: 'Single speaker: array of reference audio samples'
items:
$ref: '#/components/schemas/ReferenceAudio'
type: array
- description: >-
Multiple speakers: array of arrays, where each inner array
contains reference samples for one speaker
items:
items:
$ref: '#/components/schemas/ReferenceAudio'
type: array
type: array
- type: 'null'
description: >-
Inline voice references for zero-shot cloning. Requires MessagePack
(not JSON). For single speaker, provide an array of ReferenceAudio
objects. For multiple speakers, provide an array of arrays where
each inner array contains references for one speaker.
**Multi-speaker is only available with the S2-Pro model.** The
speaker index corresponds to the index in reference_id array.
Example for multi-speaker: [[{audio, text}], [{audio, text}, {audio,
text}]] for 2 speakers where speaker 1 has 2 reference samples.
title: References
reference_id:
anyOf:
- description: 'Single speaker: voice model ID string'
type: string
- description: 'Multiple speakers: array of voice model IDs, one per speaker'
items:
type: string
type: array
- type: 'null'
default: null
description: >-
Voice model ID(s) from Fish Audio library or your custom models. For
single-speaker synthesis, provide a string. For multi-speaker
synthesis (dialogue), provide an array of model IDs. **Multi-speaker
is only available with the S2-Pro model.** When using multiple
speakers, use speaker tags in your text like `<|speaker:0|>` and
`<|speaker:1|>` to indicate speaker changes. Example:
`<|speaker:0|>Hello!<|speaker:1|>Hi there!<|speaker:0|>How are you?`
with `reference_id: ["speaker-a-id", "speaker-b-id"]`.
title: Reference Id
prosody:
anyOf:
- $ref: '#/components/schemas/ProsodyControl'
- type: 'null'
default: null
description: Speed and volume adjustments for the output.
chunk_length:
default: 300
description: Text segment size for processing.
maximum: 300
minimum: 100
title: Chunk Length
type: integer
normalize:
default: true
description: >-
Normalizes text for English and Chinese, improving stability for
numbers.
title: Normalize
type: boolean
format:
default: mp3
description: Output audio format.
enum:
- wav
- pcm
- mp3
- opus
title: Format
type: string
sample_rate:
anyOf:
- type: integer
- type: 'null'
default: null
description: >-
Audio sample rate in Hz. When null, uses the format's default (44100
Hz for most formats, 48000 Hz for opus).
title: Sample Rate
mp3_bitrate:
default: 128
description: MP3 bitrate in kbps. Only applies when format is mp3.
enum:
- 64
- 128
- 192
title: Mp3 Bitrate
type: integer
opus_bitrate:
default: -1000
description: >-
Opus bitrate in bps. -1000 for automatic. Only applies when format
is opus.
enum:
- -1000
- 24000
- 32000
- 48000
- 64000
title: Opus Bitrate
type: integer
latency:
default: normal
description: >-
Latency-quality trade-off. normal: best quality, balanced: reduced
latency, low: lowest latency.
enum:
- low
- normal
- balanced
title: Latency
type: string
max_new_tokens:
default: 1024
description: Maximum audio tokens to generate per text chunk.
title: Max New Tokens
type: integer
repetition_penalty:
default: 1.2
description: >-
Penalty for repeating audio patterns. Values above 1.0 reduce
repetition.
title: Repetition Penalty
type: number
min_chunk_length:
default: 50
description: Minimum characters before splitting into a new chunk.
maximum: 100
minimum: 0
title: Min Chunk Length
type: integer
condition_on_previous_chunks:
default: true
description: Use previous audio as context for voice consistency.
title: Condition On Previous Chunks
type: boolean
early_stop_threshold:
default: 1
description: Early stopping threshold for batch processing.
maximum: 1
minimum: 0
title: Early Stop Threshold
type: number
required:
- text
title: TTSRequest
type: object
ReferenceAudio:
description: >-
A voice sample with its transcript, used for zero-shot voice cloning.
The model will attempt to match the voice characteristics from the audio
sample.
properties:
audio:
description: >-
Raw audio bytes of the voice sample. Supported formats: WAV, MP3,
FLAC. For best results, use 10-30 seconds of clear speech with
minimal background noise.
format: binary
title: Audio
type: string
text:
description: >-
The exact transcript of what is spoken in the audio sample. Accuracy
is important for voice cloning quality.
title: Text
type: string
required:
- audio
- text
title: ReferenceAudio
type: object
ProsodyControl:
description: >-
Controls for adjusting the prosody (rhythm and intonation) of generated
speech.
properties:
speed:
default: 1
description: >-
Speaking rate multiplier. Valid range: 0.5 to 2.0. 1.0 = normal
speed, 0.5 = half speed, 2.0 = double speed. Useful for adjusting
pacing without regenerating audio.
title: Speed
type: number
volume:
default: 0
description: >-
Volume adjustment in decibels (dB). 0 = no change, positive values =
louder, negative values = quieter.
title: Volume
type: number
normalize_loudness:
default: true
description: >-
Normalize output loudness for more consistent perceived volume.
**S2-Pro only.**
title: Normalize Loudness
type: boolean
title: ProsodyControl
type: object
securitySchemes:
BearerAuth:
type: http
scheme: bearer
````