Fish Audio Text-to-Speech
Use the text to speech endpoint to receive a result in the same response.
Overview
Use the text to speech endpoint and read the result from the same response.
Quick start
- Create an API key and set it as RUNAPI_API_KEY.
- Send a POST request whose body matches the request schema.
- Read the result from the successful response body.
Endpoint
- Base URL
https://runapi.ai- API version
v1- Authentication
Authorization: Bearer YOUR_API_TOKEN
Supported models
Open a model page for current pricing, rate limits, and commercial-usage details.
Request schema
Send only the fields declared for this endpoint.
s19 fields
bitrate_kbpsintegerMP3 bitrate. Not accepted for WAV output.
Allowed values:64, 128, 192
Default: 128
modelstringModel slug.
output_formatstringOutput audio format.
Allowed values:mp3, wav
Default: mp3
referencesarrayInline reference audio samples for this request.
references[].audiostringBase64-encoded raw audio bytes.
references[].textstringExact transcript of the reference audio.
sample_rate_hzintegerOutput sample rate. MP3 supports 32000 and 44100 Hz; WAV supports every listed value.
Allowed values:8000, 16000, 24000, 32000, 44100
Default: 44100
textstringvoice_idstrings2-pro9 fields
bitrate_kbpsintegerMP3 bitrate. Not accepted for WAV output.
Allowed values:64, 128, 192
Default: 128
modelstringModel slug.
output_formatstringOutput audio format.
Allowed values:mp3, wav
Default: mp3
referencesarrayInline reference audio samples for this request.
references[].audiostringBase64-encoded raw audio bytes.
references[].textstringExact transcript of the reference audio.
sample_rate_hzintegerOutput sample rate. MP3 supports 32000 and 44100 Hz; WAV supports every listed value.
Allowed values:8000, 16000, 24000, 32000, 44100
Default: 44100
textstringvoice_idstrings2.1-pro9 fields
bitrate_kbpsintegerMP3 bitrate. Not accepted for WAV output.
Allowed values:64, 128, 192
Default: 128
modelstringModel slug.
output_formatstringOutput audio format.
Allowed values:mp3, wav
Default: mp3
referencesarrayInline reference audio samples for this request.
references[].audiostringBase64-encoded raw audio bytes.
references[].textstringExact transcript of the reference audio.
sample_rate_hzintegerOutput sample rate. MP3 supports 32000 and 44100 Hz; WAV supports every listed value.
Allowed values:8000, 16000, 24000, 32000, 44100
Default: 44100
textstringvoice_idstringConditional rules
These requirements apply when all listed conditions match.
-
When
output_format = wav- Required
- Not accepted
bitrate_kbps
-
When
output_format = mp3- Required
- Not accepted
-
When
output_format = {"present" => false}- Required
- Not accepted
Success response
POST /api/v1/fish_audio/text_to_speech
Response schema
{
"properties": {
"audios": {
"items": {
"properties": {
"format": {
"type": "string"
},
"mime_type": {
"type": "string"
},
"size_bytes": {
"type": "integer"
},
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url",
"format",
"mime_type",
"size_bytes"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"audios",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Response example
{
"audios": [
{
"format": "mp3",
"mime_type": "audio/mpeg",
"size_bytes": 128,
"url": "https://file.runapi.ai/reference-audio.mp3"
}
],
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "completed"
}Errors
POST /api/v1/fish_audio/text_to_speech
Response schema
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
{
"error": "Authentication required"
}Errors
POST /api/v1/fish_audio/text_to_speech
Response schema
{
"oneOf": [
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "Human-readable validation summary.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Validation messages keyed by public request field, with an array of human-readable strings for each field.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}Response example
{
"error": "model must be one of: s1, s2-pro, s2.1-pro"
}Errors
POST /api/v1/fish_audio/text_to_speech
Response schema
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
{
"error": "Insufficient balance"
}Errors
POST /api/v1/fish_audio/text_to_speech
Response schema
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
{
"error": "API key credit limit exceeded"
}Errors
POST /api/v1/fish_audio/text_to_speech
Response schema
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
{
"error": "The request uses features that are not supported for the selected model"
}Errors
POST /api/v1/fish_audio/text_to_speech
Response schema
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
{
"error": "Rate limit reached. Please retry later."
}Errors
POST /api/v1/fish_audio/text_to_speech
Response schema
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
{
"error": "Service under maintenance, please try again later"
}Errors
POST /api/v1/fish_audio/text_to_speech
Response schema
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Response example
{
"error": "The request timed out"
}Generated Code Samples
Use cURL directly, or install an SDK for your language. Each sample submits the validated request shown in this reference.
Install
pip install runapi-fish-audioimport os
from runapi.fish_audio import FishAudioClient
client = FishAudioClient(api_key=os.environ["RUNAPI_API_KEY"])
result = client.text_to_speech.run(
model="s1",
text="Welcome to RunAPI."
)