Fish Audio guide details API, Python SDK and self-hosted S2-Pro

Fish Audio’s text-to-speech offering combines a hosted API with downloadable model weights, giving developers two routes to generate speech from the same platform. The company’s November 3, 2026 guide says that dual approach is why searches for both “fish audio api” and “fish speech” point to the same ecosystem, and it walks through hosted generation first, then local deployment, then the constraints users may face in production.

Evidence and context

According to Fish Audio’s model overview and install guide, the text-to-speech lineup as of November 3, 2026 includes s2.1-pro as the recommended production model, s2.1-pro-free for development and testing, s2-pro as the previous S2 generation, drama-3 for content creation, and deprecated s1, which retires on December 31, 2026. The guide says Fish bills text-to-speech per UTF-8 byte rather than per character, with s2.1-pro priced at $15 per 1 million UTF-8 bytes and Drama 3 at $50 per 1 million bytes. It also says language detection is automatic on S2 models and that requests for s1 will be served by s2.1-pro after December 31, 2026.

For the API workflow, the guide says users need Python 3.9 or later, a Fish Audio account and, optionally, cURL. It instructs users to set an environment variable named FISH_API_KEY, install fish-audio-sdk, and import it as fishaudio. The examples use s2.1-pro-free, which the guide says is the quickstart model for new accounts before API credit is added. The API request uses a model HTTP header rather than a JSON field, and the response is returned as audio bytes.

The guide also outlines error handling drawn from Fish’s quickstart: 401 for an invalid or missing API key, 402 when the selected model has no API credit on the account, 400 for a bad reference_id or parameters, and 429 for concurrency-based rate limits. It says retries should use exponential backoff and that there is no Retry-After header.

SDK features and local deployment

Fish Audio’s Python SDK examples show how to pass a reference_id to select a voice, and how to centralize voice, format and speed settings with TTSConfig and Prosody. The guide says the SDK supports wav, pcm, mp3 and opus output, with latency options of normal or balanced, and that WAV and PCM can be 8, 16, 24, 32 or 44.1 kHz, MP3 can be 32 or 44.1 kHz, and Opus uses 48 kHz.

For speech styling, the guide says S2 models respond to free-form cues in square brackets, including examples such as [whisper], [laugh], [sigh], [gasp], [excited] and [laughing nervously]. It adds that users migrating from S1 should convert parenthesis-based tags to brackets, because S2 models do not read the older format.

On self-hosting, the guide says Fish Audio publishes some model weights and that S2-Pro can run locally behind Fish’s API server. Background documentation says the official repository recommends Linux or WSL and at least 24 GB of GPU memory for S2 inference, with support for command-line inference, a Gradio WebUI, an API server and Docker deployment. It also says S2-Pro is a 4-billion-parameter model that supports natural-language expression instructions in square brackets, multilingual speech and multi-speaker generation.

The licensing position appears mixed across the project materials. The guide says s2-pro weights are downloadable under the Fish Audio Research License, while the broader codebase is described in current repository documentation under the Fish Audio Community License. The background material says users should verify the applicable terms before commercial self-hosting.

Related release notes dated March 10, 2026 say Fish Audio announced that S2 is open source and that version 1.3.0 of the Python SDK added S2-Pro support and advanced TTS generation parameters. The article’s examples also note that older fish_audio_sdk imports are no longer updated and that the modern package name is fish-audio-sdk.