### Transcribe from File Example (Python)

Source: https://st-frontend.aldea.ai/docs/guides/deepgram-to-aldea

This example demonstrates how to transcribe audio directly from a local file using the Deepgram client. It opens an audio file in binary read mode and passes its content to the `transcribe_file` method. The response, formatted as JSON, includes transcription details.

```python
import asyncio
from deepgram import DeepgramClient, DeepgramClientEnvironment

async def main():
    ALDEA_TOKEN = "<get your aldea token>"
    ALDEA_HOST = "https://api.aldea.ai"
    
    config = DeepgramClientEnvironment(
        base=ALDEA_HOST,
        production=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}",
        agent=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}"
    )

    client = DeepgramClient(api_key=ALDEA_TOKEN, environment=config)

    with open("audio.wav", "rb") as f:
        response = client.listen.v1.media.transcribe_file(request=f.read())
        print(response.to_json(indent=2))

asyncio.run(main())

```

--------------------------------

### cURL Request Example with Authentication

Source: https://st-frontend.aldea.ai/docs/authentication

An example of a cURL request to the Aldea AI API, showing how to pass the API token in the Authorization header and send audio data. This requires the 'curl' command-line tool.

```bash
API="https://api.aldea.ai/v1/listen"
TOKEN=org_your_api_key_here
FILE=~/Downloads/aldea_sample.wav

curl -s -X POST "$API" \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @"$FILE"
```

--------------------------------

### Pre-recorded Transcription Example (Python)

Source: https://st-frontend.aldea.ai/docs/guides/deepgram-to-aldea

This example shows how to transcribe pre-recorded audio from a URL using the Deepgram client and the httpx client. It sends a POST request to the Aldea AI API with the audio URL and an optional callback URL for receiving results. The response contains metadata and transcription results.

```python
import asyncio
from deepgram import DeepgramClient, DeepgramClientEnvironment

async def main():
    ALDEA_TOKEN = "<get your aldea token>"
    ALDEA_HOST = "https://api.aldea.ai"
    
    # Webhook URL where transcription results will be POSTed
    CALLBACK_URL = "<get your callback url>" # "https://webhook-test.com/<code>"
    
    # Audio URL to transcribe
    AUDIO_URL = "https://dpgr.am/spacewalk.wav"

    config = DeepgramClientEnvironment(
        base=ALDEA_HOST,
        production=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}",
        agent=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}"
    )

    client = DeepgramClient(api_key=ALDEA_TOKEN, environment=config)

    # Aldea uses different URL API - call /v1/listen/url with url and callback as query params
    # When using a callback, the transcription result will be POSTed to the callback URL
    params = {'url': AUDIO_URL}
    if CALLBACK_URL != "<get your callback url>":
        params['callback'] = CALLBACK_URL
    
    response = client.listen.v1.media.with_raw_response._client_wrapper.httpx_client.request(
        path='/v1/listen/url',
        method='POST',
        base_url=ALDEA_HOST,
        params=params,
        headers=client.listen.v1.media.with_raw_response._client_wrapper.get_headers()
    )
    
    result = response.json()
    print(f"Request accepted. Status code: {response.status_code}")
    print(f"Response: {result}")
    if CALLBACK_URL != "<get your callback url>":
        print(f"\nTranscription results will be POSTed to: {CALLBACK_URL}")

asyncio.run(main())

```

--------------------------------

### Python SDK Pre-recorded Transcription with Aldea STT API

Source: https://st-frontend.aldea.ai/docs/guides/deepgram-to-aldea

Example demonstrating how to transcribe a pre-recorded audio file using the Deepgram Python SDK configured for Aldea's STT API. It takes a URL to an audio file as input and prints the transcription response.

```python
import asyncio
from deepgram import DeepgramClient, DeepgramClientEnvironment

async def main():
    ALDEA_TOKEN = "<get your aldea token>"
    ALDEA_HOST = "https://api.aldea.ai"

    config = DeepgramClientEnvironment(
        base=ALDEA_HOST,
        production=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}",
        agent=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}"
    )

    client = DeepgramClient(api_key=ALDEA_TOKEN, environment=config)

    response = client.listen.v1.media.transcribe_url(url="https://dpgr.am/spacewalk.wav")
    print(response.to_json(indent=2))

asyncio.run(main())
```

--------------------------------

### Authentication Header Example

Source: https://st-frontend.aldea.ai/docs/authentication

Demonstrates how to include the API token in the Authorization header for API requests. The token should be prefixed with 'Bearer '.

```plaintext
Authorization: Bearer org_your_api_key_here
```

--------------------------------

### Make First Speech-to-Text Request with Node.js (fetch)

Source: https://st-frontend.aldea.ai/docs/getting-started

This Node.js example shows how to transcribe speech from an audio file using the fetch API. It assumes you are using Node.js version 18 or later and have your API token. The code reads a local audio file and sends it as binary data in the request body.

