Skip to content
API Reference
API Reference

Fish Audio Text-to-Speech

Generate speech with the S2 Pro models, instant voice cloning, and mp3 or wav output.

View Markdown
01

Overview

Use the text to speech endpoint and read the result from the same response.

Quick start

  1. Create an API key and set it as RUNAPI_API_KEY.
  2. Send a POST request whose body matches the request schema.
  3. Read the result from the successful response body.

Endpoint

POST /api/v1/fish_audio/text_to_speech
Base URL
https://runapi.ai
API version
v1
Authentication
Authorization: Bearer YOUR_API_TOKEN
02

Supported models

Open a model page for current pricing, rate limits, and commercial-usage details.

03

Request schema

JSON body

Send only the fields declared for this endpoint.

s19 fields
bitrate_kbpsinteger
Optional

MP3 bitrate. Not accepted for WAV output.

Allowed values: 64, 128, 192 Default: 128
modelstring
Required

Model slug.

output_formatstring
Optional

Output audio format.

Allowed values: mp3, wav Default: mp3
referencesarray
Optional

One temporary voice-cloning sample. Cannot be combined with voice_id. Omit, use null, or [] for no sample.

Item limit: 1
references[].audiostring
Required

Publicly accessible HTTPS audio URL. Must remain valid while queued and read by the provider.

references[].textstring
Required

Exact transcript that matches the reference audio word for word.

sample_rate_hzinteger
Optional

Output sample rate. MP3 supports 32000 and 44100 Hz; WAV supports every listed value.

Allowed values: 8000, 16000, 24000, 32000, 44100 Default: 44100
textstring
Required
voice_idstring
Optional
s2-pro9 fields
bitrate_kbpsinteger
Optional

MP3 bitrate. Not accepted for WAV output.

Allowed values: 64, 128, 192 Default: 128
modelstring
Required

Model slug.

output_formatstring
Optional

Output audio format.

Allowed values: mp3, wav Default: mp3
referencesarray
Optional

One temporary voice-cloning sample. Cannot be combined with voice_id. Omit, use null, or [] for no sample.

Item limit: 1
references[].audiostring
Required

Publicly accessible HTTPS audio URL. Must remain valid while queued and read by the provider.

references[].textstring
Required

Exact transcript that matches the reference audio word for word.

sample_rate_hzinteger
Optional

Output sample rate. MP3 supports 32000 and 44100 Hz; WAV supports every listed value.

Allowed values: 8000, 16000, 24000, 32000, 44100 Default: 44100
textstring
Required
voice_idstring
Optional
s2.1-pro9 fields
bitrate_kbpsinteger
Optional

MP3 bitrate. Not accepted for WAV output.

Allowed values: 64, 128, 192 Default: 128
modelstring
Required

Model slug.

output_formatstring
Optional

Output audio format.

Allowed values: mp3, wav Default: mp3
referencesarray
Optional

One temporary voice-cloning sample. Cannot be combined with voice_id. Omit, use null, or [] for no sample.

Item limit: 1
references[].audiostring
Required

Publicly accessible HTTPS audio URL. Must remain valid while queued and read by the provider.

references[].textstring
Required

Exact transcript that matches the reference audio word for word.

sample_rate_hzinteger
Optional

Output sample rate. MP3 supports 32000 and 44100 Hz; WAV supports every listed value.

Allowed values: 8000, 16000, 24000, 32000, 44100 Default: 44100
textstring
Required
voice_idstring
Optional

Conditional rules

These requirements apply when all listed conditions match.

  1. When references present
    Required
    Not accepted
    voice_id
  2. When output_format = wav
    Required
    Not accepted
    bitrate_kbps
  3. When output_format = mp3
    Required
    Not accepted
  4. When output_format absent
    Required
    Not accepted
04

Success response

HTTP 200

POST /api/v1/fish_audio/text_to_speech

Response schema
JSON 
{
  "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"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "enum": [
        "completed"
      ],
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "audios"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "audios": [
    {
      "format": "mp3",
      "mime_type": "audio/mpeg",
      "size_bytes": 128,
      "url": "https://file.runapi.ai/reference-audio.mp3"
    }
  ],
  "id": "tsk_reference_demo",
  "status": "completed"
}
05

Errors

HTTP 401

POST /api/v1/fish_audio/text_to_speech

Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "Authentication required"
}
06

Errors

HTTP 400

POST /api/v1/fish_audio/text_to_speech

Response schema
JSON 
{
  "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

JSON 
{
  "error": "model must be one of: s1, s2-pro, s2.1-pro"
}
07

Errors

HTTP 402

POST /api/v1/fish_audio/text_to_speech

Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "Insufficient balance"
}
08

Errors

HTTP 429

POST /api/v1/fish_audio/text_to_speech

Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "API key credit limit exceeded"
}
09

Errors

HTTP 409

POST /api/v1/fish_audio/text_to_speech

Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "The request uses features that are not supported for the selected model"
}
10

Errors

HTTP 429

POST /api/v1/fish_audio/text_to_speech

Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "Rate limit reached. Please retry later."
}
11

Errors

HTTP 503

POST /api/v1/fish_audio/text_to_speech

Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "Service under maintenance, please try again later"
}
12

Errors

HTTP 504

POST /api/v1/fish_audio/text_to_speech

Response schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Response example

JSON 
{
  "error": "The request timed out"
}
13

Generated Code Samples

Use cURL directly, or install an SDK for your language. Each sample submits the validated request shown in this reference.

Install

Shell 
pip install runapi-fish-audio
PYTHON 
import 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."
)