Speech to Text

This documentation is for the legacy Python SDK. Please use the new Python SDK instead. See the migration guide for help upgrading.

Prerequisites

Create a Fish Audio account

Go to fish.audio/auth/signup
Fill in your details to create an account, complete steps to verify your account.
Log in to your account and navigate to the API section

Get your API key

Once you have an account, you’ll need an API key to authenticate your requests.

Log in to your Fish Audio Dashboard
Navigate to the API Keys section
Click “Create New Key” and give it a descriptive name, set a expiration if desired
Copy your key and store it securely

Keep your API key secret! Never commit it to version control or share it publicly.

Basic Usage

Transcribe audio to text:

from fish_audio_sdk import Session, ASRRequest

session = Session("your_api_key")

# Read audio file
with open("audio.mp3", "rb") as f:
    audio_data = f.read()

# Transcribe
response = session.asr(ASRRequest(
    audio=audio_data,
    ignore_timestamps=True
))

print(response.text)
print(f"Duration: {response.duration}s")

Language Specification

Pass a language hint when you know the source language:

# English transcription
response = session.asr(ASRRequest(
    audio=audio_data,
    language="en",
    ignore_timestamps=True
))

# Chinese transcription
response = session.asr(ASRRequest(
    audio=audio_data,
    language="zh",
    ignore_timestamps=True
))

Common language codes: en (English), zh (Chinese), es (Spanish), fr (French), de (German), ja (Japanese), ko (Korean), pt (Portuguese)

The language is detected automatically whether or not you send a hint, and a hint does not force the transcript into that language.

Working with Segments

Get detailed timing for each segment:

response = session.asr(ASRRequest(
    audio=audio_data,
    ignore_timestamps=False
))

# Full transcription
print(response.text)

# Segment details
for segment in response.segments:
    print(f"[{segment.start:.2f}s - {segment.end:.2f}s] {segment.text}")

Timestamps Control

Control timestamp generation:

# Include timestamps
response = session.asr(ASRRequest(
    audio=audio_data,
    ignore_timestamps=False  # False = include timestamps
))

# Skip timestamp processing for faster results
response = session.asr(ASRRequest(
    audio=audio_data,
    ignore_timestamps=True   # True = skip timestamps
))

Always set ignore_timestamps. The legacy SDK sends None when you leave it out, and the API rejects that with a 400 error. ignore_timestamps=False includes segment timestamps. Set it to True to skip timestamp processing for faster transcription when you only need the text.

Audio Formats

Supported audio formats:

MP3 (recommended)
WAV
M4A
OGG
FLAC
AAC

File requirements:

Size and duration limits depend on the model; see Speech to Text limits
Sample rate: 16kHz or higher recommended

Transcribing TTS Output

Transcribe generated speech:

from fish_audio_sdk import TTSRequest

# Generate speech
audio_buffer = bytearray()
for chunk in session.tts(TTSRequest(
    text="Hello, this is a test"
)):
    audio_buffer.extend(chunk)

# Transcribe it
response = session.asr(ASRRequest(
    audio=bytes(audio_buffer),
    ignore_timestamps=True
))

print(response.text)

Error Handling

Handle common errors:

from fish_audio_sdk.exceptions import HttpCodeErr

try:
    response = session.asr(ASRRequest(
        audio=audio_data,
        ignore_timestamps=True
    ))
except HttpCodeErr as e:
    if e.status == 413:
        print("Audio file too large")
    elif e.status == 400:
        print("Invalid audio format")
    else:
        raise e

Response Structure

The ASR response includes:

Field	Type	Description
`text`	str	Complete transcription
`duration`	float	Audio duration (seconds)
`segments`	list[ASRSegment]	Timestamped text segments

Segment structure:

Field	Type	Description
`text`	str	Segment text
`start`	float	Start time (seconds)
`end`	float	End time (seconds)

Request Parameters

Parameter	Type	Description	Default
`audio`	bytes	Audio data to transcribe	Required
`language`	str	Language code (e.g., “en”)	None (auto-detect)
`ignore_timestamps`	bool	Skip timestamp processing	None (must be set)

API Reference

REST API

Agents API

SDK Reference

Prerequisites

Basic Usage

Language Specification

Working with Segments

Timestamps Control

Audio Formats

Transcribing TTS Output

Error Handling

Response Structure

Request Parameters

​Prerequisites

​Basic Usage

​Language Specification

​Working with Segments

​Timestamps Control

​Audio Formats

​Transcribing TTS Output

​Error Handling

​Response Structure

​Request Parameters

Prerequisites

Basic Usage

Language Specification

Working with Segments

Timestamps Control

Audio Formats

Transcribing TTS Output

Error Handling

Response Structure

Request Parameters