```javascript
import fetch from 'node-fetch';
import fs from 'fs';

const API_URL = 'https://api.aldea.ai/v1/listen';
const API_TOKEN = 'YOUR_API_TOKEN';
const audioFilePath = '~/Downloads/aldea_sample.wav';

async function transcribeAudio() {
  try {
    const audioData = fs.readFileSync(audioFilePath);

    const response = await fetch(API_URL, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`
      },
      body: audioData
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const transcription = await response.json();
    console.log(transcription);
  } catch (error) {
    console.error('Error transcribing audio:', error);
  }
}

transcribeAudio();
```

--------------------------------

### Python SDK Configuration for Aldea STT API

Source: https://st-frontend.aldea.ai/docs/guides/deepgram-to-aldea

Configures the Deepgram Python SDK to use Aldea's STT API by setting custom environment variables for base and WebSocket URLs. Requires Python 3.10+ and installation via pip.

```python
from deepgram import DeepgramClient, DeepgramClientEnvironment

ALDEA_TOKEN = "<get your aldea token>"
ALDEA_HOST = "https://api.aldea.ai"

config = DeepgramClientEnvironment(
    base=ALDEA_HOST,
    production=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}",
    agent=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}"
)

client = DeepgramClient(ALDEA_TOKEN, config)
```

--------------------------------

### Speech to Text API - cURL Example

Source: https://st-frontend.aldea.ai/docs/getting-started

This endpoint allows you to transcribe audio to text. You need to provide your API key for authentication and the audio file in the request body.

```APIDOC
## POST /v1/listen

### Description
Transcribes audio to text using the Speech-to-Text API.

### Method
POST

### Endpoint
https://api.aldea.ai/v1/listen

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer token for authentication. Format: `Bearer YOUR_API_TOKEN`

#### Request Body
- **audio file** (binary) - Required - The audio file to transcribe. Accepts formats like WAV or MP3.

### Request Example
```bash
API="https://api.aldea.ai/v1/listen"
TOKEN="YOUR_API_TOKEN"
FILE=~/Downloads/aldea_sample.wav

curl -s -X POST "$API" \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @"$FILE"
```

### Response
#### Success Response (200)
- **transcript** (string) - The transcribed text from the audio.

#### Response Example
```json
{
  "transcript": "This is a sample transcription."
}
```

#### Error Response (e.g., 401 Unauthorized)
- **error** (string) - A message describing the error.

#### Error Response Example
```json
{
  "error": "Invalid API token."
}
```
```

--------------------------------

### Python SDK Configuration for Aldea STT API

Source: https://st-frontend.aldea.ai/docs/guides/deepgram-to-aldea

This snippet demonstrates how to configure the Deepgram Python SDK to use Aldea's STT API by setting the base and WebSocket URLs.

```APIDOC
## Python SDK Configuration for Aldea STT API

### Description
This section provides instructions on setting up the Deepgram Python SDK to interact with Aldea's Speech-to-Text API servers. It includes steps for installation and configuration, focusing on updating the base URL to point to Aldea's endpoints.

### Requirements
- Python 3.10+

### Installation
```
pip install "deepgram-sdk>=3.4.0"
httpx
```

### Configuration
```python
from deepgram import DeepgramClient, DeepgramClientEnvironment

ALDEA_TOKEN = "<get your aldea token>"
ALDEA_HOST = "https://api.aldea.ai"

config = DeepgramClientEnvironment(
    base=ALDEA_HOST,
    production=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}",
    agent=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}"
)

client = DeepgramClient(ALDEA_TOKEN, config)
```

### Pre-recorded Transcription Example

#### Description
This example shows how to use the configured Aldea STT API client to transcribe a pre-recorded audio file from a given URL.

#### Endpoint
`/v1/listen/media/transcribe_url` (Implicitly used by the SDK method)

#### Method
`POST` (handled by the SDK)

#### Request Example
```python
import asyncio
from deepgram import DeepgramClient, DeepgramClientEnvironment

async def main():
    ALDEA_TOKEN = "<get your aldea token>"
    ALDEA_HOST = "https://api.aldea.ai"

    config = DeepgramClientEnvironment(
        base=ALDEA_HOST,
        production=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}",
        agent=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}"
    )

    client = DeepgramClient(api_key=ALDEA_TOKEN, environment=config)

    response = client.listen.v1.media.transcribe_url(url="https://dpgr.am/spacewalk.wav")
    print(response.to_json(indent=2))

asyncio.run(main())
```

#### Response Example (Success)

##### Description
This is an example of a successful transcription response from the Aldea STT API.

