> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fish.audio/llms.txt
> Use this file to discover all available pages before exploring further.

# Speech to Text

> Convert audio to text with Fish Audio Python SDK

> [!WARNING]
>
> This documentation is for the legacy Python SDK. Please use the [new Python SDK](https://docs.fish.audio/developer-guide/sdk-guide/python) instead. See the [migration guide](https://docs.fish.audio/archive/python-sdk-legacy/migration-guide) for help upgrading.

## Prerequisites

> **Create a Fish Audio account**
>
> Sign up for a free Fish Audio account to get started with our API.
>
> 1. Go to [fish.audio/auth/signup](https://fish.audio/auth/signup)
> 2. Fill in your details to create an account, complete steps to verify your account.
> 3. Log in to your account and navigate to the [API section](https://fish.audio/app/api-keys)

> **Get your API key**
>
> Once you have an account, you'll need an API key to authenticate your requests.
>
> 1. Log in to your [Fish Audio Dashboard](https://fish.audio/app/api-keys/)
>
> 2. Navigate to the API Keys section
>
> 3. Click "Create New Key" and give it a descriptive name, set a expiration if desired
>
> 4. Copy your key and store it securely
>
> > [!WARNING]
> >
> > Keep your API key secret! Never commit it to version control or share it publicly.

## Basic Usage

Transcribe audio to text:

```python theme={null}
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:

```python theme={null}
# 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)

> [!TIP]
>
> 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:

```python theme={null}
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:

```python theme={null}
# 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
))
```

> [!NOTE]
>
> 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](https://docs.fish.audio/features/speech-to-text.md#limits)
* Sample rate: 16kHz or higher recommended

## Transcribing TTS Output

Transcribe generated speech:

```python theme={null}
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:

```python theme={null}
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) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.