AldeaMigrate from Deepgram
Switch from Deepgram to Aldea with a 2-line code change
Aldea implements Deepgram-compatible APIs. If you already use a Deepgram SDK, you can switch to Aldea by changing the base URL and API key. The SDKs, request format, and response structure stay the same.
What changes
| Deepgram | Aldea | |
|---|---|---|
| REST base URL | https://api.deepgram.com | https://api.aldea.ai |
| WebSocket URL | wss://api.deepgram.com | wss://api.aldea.ai |
| API key prefix | dg_ | org_ |
| Auth header (REST) | Authorization: Token dg_... | Authorization: Bearer org_... |
| Auth header (WebSocket) | Sec-WebSocket-Protocol: token, dg_... | Sec-WebSocket-Protocol: token, org_... |
The API endpoints (/v1/listen), query parameters, and JSON response format are identical. Your existing parsing logic does not need to change.
Step 1: Get an Aldea API key
Sign up at platform.aldea.ai and generate an API key from the API Keys page. Your key starts with org_.
Step 2: Update the SDK configuration
The only code change is pointing the SDK to api.aldea.ai instead of api.deepgram.com.
The Python SDK uses DeepgramClientEnvironment to override the base URL. Replace your existing client setup:
Before (Deepgram):
from deepgram import DeepgramClient
client = DeepgramClient("dg_YOUR_DEEPGRAM_KEY")After (Aldea):
from deepgram import DeepgramClient, DeepgramClientEnvironment
config = DeepgramClientEnvironment(
base="https://api.aldea.ai",
production="wss://api.aldea.ai",
agent="wss://api.aldea.ai"
)
client = DeepgramClient(api_key="YOUR_ALDEA_API_KEY", environment=config)The rest of your code stays the same. Any calls to client.listen.v1.media.transcribe_file(), transcribe_url(), or client.listen.v1.connect() work without changes.
Requirements: Python 3.10+, deepgram-sdk>=3.4.0
The Node.js SDK accepts a global.url option to redirect all requests.
Before (Deepgram):
import { createClient } from "@deepgram/sdk";
const client = createClient({ key: "dg_YOUR_DEEPGRAM_KEY" });After (Aldea):
import { createClient } from "@deepgram/sdk";
const client = createClient({
key: "YOUR_ALDEA_API_KEY",
global: { url: "https://api.aldea.ai" }
});For pre-recorded transcription, use accessToken instead of key:
const client = createClient({
accessToken: "YOUR_ALDEA_API_KEY",
global: { url: "https://api.aldea.ai" }
});All client.listen.prerecorded and client.listen.live calls work as before.
The Go SDK accepts Host and AccessToken in ClientOptions.
Before (Deepgram):
client := dglisten.NewREST("dg_YOUR_DEEPGRAM_KEY", nil)After (Aldea):
client := dglisten.NewREST("", &dgi.ClientOptions{
Host: "https://api.aldea.ai",
AccessToken: "YOUR_ALDEA_API_KEY",
})The DoFile(), DoURL(), and WebSocket methods work identically.
Step 3: Verify it works
Run a quick test to confirm the migration. These examples use the same SDK methods you already have, just with the Aldea configuration from Step 2.
Pre-recorded transcription
with open("audio.wav", "rb") as f:
response = client.listen.v1.media.transcribe_file(request=f.read())
print(response.results.channels[0].alternatives[0].transcript)import fs from "fs";
const response = await client.listen.prerecorded.transcribeFile(
fs.createReadStream("audio.wav"),
{ mimetype: "audio/wav" }
);
const result = response?.result ?? response;
console.log(result.results.channels[0].alternatives[0].transcript);var resp Response
if err := client.DoFile(ctx, "audio.wav",
&dgi.PreRecordedTranscriptionOptions{}, &resp); err != nil {
panic(err)
}
fmt.Println(resp.Results.Channels[0].Alternatives[0].Transcript)Real-time streaming
import { createClient, LiveTranscriptionEvents } from "@deepgram/sdk";
const client = createClient({
key: "YOUR_ALDEA_API_KEY",
global: { url: "https://api.aldea.ai" }
});
const connection = client.listen.live({
encoding: "mp3",
interim_results: true
});
connection.on(LiveTranscriptionEvents.Transcript, (data) => {
const transcript = data?.channel?.alternatives?.[0]?.transcript;
if (transcript) console.log(transcript);
});
connection.on(LiveTranscriptionEvents.Open, async () => {
const stream = await fetch("http://icecast.omroep.nl/radio1-bb-mp3");
const reader = stream.body.getReader();
while (true) {
const { done, value } = await reader.read();
if (done) break;
connection.send(value);
}
});The Python and Go Deepgram SDKs may produce authentication errors during WebSocket streaming due to SDK-specific auth handling. Pre-recorded transcription works correctly with all SDKs. For streaming, use the Node.js SDK or connect via raw WebSocket.
Without the Deepgram SDK
If you prefer not to use a Deepgram SDK, you can call the API directly. The endpoint and response format are the same.
import httpx
response = httpx.post(
"https://api.aldea.ai/v1/listen",
headers={"Authorization": "Bearer YOUR_ALDEA_API_KEY"},
content=open("audio.wav", "rb").read(),
timeout=60.0
)
result = response.json()
print(result["results"]["channels"][0]["alternatives"][0]["transcript"])import { readFileSync } from "fs";
const response = await fetch("https://api.aldea.ai/v1/listen", {
method: "POST",
headers: { "Authorization": "Bearer YOUR_ALDEA_API_KEY" },
body: readFileSync("audio.wav")
});
const result = await response.json();
console.log(result.results.channels[0].alternatives[0].transcript);audioData, _ := os.ReadFile("audio.wav")
req, _ := http.NewRequest("POST",
"https://api.aldea.ai/v1/listen",
bytes.NewReader(audioData))
req.Header.Set("Authorization", "Bearer YOUR_ALDEA_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var result map[string]interface{}
json.Unmarshal(body, &result)
transcript := result["results"].(map[string]interface{})["channels"].([]interface{})[0].(map[string]interface{})["alternatives"].([]interface{})[0].(map[string]interface{})["transcript"].(string)
fmt.Println(transcript)Troubleshooting
| Error | Fix |
|---|---|
| Connection refused | Verify the base URL is https://api.aldea.ai |
| 401 Unauthorized | Check that your API key starts with org_ and is passed correctly |
| 503 Service Unavailable | Server is busy. Retry after the Retry-After header value |
| 415 Unsupported Media | Verify the audio format is supported (MP3, WAV, AAC, FLAC, OGG, WebM, Opus, M4A) |
ModuleNotFoundError (Python) | Run pip install "deepgram-sdk>=3.4.0" |
unknown deepgram error (streaming) | Python/Go SDK WebSocket auth issue. Use Node.js SDK or raw WebSocket for streaming |