##### Content
```json
{
  "metadata": {
    "channels": 1,
    "created": "2026-01-08T15:39:40.011380Z",
    "duration": 25.561875,
    "models": ["2304fa8b9196f7e14a4d5c97011c9c88ce9c8e5388fd979411efb51e6ffb6cc1"],
    "request_id": "e1f63e0b-7c71-4f90-a281-290ad284daf5",
    "sha256": "154e291ecfa8be6ab8343560bcc109008fa7853eb5372533e8efdefc9b504c33"
  },
  "results": {
    "channels": [
      {
        "alternatives": [
          {
            "confidence": 0.0,
            "transcript": "As much as it's worth celebrating the first spacewalk with an all-female team, I think many of us are looking forward to it just being normal...",
            "words": []
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### Connect to Streaming Audio WebSocket Endpoint

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/streaming-audio

Establishes a WebSocket connection to the primary streaming audio endpoint. This endpoint supports both encoded audio and raw PCM data. The connection is initiated using a GET request, and a '101 Switching Protocols' status code indicates a successful upgrade.

```websocket
wss://api.aldea.ai/v1/listen
```

--------------------------------

### Receive SpeechStarted Message (Server to Client)

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/streaming-audio

Receives a JSON message from the server indicating that speech has been detected and the transcription process has started. It includes channel information and a timestamp.

```json
{
  "type": "SpeechStarted",
  "channel": [0],
  "timestamp": 0.0
}
```

--------------------------------

### Connect to Streaming Audio PCM-Only WebSocket Endpoint

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/streaming-audio

Establishes a WebSocket connection to a PCM-only streaming audio endpoint, optimized for raw PCM data. This connection also uses a GET request and expects a '101 Switching Protocols' status for success.

```websocket
wss://api.aldea.ai/v1/listen/pcm
```

--------------------------------

### Live WebSocket Streaming with Deepgram and Aldea AI (Python)

Source: https://st-frontend.aldea.ai/docs/guides/deepgram-to-aldea

This Python script streams audio from a given URL using httpx and sends it to Deepgram via WebSockets for real-time transcription. It configures the Deepgram client with Aldea AI's environment settings and defines a callback function to process incoming transcription results.

```python
import threading
import httpx
import asyncio
import sys
from deepgram import DeepgramClient, DeepgramClientEnvironment
from deepgram.core.events import EventType
from deepgram.extensions.types.sockets import ListenV1SocketClientResponse

async def stream_audio():
    ALDEA_TOKEN = "<get your aldea token>"
    ALDEA_HOST = "https://api.aldea.ai"
    STREAM_URL = "http://icecast.omroep.nl/radio1-bb-mp3" # example

    config = DeepgramClientEnvironment(
        base=ALDEA_HOST,
        production=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}",
        agent=f"wss://{ALDEA_HOST.replace('https://', '').replace('http://', '')}"
    )

    client = DeepgramClient(api_key=ALDEA_TOKEN, environment=config)

    with client.listen.v1.connect(model="") as connection:
        def on_message(message: ListenV1SocketClientResponse) -> None:
            if hasattr(message, 'channel') and hasattr(message.channel, 'alternatives'):
                transcript = message.channel.alternatives[0].transcript
                if transcript:
                    print(transcript)

        connection.on(EventType.MESSAGE, on_message)

        # Start listening in background thread
        threading.Thread(target=connection.start_listening, daemon=True).start()

        # Stream audio from URL and send chunks
        with httpx.stream("GET", STREAM_URL) as r:
            for chunk in r.iter_bytes():
                connection.send_media(chunk)

if __name__ == "__main__":
    success = asyncio.run(stream_audio())
    if not success:
        sys.exit(1)

```

--------------------------------

### Make First Speech-to-Text Request with Python (requests)

Source: https://st-frontend.aldea.ai/docs/getting-started

This Python script utilizes the 'requests' library to send an audio file to the Aldea AI Speech-to-Text API. It requires your API token and the path to the audio file. The script reads the audio file in binary mode and sends it as the data for a POST request.

```python
import requests

API_URL = "https://api.aldea.ai/v1/listen"
API_TOKEN = "YOUR_API_TOKEN"
audio_file_path = "~/Downloads/aldea_sample.wav"

