> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aiola.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aiola.ai/_mcp/server.

# Speech to Text SDK

Convert audio to text with our easy-to-use SDKs. This guide will walk you through the essential steps to get started with speech transcription in your applications.

## Prerequisites

Before you begin, make sure you have:

* An aiOla API key ([get one here](https://platform.aiola.ai/))
* Python 3.10+ (for Python SDK) or Node.js 18+ (for TypeScript SDK)

## Step 1: Install the SDK

#### Python

```bash
pip install aiola
# or for microphone support
pip install 'aiola[mic]'
```

#### TypeScript

```bash
npm install @aiola/sdk
# or
yarn add @aiola/sdk
```

## Step 2: Set up authentication

First, you'll need to generate an access token using your API key:

> **Info**
>
> For detailed authentication information, security best practices, and advanced token management, see our [Authentication Guide](../authentication).

#### Python

```python
from aiola import AiolaClient

# Generate access token
result = AiolaClient.grant_token(api_key='your-api-key')
access_token = result.access_token

# Create client
client = AiolaClient(access_token=access_token)
```

#### TypeScript

```typescript
import { AiolaClient } from '@aiola/sdk';

// Generate access token
const { accessToken } = await AiolaClient.grantToken({
  apiKey: 'your-api-key'
});

// Create client
const client = new AiolaClient({ accessToken });
```

## Step 3: Transcribe an audio file

Here's how to transcribe an audio file:

#### Python

```python
# Transcribe audio file
with open('path/to/your/audio.wav', 'rb') as audio_file:
    transcript = client.stt.transcribe_file(
        file=audio_file,
        language='en'
    )

print(transcript)
```

#### TypeScript

```typescript
import fs from 'fs';

// Read audio file (Node.js)
const audioFile = fs.readFileSync('path/to/your/audio.wav');

// Transcribe audio file
const transcript = await client.stt.transcribeFile({
  file: audioFile,
  language: 'en'
});

console.log(transcript);
```

## Real-time streaming

For real-time audio streaming transcription, check out our dedicated [Speech to Text Streaming Guide](streaming) which covers:

* Live microphone streaming
* Event-based transcription handling
* Custom audio source streaming
* Keyword detection during streaming
* Connection management and error handling

## Supported audio formats

The SDK supports the following audio formats:

* **WAV** (`.wav`)
* **FLAC** (`.flac`)
* **AIFF** (`.aiff`)
* **M4A** (`.m4a`)
* **MP4** (`.mp4`)
* **MOV** (`.mov`)
* **M4V** (`.m4v`)
* **AAC** (`.aac`)
* **MKV** (`.mkv`)
* **MP3** (`.mp3`)
* **Opus** (`.opus`)

### File size limitations

* Maximum file size: **50 MB**
* For larger files, consider using streaming transcription or splitting the audio into smaller chunks

## Supported languages

The SDK supports the following languages:

* English (`en`)
* German (`de`)
* French (`fr`)
* Spanish (`es`)
* Portuguese (`pr`)
* Chinese (`zh`)
* Japanese (`ja`)
* Italian (`it`)

## Error handling

Always implement proper error handling for your API calls:

#### Python

```python
try:
    with open('audio.wav', 'rb') as audio_file:
        transcript = client.stt.transcribe_file(
            file=audio_file,
            language='en'
        )
    print(transcript)
except Exception as e:
    print(f"Transcription failed: {e}")
```

#### TypeScript

```typescript
try {
  const transcript = await client.stt.transcribeFile({
    file: audioFile,
    language: 'en'
  });
  console.log(transcript);
} catch (error) {
  if (error instanceof Error) {
    console.error('Transcription failed:', error.message);
  }
}
```

## Advanced options

### Keyword detection

You can enable keyword detection for more accurate transcription:

#### Python

```python
# Keyword detection with custom transcription
transcript = client.stt.transcribe_file(
    file=audio_file,
    language='en',
    keywords={
        "postgres": "PostgreSQL",
        "k eight s": "Kubernetes"
    }
)
```

#### TypeScript

```typescript
const transcript = await client.stt.transcribeFile({
  file: audioFile,
  language: 'en',
  keywords: {
    "postgres": "PostgreSQL",
    "k eight s": "Kubernetes"
  }
});
```

### Custom configuration

For enterprise users, you can configure custom endpoints:

#### Python

```python
# Custom base URL (enterprise)
client = AiolaClient(
    access_token=access_token,
    base_url='https://your-custom-endpoint.com'
)
```

#### TypeScript

```typescript
const client = new AiolaClient({ 
  accessToken,
  baseUrl: 'https://your-custom-endpoint.com' 
});
```

## Next steps

Now that you've successfully transcribed your first audio file, you can:

* Explore [Real-time Streaming](streaming) for live audio transcription
* Learn about [Text to Speech SDK](../text-to-speech/quickstart) for converting text back to speech
* Check out the SDK repositories for more examples:
  * [Python SDK](https://github.com/aiola-lab/aiola-python-sdk)
  * [TypeScript SDK](https://github.com/aiola-lab/aiola-js-sdk)

## Browser Examples

For web applications, check out our complete browser microphone streaming example:

* [**Browser Microphone Streaming**](https://github.com/aiola-lab/aiola-js-sdk/tree/main/examples/stt/browser-mic-stream) - Full web app example showing real-time microphone transcription in the browser