Deepgram SDKs with Aldea STT API

deepgram-sdk>=3.4.0httpx

pip install "deepgram-sdk>=3.4.0"

from deepgram import DeepgramClient, DeepgramClientEnvironmentALDEA_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)

import asynciofrom deepgram import DeepgramClient, DeepgramClientEnvironmentasync 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())

{  "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": []      }]    }]  }}

import asynciofrom deepgram import DeepgramClient, DeepgramClientEnvironmentasync 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())

{  "metadata": {    "channels": 1,    "created": "2026-01-08T15:39:40.011380Z",    "duration": 25.561875,    "models": ["2304fa8b..."],    "request_id": "e1f63e0b-7c71-4f90-a281-290ad284daf5"  },  "results": {    "channels": [{      "alternatives": [{        "confidence": 0.0,        "transcript": "As much as it's worth celebrating...",        "words": []      }]    }]  }}

import asynciofrom deepgram import DeepgramClient, DeepgramClientEnvironmentasync 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())

{  "metadata": {    "channels": 1,    "duration": 1.5,    "models": ["2304fa8b..."],    "request_id": "abc12345-..."  },  "results": {    "channels": [{      "alternatives": [{        "confidence": 0.0,        "transcript": "Hey, how are you?",        "words": []      }]    }]  }}

import threadingimport httpximport asyncioimport sysfrom deepgram import DeepgramClient, DeepgramClientEnvironmentfrom deepgram.core.events import EventTypefrom deepgram.extensions.types.sockets import ListenV1SocketClientResponseasync 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)

{  "type": "Results",  "channel_index": [0, 1],  "duration": 1.5,  "start": 0.0,  "is_final": true,  "speech_final": true,  "channel": {    "alternatives": [{      "transcript": "hello world",      "confidence": 0.98,      "words": [        {"word": "hello", "start": 0.0, "end": 0.5, "confidence": 0.99},        {"word": "world", "start": 0.6, "end": 1.0, "confidence": 0.97}      ]    }]  }}