def transcribe_audio():
    try:
        with open(audio_file_path, 'rb') as audio_file:
            files = {'file': audio_file}
            headers = {'Authorization': f'Bearer {API_TOKEN}'}
            
            response = requests.post(API_URL, headers=headers, data=audio_file)
            
            if response.status_code != 200:
                response.raise_for_status()
            
            transcription = response.json()
            print(transcription)
            
    except FileNotFoundError:
        print(f"Error: Audio file not found at {audio_file_path}")
    except requests.exceptions.RequestException as e:
        print(f"Error during API request: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

transcribe_audio()

```

--------------------------------

### Make First Speech-to-Text Request with cURL (WAV)

Source: https://st-frontend.aldea.ai/docs/getting-started

This cURL command demonstrates how to make a POST request to the Aldea AI Speech-to-Text API to transcribe a WAV audio file. It requires your API token and the path to the audio file. Ensure the API endpoint and token are correctly set.

```shell
API="https://api.aldea.ai/v1/listen"
TOKEN="YOUR_API_TOKEN"
FILE=~/Downloads/aldea_sample.wav

curl -s -X POST "$API" \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @"$FILE"
```

--------------------------------

### POST /pre-recorded-audio

Source: https://st-frontend.aldea.ai/docs/stt-api-reference

Transcribe audio files using HTTP POST requests. Upload audio files and receive complete transcripts.

```APIDOC
## POST /pre-recorded-audio

### Description
Transcribe audio files using HTTP POST requests. Upload MP3, WAV, M4A, FLAC, or raw PCM audio files and receive complete transcripts.

### Method
POST

### Endpoint
/pre-recorded-audio

### Parameters
#### Query Parameters
- **audio_file** (file) - Required - The audio file to transcribe.
- **language_code** (string) - Optional - The language code of the audio (e.g., "en-US").

### Request Example
```
POST /pre-recorded-audio?language_code=en-US
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="audio_file"; filename="audio.mp3"
Content-Type: audio/mpeg

[audio data]
--boundary--
```

### Response
#### Success Response (200)
- **transcript** (string) - The transcribed text.

#### Response Example
```json
{
  "transcript": "This is the transcribed text from the audio file."
}
```
```

--------------------------------

### WSS /streaming-audio

Source: https://st-frontend.aldea.ai/docs/stt-api-reference

Real-time audio transcription using WebSocket connections. Stream audio data and receive live transcriptions as you speak.

```APIDOC
## WSS /streaming-audio

### Description
Real-time audio transcription using WebSocket connections. Stream audio data and receive live transcriptions as you speak.

### Method
WebSocket (WSS)

### Endpoint
/streaming-audio

### Parameters
#### Query Parameters
- **language_code** (string) - Optional - The language code of the audio (e.g., "en-US").

### Request Example
```
// Establishing WebSocket connection
WSS /streaming-audio?language_code=en-US

// Sending audio data frame
[audio data chunk]
```

### Response
#### Success Response (WebSocket messages)
- **transcript** (string) - The transcribed text in real-time.

#### Response Example
```json
{
  "transcript": "This is a live transcription."
}
```
```

--------------------------------

### POST Pre-Recorded Audio - Binary or URL

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/pre-recorded-audio

This endpoint accepts pre-recorded audio either as raw binary data or a URL pointing to an audio file. It returns a JSON object containing the transcribed text, confidence scores, and optionally, per-word timestamps. Supported audio formats include MP3, AAC, FLAC, WAV, OGG, WebM, Opus, M4A, and raw 16-bit PCM.

```bash
API="https://api.aldea.ai/v1/listen"
TOKEN="$STT_API_TOKEN"
FILE=~/Downloads/aldea_sample.wav

curl -s -X POST "$API" \
  -H "Authorization: Bearer $TOKEN" \
  -H "timestamps: true" \
  --data-binary @"$FILE"
```

--------------------------------

### POST Pre-Recorded Audio - URL Endpoint

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/pre-recorded-audio

This endpoint handles pre-recorded audio provided via a URL. The API will download and process the audio file from the given URL. It returns a JSON object with transcription details. Similar to the binary endpoint, it supports various audio formats accessible via HTTP/HTTPS.

```bash
# Example for URL endpoint (conceptual, requires actual URL in data)
API="https://api.aldea.ai/v1/listen/url"
TOKEN="$STT_API_TOKEN"
AUDIO_URL="https://example.com/path/to/your/audio.wav"

curl -s -X POST "$API?audio_url=$AUDIO_URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "timestamps: true"
```

--------------------------------

### POST /v1/listen/url

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/pre-recorded-audio

Submits a URL pointing to audio data for transcription. The API will fetch and process the audio from the provided URL.

```APIDOC
## POST /v1/listen/url

### Description
This endpoint processes audio data located at a specified URL for speech-to-text transcription.

### Method
POST

### Endpoint
/v1/listen/url

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the audio file to transcribe.
- **timestamps** (boolean) - Optional - Include `true` to receive per-word timings in the response.
- **diarization** (boolean) - Optional - Include `true` to enable speaker diarization. Requires word timestamps.
- **keywords** (string) - Optional - A comma-separated list of terms to boost recognition for.
- **keyword_boost** (number) - Optional - The boost strength for keywords (default: 2.0).

### Request Example
(No request body needed, URL is passed as a query parameter)

### Response
#### Success Response (200)
- **results** (object) - Contains the transcription results.
- **word_count** (integer) - The total number of words transcribed.
- **channel_count** (integer) - The number of audio channels.
- **duration** (number) - The duration of the audio in seconds.
- **confidence** (number) - The overall confidence score of the transcription.
- **words** (array) - An array of word objects, each containing `word`, `start`, and `end` if timestamps are enabled.

#### Response Example
```json
{
  "results": {
    "channels": [
      {
        "alternatives": [
          {
            "paragraphs": [],
            "words": [
              {
                "word": "hello",
                "start": 0.5,
                "end": 0.9,
                "confidence": 0.95
              },
              {
                "word": "world",
                "start": 1.0,
                "end": 1.5,
                "confidence": 0.98
              }
            ]
          }
        ]
      }
    ],
    "speaker_count": 1,
    "utterances": [
      {
        "start": 0.0,
        "end": 1.5,
        "speaker": 0,
        "transcript": "hello world"
      }
    ]
  },
  "word_count": 2,
  "channel_count": 1,
  "duration": 1.5,
  "confidence": 0.96
}
```
```

--------------------------------

### Audio Transcription with Options

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/streaming-audio

This endpoint handles audio transcription, supporting various options for PII redaction, keyword boosting, and format detection. Audio can be sent as raw PCM or encoded formats.

```APIDOC
## POST /v1/listen

### Description
Processes audio streams for speech-to-text conversion. Supports PII redaction, keyword boosting, and automatic format detection. Audio can be sent directly as encoded chunks or decoded PCM.

### Method
POST

### Endpoint
/v1/listen

### Query Parameters
- **redact** (string) - Optional - Specifies PII redaction types (e.g., 'pii', 'pci'). Can be combined.
- **redact_mode** (string) - Optional - Controls the anonymization style ('mask', 'redact', or 'replace').
- **keywords** (string) - Optional - A comma-separated list of terms to boost.
- **keyword_boost** (number) - Optional - The boost strength for keywords (default: 2.0).

### Request Body
- **audio_chunk** (binary) - Required - The audio data to be transcribed.

### Response
#### Success Response (200)
- **results** (array) - Contains transcription results, including interim/final results and word timestamps if enabled.
- **Metadata** (object) - Additional metadata about the transcription.
- **SpeechStarted** (object) - Indicates the start of speech detection.
- **UtteranceEnd** (object) - Indicates the end of an utterance (requires word timestamps).

#### Response Example
```json
{
  "results": [
    {
      "type": "interim",
      "alternatives": [
        {
          "content": "this is a test",
          "words": [
            ["this", 100, 150],
            ["is", 160, 190],
            ["a", 200, 210],
            ["test", 220, 270]
          ]
        }
      ]
    }
  ],
  "metadata": {
    "request_id": "abc-123"
  }
}
```
```

--------------------------------

### POST /v1/listen

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/pre-recorded-audio

Submits audio data for transcription. This endpoint accepts audio directly in the request body.

```APIDOC
## POST /v1/listen

### Description
This endpoint processes audio data submitted directly in the request body for speech-to-text transcription.

### Method
POST

### Endpoint
/v1/listen

### Parameters
#### Query Parameters
- **timestamps** (boolean) - Optional - Include `true` to receive per-word timings in the response.
- **diarization** (boolean) - Optional - Include `true` to enable speaker diarization. Requires word timestamps.
- **keywords** (string) - Optional - A comma-separated list of terms to boost recognition for.
- **keyword_boost** (number) - Optional - The boost strength for keywords (default: 2.0).

#### Request Body
- **audio** (binary) - Required - The audio data to be transcribed.

### Request Example
(Binary audio data should be sent in the request body)

### Response
#### Success Response (200)
- **results** (object) - Contains the transcription results.
- **word_count** (integer) - The total number of words transcribed.
- **channel_count** (integer) - The number of audio channels.
- **duration** (number) - The duration of the audio in seconds.
- **confidence** (number) - The overall confidence score of the transcription.
- **words** (array) - An array of word objects, each containing `word`, `start`, and `end` if timestamps are enabled.

#### Response Example
```json
{
  "results": {
    "channels": [
      {
        "alternatives": [
          {
            "paragraphs": [],
            "words": [
              {
                "word": "hello",
                "start": 0.5,
                "end": 0.9,
                "confidence": 0.95
              },
              {
                "word": "world",
                "start": 1.0,
                "end": 1.5,
                "confidence": 0.98
              }
            ]
          }
        ]
      }
    ],
    "speaker_count": 1,
    "utterances": [
      {
        "start": 0.0,
        "end": 1.5,
        "speaker": 0,
        "transcript": "hello world"
      }
    ]
  },
  "word_count": 2,
  "channel_count": 1,
  "duration": 1.5,
  "confidence": 0.96
}
```
```

--------------------------------

### Pre-Recorded Audio - Binary

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/pre-recorded-audio

Accepts binary audio data or a URL string in the request body for transcription.

```APIDOC
## POST /v1/listen

### Description
This endpoint accepts binary audio data or a URL string in the request body and returns a JSON object containing the transcription, confidence scores, and optional word timestamps.

### Method
POST

### Endpoint
https://api.aldea.ai/v1/listen

### Headers
- **Authorization** (string) - Required - Bearer token; required for all API requests.
- **timestamps** (string) - Optional - Set to "true" to include per-word timestamps in response.

### Query Parameters
- **callback** (string) - Optional - URL to send results asynchronously. When provided, the request returns immediately with a `request_id`.
- **callback_method** (string) - Optional - HTTP method for the callback URL. Defaults to POST.
- **metadata** (string) - Optional - JSON string that will be passed through to the callback.
- **diarization** (boolean) - Optional - Enable speaker diarization to identify different speakers.
- **keywords** (string) - Optional - Comma-separated list of keywords or phrases to boost recognition accuracy. Example: `?keywords=John Doe,Acme Corp`
- **language** (string) - Optional - Language identifier in BCP-47 format (e.g., `"en-US"`). Accepts `lang` as an alias. Spanish can be indicated with `"es"` or `"es-ES"`.

### Request Body
Send raw binary audio bytes or an HTTP/HTTPS URL string in the request body. Supported formats include MP3, AAC, FLAC, WAV, OGG, WebM, Opus, M4A, and 16-bit PCM (s16le). Max duration defaults to 10 minutes (600 seconds).

### Request Example
```bash
API="https://api.aldea.ai/v1/listen"
TOKEN="$STT_API_TOKEN"
FILE=~/Downloads/aldea_sample.wav

curl -s -X POST "$API" \
  -H "Authorization: Bearer $TOKEN" \
  -H "timestamps: true" \
  --data-binary @"$FILE"
```

### Response
#### Success Response (200)
- **metadata** (object) - Contains metadata about the request, including `request_id`, `created` timestamp, `duration`, and `channels`.
- **results** (object) - Contains the transcription results, including alternatives with `transcript`, `confidence`, and `words` (if timestamps are enabled).

#### Response Example
```json
{
  "metadata": {
    "request_id": "77aaccd1-3b19-4000-9055-3f91009751b4",
    "created": "2025-01-01T00:00:00.000000Z",
    "duration": 6.916625,
    "channels": 1
  },
  "results": {
    "channels": [
      {
        "alternatives": [
          {
            "transcript": "Something, you know, it's just like I'm saying, it's a it's a next level. It's like there's I mean, when we give you a show now, you're gonna get",
            "confidence": 0.802,
            "words": [
              {
                "word": "Something,",
                "start": 0.04,
                "end": 0.36
              },
              {
                "word": "you",
                "start": 0.44,
                "end": 0.52
              }
            ]
          }
        ]
      }
    ]
  }
}
```

### Async Processing
For long audio files or when you need non-blocking processing, use the `callback` query parameter. Include `?callback=https://your-server.com/webhook`. The API returns immediately with a `request_id`, and results are sent to your callback URL when transcription completes. The optional `metadata` parameter (JSON string) is passed through to your callback.
```

--------------------------------

### Alias Endpoints

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/pre-recorded-audio

The following endpoints are aliases and function identically to the primary /v1/listen and /v1/listen/url endpoints.

```APIDOC
## Alias Endpoints

### Description
These endpoints serve as aliases for the primary `/v1/listen` and `/v1/listen/url` endpoints, providing alternative routes for the same functionality.

### Method
POST

### Endpoints
- `/v1/listen/media` (Alias for `/v1/listen`)
- `/v1/listen/media/transcribe` (Alias for `/v1/listen`)
- `/v1/listen/media/transcribe_file` (Alias for `/v1/listen`)
- `/v1/listen/media/url` (Alias for `/v1/listen/url`)

### Parameters
(Refer to the documentation for `/v1/listen` and `/v1/listen/url` for detailed parameter information.)

### Request Example
(Same as `/v1/listen` or `/v1/listen/url` depending on the alias used.)

### Response
(Same as `/v1/listen` or `/v1/listen/url` depending on the alias used.)
```

--------------------------------

### Send Binary Audio Data (Client to Server)

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/streaming-audio

Sends binary audio data to the streaming audio API. Supported formats include raw PCM (16-bit signed little-endian) for both endpoints, and encoded formats like MP3, AAC, FLAC, WAV, OGG, WebM, Opus, and M4A, which are supported by the primary endpoint only.

```binary
Binary audio data in one of the following formats:

• Raw PCM: 16-bit signed little-endian (s16le)
  - Supported by both /v1/listen and /v1/listen/pcm
  
• Encoded formats: MP3, AAC, FLAC, WAV, OGG, WebM, Opus, M4A
  - Supported by /v1/listen only
  - Auto-detected from format hints or binary headers
```

--------------------------------

### Pre-Recorded Audio - URL

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/pre-recorded-audio

Accepts a URL string in the request body for transcription of audio hosted online.

```APIDOC
## POST /v1/listen/url

### Description
This endpoint accepts a URL string in the request body pointing to an audio file for transcription. It is a convenience endpoint for directly transcribing audio hosted online.

### Method
POST

### Endpoint
https://api.aldea.ai/v1/listen/url

### Headers
- **Authorization** (string) - Required - Bearer token; required for all API requests.
- **timestamps** (string) - Optional - Set to "true" to include per-word timestamps in response.

### Query Parameters
- **callback** (string) - Optional - URL to send results asynchronously. When provided, the request returns immediately with a `request_id`.
- **callback_method** (string) - Optional - HTTP method for the callback URL. Defaults to POST.
- **metadata** (string) - Optional - JSON string that will be passed through to the callback.
- **diarization** (boolean) - Optional - Enable speaker diarization to identify different speakers.
- **keywords** (string) - Optional - Comma-separated list of keywords or phrases to boost recognition accuracy. Example: `?keywords=John Doe,Acme Corp`
- **language** (string) - Optional - Language identifier in BCP-47 format (e.g., `"en-US"`). Accepts `lang` as an alias. Spanish can be indicated with `"es"` or `"es-ES"`.

### Request Body
Send an HTTP/HTTPS URL string pointing to the audio file in the request body. The API will download and process the audio. Supported formats include MP3, AAC, FLAC, WAV, OGG, WebM, Opus, M4A, and 16-bit PCM (s16le). Max duration defaults to 10 minutes (600 seconds).

### Request Example
```bash
API="https://api.aldea.ai/v1/listen/url"
TOKEN="$STT_API_TOKEN"
AUDIO_URL="https://example.com/path/to/your/audio.wav"

curl -s -X POST "$API" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/plain" \
  --data "$AUDIO_URL"
```

### Response
#### Success Response (200)
- **metadata** (object) - Contains metadata about the request, including `request_id`, `created` timestamp, `duration`, and `channels`.
- **results** (object) - Contains the transcription results, including alternatives with `transcript`, `confidence`, and `words` (if timestamps are enabled).

#### Response Example
```json
{
  "metadata": {
    "request_id": "77aaccd1-3b19-4000-9055-3f91009751b4",
    "created": "2025-01-01T00:00:00.000000Z",
    "duration": 6.916625,
    "channels": 1
  },
  "results": {
    "channels": [
      {
        "alternatives": [
          {
            "transcript": "Something, you know, it's just like I'm saying, it's a it's a next level. It's like there's I mean, when we give you a show now, you're gonna get",
            "confidence": 0.802,
            "words": [
              {
                "word": "Something,",
                "start": 0.04,
                "end": 0.36
              },
              {
                "word": "you",
                "start": 0.44,
                "end": 0.52
              }
            ]
          }
        ]
      }
    ]
  }
}
```

### Async Processing
For long audio files or when you need non-blocking processing, use the `callback` query parameter. Include `?callback=https://your-server.com/webhook`. The API returns immediately with a `request_id`, and results are sent to your callback URL when transcription completes. The optional `metadata` parameter (JSON string) is passed through to your callback.
```

--------------------------------

### PCM Audio Transcription

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/streaming-audio

This endpoint is specifically for transcribing audio that has already been decoded into PCM format.

```APIDOC
## POST /v1/listen/pcm

### Description
Processes decoded PCM audio streams for speech-to-text conversion. This endpoint is optimized for clients that handle audio decoding themselves.

### Method
POST

### Endpoint
/v1/listen/pcm

### Query Parameters
- **redact** (string) - Optional - Specifies PII redaction types (e.g., 'pii', 'pci'). Can be combined.
- **redact_mode** (string) - Optional - Controls the anonymization style ('mask', 'redact', or 'replace').
- **keywords** (string) - Optional - A comma-separated list of terms to boost.
- **keyword_boost** (number) - Optional - The boost strength for keywords (default: 2.0).

### Request Body
- **audio_data** (binary) - Required - The raw PCM audio data to be transcribed.

### Response
#### Success Response (200)
- **results** (array) - Contains transcription results, including interim/final results and word timestamps if enabled.
- **Metadata** (object) - Additional metadata about the transcription.
- **SpeechStarted** (object) - Indicates the start of speech detection.
- **UtteranceEnd** (object) - Indicates the end of an utterance (requires word timestamps).

#### Response Example
```json
{
  "results": [
    {
      "type": "final",
      "alternatives": [
        {
          "content": "processed pcm audio"
        }
      ]
    }
  ],
  "metadata": {
    "request_id": "xyz-789"
  }
}
```
```

--------------------------------

### Streaming Audio API

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/streaming-audio

This endpoint facilitates real-time speech-to-text transcription using WebSockets. It supports both encoded audio formats and raw PCM data. An optimized endpoint is available specifically for raw PCM.

```APIDOC
## Streaming Audio API

### Description
This endpoint facilitates real-time speech-to-text transcription using WebSockets. It supports both encoded audio formats and raw PCM data. An optimized endpoint is available specifically for raw PCM.

### Method
GET (WebSocket upgrade)

### Endpoints
**Primary Endpoint (Supports encoded audio and raw PCM):**
- `wss://api.aldea.ai/v1/listen`
**PCM-Only Endpoint (Optimized for raw PCM):**
- `wss://api.aldea.ai/v1/listen/pcm`

*Note: Both URLs are aliases and function identically.

### Headers
- **Authorization** (string) - Required - Bearer token; required for all API requests.
- **Content-Type** (string) - Optional - Audio format hint (e.g., `audio/mpeg`, `audio/wav`). Used for format detection.

### Query Parameters
- **sample_rate** (number) - Optional - Client audio sample rate in Hz; server resamples to 16 kHz for inference. Default: `16000`.
- **interim_results** (boolean) - Optional - Emit interim updates while streaming. Default: `true`.
- **endpointing** (number) - Optional - Controls sentence finalization latency. Default: `false`.
- **encoding** (string) - Optional - Audio encoding format (pcm, mp3, aac, flac, wav, ogg, webm, opus, m4a). Also accepts format or codec as aliases. Default: `auto-detect`.
- **redact** (string) - Optional - Enable PII redaction. Can be repeated multiple times. Values: `pii` (person names, emails, phone numbers, addresses, SSN), `pci` (credit cards, bank numbers), `numbers` (dates, phone numbers, SSN, credit cards), `true` (all PII types). Example: `?redact=pii&redact=pci`.
- **keywords** (string) - Optional - Comma-separated list of keywords or phrases to boost recognition accuracy. Example: `?keywords=John Doe,Acme Corp`.
- **language** (string) - Optional - Language identifier in BCP-47 format (e.g., `"en-US"`). Also accepts `lang` as alias. Spanish can be indicated with `"es"` or `"es-ES"`.

### Client → Server Messages
**Audio Data:**
Binary audio data in one of the following formats:
  * Raw PCM: 16-bit signed little-endian (s16le) frames (Supported by both `/v1/listen` and `/v1/listen/pcm`)
  * Encoded formats: MP3, AAC, FLAC, WAV, OGG, WebM, Opus, M4A (Supported by `/v1/listen` only; auto-detected from format hints or binary headers)

**Control Messages:**
```json
{ "type": "Finalize" }
```

```json
{ "type": "CloseStream" }
```

```json
{ "type": "KeepAlive" }
```

### Server → Client Messages
#### Metadata Response
```json
{
  "type": "Metadata",
  "request_id": "...",
  "created": "2025-01-01T00:00:00.000000Z",
  "duration": 0.0,
  "channels": 1,
  "model_info": {
    "name": "<model_id>",
    "version": "",
    "arch": "aldea-asr"
  }
}
```

#### SpeechStarted Response
```json
{
  "type": "SpeechStarted",
  "channel": [0],
  "timestamp": 0.0
}
```

#### Results Response
```json
{
  "type": "Results",
  "channel_index": [0],
  "duration": 1.98,
  "start": 0.00,
  "is_final": false,
  "speech_final": false,
  "channel": {
    "alternatives": [
      {
        "transcript": "Hello world",
        "confidence": 0.95,
        "words": [
          ["Hello", 0, 320],
          ["world", 320, 640]
        ]
      }
    ]
  },
  "metadata": {
    "request_id": "...",
    "model_info": {
      "name": "<model>",
      "version": null,
      "arch": "aldea-asr"
    }
  }
}
```

#### UtteranceEnd Response
```json
{
  "type": "UtteranceEnd",
  "channel": [0],
  "last_word_end": 2.5
}
```

### Supported Audio Formats
**Encoded Formats (via `/v1/listen`):**
  * MP3, AAC, FLAC, WAV, OGG, WebM, Opus, M4A
  * Auto-detected from format hints or binary headers

**Raw PCM (via `/v1/listen/pcm`):**
  * 16-bit signed little-endian (s16le)
  * 16kHz sample rate (configurable via `sample_rate` param)
  * Mono channel (auto-converted)
```

--------------------------------

### Receive Results Message (Server to Client)

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/streaming-audio

Receives a JSON message from the server containing transcription results. This message includes interim or final transcriptions, confidence scores, word timings, and associated metadata. The `is_final` and `speech_final` flags indicate the status of the transcription.

```json
{
  "type": "Results",
  "channel_index": [0],
  "duration": 1.98,
  "start": 0.00,
  "is_final": false,
  "speech_final": false,
  "channel": {
    "alternatives": [{
      "transcript": "Hello world",
      "confidence": 0.95,
      "words": [
        ["Hello", 0, 320],
        ["world", 320, 640]
      ]
    }]
  },
  "metadata": {
    "request_id": "...",
    "model_info": {
      "name": "<model>",
      "version": null,
      "arch": "aldea-asr"
    }
  }
}
```

--------------------------------

### Receive Metadata Message (Server to Client)

Source: https://st-frontend.aldea.ai/docs/stt-api-reference/streaming-audio

Receives a JSON message from the server containing metadata about the transcription session. This includes information like request ID, creation timestamp, audio duration, channel details, and the ASR model used.

```json
{
  "type": "Metadata",
  "request_id": "...",
  "created": "2025-01-01T00:00:00.000000Z",
  "duration": 0.0,
  "channels": 1,
  "model_info": {
    "name": "<model_id>",
    "version": "",
    "arch": "aldea-asr"
  }
}
```