> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slng.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Fish Audio TTS Drama 3
> Synthesize directed speech with Fish Audio Drama 3 over one-shot HTTP. Returns binary audio in the requested format.
Direct the performance in plain language inside square brackets, such as `[breathless, urgent]` or `[voice drops to a terrified whisper]`. A direction applies from where it appears, so one line can change tone partway through. Paired tags such as `...` or `...` change only the words they wrap, and markers such as `[sigh]`, `[laugh]` or `[pause]` place a sound or pause exactly where you put it.
For a multi-speaker scene, start each line with `<|speaker:N|>` and pass `reference_id` as an array with one voice ID per speaker, in speaker order. Every speaker keeps their own voice across the scene.
```json
{
"text": "<|speaker:0|>You were there that night.<|speaker:1|>[defensive] I was home. [pause] Asleep.",
"reference_id": ["9a9cf47702da476aa4629e2506d4a857", "fbe02f8306fc4d3d915e9871722a39d5"],
"format": "mp3"
}
```
**Hosting: routed through SLNG (Fish Audio).** This model runs on Fish Audio's servers; SLNG proxies each request through the regional gateway you call. Available in United States (East, West). Send requests to your region's gateway base URL: `https://us-east.api.slng.ai`, `https://us-west.api.slng.ai`.
## OpenAPI
````yaml api-reference/openapi/tts-fish.oas.yaml POST /v1/tts/fish/tts:drama-3
openapi: 3.0.3
info:
title: SLNG Gateway API - Fish Audio TTS
version: 0.1.0
description: Unified API for speech-to-text and text-to-speech services.
contact:
name: SLNG Support
email: support@slng.ai
servers:
- url: https://us-east.api.slng.ai
description: 'Regional gateway: United States (East) (us-east)'
- url: https://us-west.api.slng.ai
description: 'Regional gateway: United States (West) (us-west)'
security:
- BearerAuth: []
tags:
- name: Fish Audio TTS S2 Pro
description: Fish Audio TTS S2 Pro over one-shot HTTP and MessagePack WebSocket.
- name: Fish Audio TTS S2.1 Pro
description: Fish Audio TTS S2.1 Pro over one-shot HTTP and MessagePack WebSocket.
- name: Fish Audio TTS Drama 3
description: >-
Fish Audio TTS Drama 3, directable expressive speech and multi-speaker
dialogue over one-shot HTTP and MessagePack WebSocket.
paths:
/v1/tts/fish/tts:drama-3:
post:
tags:
- Fish Audio TTS Drama 3
summary: Fish Audio TTS Drama 3
description: >
Synthesize directed speech with Fish Audio Drama 3 over one-shot HTTP.
Returns binary audio in the requested format.
Direct the performance in plain language inside square brackets, such as
`[breathless, urgent]` or `[voice drops to a terrified whisper]`. A
direction applies from where it appears, so one line can change tone
partway through. Paired tags such as `...` or
`...` change only the words they wrap, and markers
such as `[sigh]`, `[laugh]` or `[pause]` place a sound or pause exactly
where you put it.
For a multi-speaker scene, start each line with `<|speaker:N|>` and pass
`reference_id` as an array with one voice ID per speaker, in speaker
order. Every speaker keeps their own voice across the scene.
```json
{
"text": "<|speaker:0|>You were there that night.<|speaker:1|>[defensive] I was home. [pause] Asleep.",
"reference_id": ["9a9cf47702da476aa4629e2506d4a857", "fbe02f8306fc4d3d915e9871722a39d5"],
"format": "mp3"
}
```
operationId: fish/tts:drama-3
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FishTtsRequest'
examples:
directed:
summary: Directed synthesis
value:
text: >-
[breathless, urgent] Turn off the lights. [slow, deadly
serious] Do not open that door.
reference_id: 9a9cf47702da476aa4629e2506d4a857
format: mp3
application/msgpack:
schema:
$ref: '#/components/schemas/FishTtsRequest'
examples:
cloning:
summary: Synthesis with inline reference audio (MessagePack only)
value:
text: '[warmly] Hello from Fish Audio Drama 3.'
format: mp3
responses:
'200':
$ref: '#/components/responses/FishTtsSynthesisSuccess'
'400':
$ref: '#/components/responses/ProviderBadRequest'
'401':
$ref: '#/components/responses/ProviderUnauthorized'
'402':
$ref: '#/components/responses/ProviderPaymentRequired'
'413':
$ref: '#/components/responses/ProviderPayloadTooLarge'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'503':
$ref: '#/components/responses/ProviderServiceUnavailable'
components:
schemas:
FishTtsRequest:
type: object
description: Fish Audio TTS request. Shared by one-shot and streaming synthesis.
required:
- text
properties:
text:
type: string
minLength: 1
description: >-
Text to synthesize. S2-family and Drama 3 variants support
`<|speaker:N|>` multi-speaker dialogue markers. Drama 3 also follows
bracketed natural-language direction such as `[whispering]` and
paired word-level tags such as `...`.
reference_id:
type: string
description: >-
Fish Audio voice-model ID. For multi-speaker synthesis, provide one
ID per speaker as an array.
references:
type: array
description: >-
Inline reference audio for voice cloning. MessagePack-only, as the
entries carry binary audio.
items:
$ref: '#/components/schemas/FishTtsReference'
prosody:
type: object
description: Prosody controls.
properties:
speed:
type: number
minimum: 0.5
maximum: 2
default: 1
description: Speech speed multiplier.
volume:
type: number
minimum: -20
maximum: 20
default: 0
description: Volume adjustment in dB.
normalize_loudness:
type: boolean
default: true
description: Whether to normalize output loudness.
temperature:
type: number
minimum: 0
maximum: 1
default: 0.7
description: Sampling temperature.
top_p:
type: number
minimum: 0
maximum: 1
default: 0.7
description: Nucleus sampling probability mass.
chunk_length:
type: integer
minimum: 100
maximum: 300
default: 300
description: Target chunk length for synthesis.
normalize:
type: boolean
default: true
description: Whether to normalize input text before synthesis.
format:
type: string
enum:
- wav
- pcm
- mp3
- opus
default: mp3
description: Output audio format.
sample_rate:
type: integer
nullable: true
enum:
- 8000
- 16000
- 24000
- 32000
- 44100
- 48000
description: >-
Output sample rate in Hz. This enum is the union across formats; the
gateway rejects a rate the selected format does not accept before
contacting the provider. `wav` and `pcm` accept 8000, 16000, 24000,
32000, and 44100; `mp3` accepts 32000 and 44100; `opus` accepts
48000 only. Omit or send null for the format default (48000 for
opus, 44100 otherwise).
mp3_bitrate:
type: integer
enum:
- 64
- 128
- 192
default: 128
description: MP3 bitrate in kbps (used when `format` is `mp3`).
opus_bitrate:
type: integer
enum:
- -1000
- 24000
- 32000
- 48000
- 64000
default: -1000
description: >-
Opus bitrate in bps (used when `format` is `opus`). `-1000` selects
the provider default.
latency:
type: string
enum:
- low
- normal
- balanced
default: normal
description: Latency/quality trade-off.
max_new_tokens:
type: integer
default: 1024
description: Maximum number of new tokens to generate.
repetition_penalty:
type: number
default: 1.2
description: Penalty applied to repeated tokens.
min_chunk_length:
type: integer
minimum: 0
maximum: 100
default: 50
description: Minimum chunk length for synthesis.
condition_on_previous_chunks:
type: boolean
default: true
description: Whether generation is conditioned on previously generated chunks.
early_stop_threshold:
type: number
minimum: 0
maximum: 1
default: 1
description: Early-stop threshold for generation.
features:
type: array
description: Optional feature flags.
items:
type: string
FishTtsReference:
type: object
description: >-
Inline reference audio for voice cloning. Supplied only over
`application/msgpack`.
required:
- audio
- text
properties:
audio:
type: string
format: binary
description: Reference audio bytes (MessagePack binary value).
text:
type: string
description: Transcript of the reference audio.
AudioBinary:
type: string
format: binary
description: Binary audio data.
ProviderErrorResponse:
type: object
description: >
Provider error response. Contains error information from the upstream
provider.
Common errors include invalid parameters, unsupported media types, or
payloads that exceed limits.
properties:
error:
type: string
description: >-
Error type or category (e.g., "TTS service error", "Validation
error").
example: TTS service error
upstream_status:
type: integer
description: >-
Original HTTP status code from the provider (may differ from gateway
response code).
example: 400
details:
type: string
description: Detailed error message from the provider.
example: 'Fish Audio TTS error: 400 Bad Request - Invalid reference_id'
required:
- error
responses:
FishTtsSynthesisSuccess:
description: >-
Synthesis successful. Returns binary audio in the format requested via
`format`.
content:
audio/*:
schema:
$ref: '#/components/schemas/AudioBinary'
ProviderBadRequest:
description: Bad request - invalid parameters provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorResponse'
examples:
validation-error:
summary: Validation error
value:
error: Validation error
details: 'Missing required field: text'
ProviderUnauthorized:
description: Invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorResponse'
ProviderPaymentRequired:
description: Insufficient credit or payment required.
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorResponse'
ProviderPayloadTooLarge:
description: Request payload exceeds the provider size limit.
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorResponse'
UnsupportedMediaType:
description: Unsupported request media type.
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorResponse'
ProviderServiceUnavailable:
description: Service unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderErrorResponse'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: |
API key issued by SLNG. Pass as `Authorization: Bearer `.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.