Deepgram SDK Patterns
Overview
Production patterns for @deepgram/sdk (TypeScript) and deepgram-sdk (Python). Covers singleton client, typed wrappers, text-to-speech with Aura, audio intelligence pipeline, error handling, and SDK v5 migration path.
Prerequisites
npm install @deepgram/sdk or pip install deepgram-sdkDEEPGRAM_API_KEY environment variable configured
Instructions
Step 1: Singleton Client (TypeScript)
import { createClient, DeepgramClient } from '@deepgram/sdk';
class DeepgramService {
private static instance: DeepgramService;
private client: DeepgramClient;
private constructor() {
const apiKey = process.env.DEEPGRAM_API_KEY;
if (!apiKey) throw new Error('DEEPGRAM_API_KEY is required');
this.client = createClient(apiKey);
}
static getInstance(): DeepgramService {
if (!this.instance) this.instance = new DeepgramService();
return this.instance;
}
getClient(): DeepgramClient { return this.client; }
}
export const deepgram = DeepgramService.getInstance().getClient();
Step 2: Text-to-Speech with Aura
import { createClient } from '@deepgram/sdk';
import { writeFileSync } from 'fs';
const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);
async function textToSpeech(text: string, outputPath: string) {
const response = await deepgram.speak.request(
{ text },
{
model: 'aura-2-thalia-en',
encoding: 'linear16',
container: 'wav',
sample_rate: 24000,
}
);
const stream = await response.getStream();
if (!stream) throw new Error('No audio stream returned');
const reader = stream.getReader();
const chunks: Uint8Array[] = [];
while (true) {
const { done, value } = await reader.read();
if (done) ;
chunks.(value);
}
buffer = .(chunks);
(outputPath, buffer);
.();
buffer;
}
Step 3: Audio Intelligence Pipeline
async function analyzeConversation(audioUrl: string) {
const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
{ url: audioUrl },
{
model: 'nova-3',
smart_format: true,
diarize: true,
utterances: true,
summarize: 'v2',
detect_topics: true,
sentiment: true,
intents: true,
}
);
if (error) throw error;
return {
transcript: result.results.channels[0].alternatives[0].transcript,
summary: result.results.summary?.short,
topics: result.results.topics?.segments?.( ({
: s.,
: s..( t.),
})),
: result..?.?.( ({
: s.,
: s.,
: s.,
})),
: result..?.?.( ({
: s.,
: s.[]?.,
: s.[]?.,
})),
};
}
Step 4: Python Production Patterns
from deepgram import DeepgramClient, PrerecordedOptions, LiveOptions, SpeakOptions
import os
class DeepgramService:
_instance = None
def __new__(cls):
if cls._instance is None:
cls._instance = super().__new__(cls)
cls._instance.client = DeepgramClient(os.environ["DEEPGRAM_API_KEY"])
return cls._instance
def transcribe_url(self, url: str, **kwargs):
options = PrerecordedOptions(
model=kwargs.get("model", "nova-3"),
smart_format=True,
diarize=kwargs.get("diarize", False),
summarize=kwargs.get("summarize", False),
)
source = {"url": url}
return self.client.listen.rest.v("1").transcribe_url(source, options)
def transcribe_file(self, path: str, **kwargs):
with open(path, "rb") as f:
source = {"buffer": f.read(), "mimetype": self._mimetype(path)}
options = PrerecordedOptions(
model=kwargs.get("model", "nova-3"),
smart_format=True,
diarize=kwargs.get(, ),
)
.client.listen.rest.v().transcribe_file(source, options)
():
options = SpeakOptions(model=, encoding=)
response = .client.speak.rest.v().save(output_path, {: text}, options)
response
() -> :
ext = path.rsplit(, )[-].lower()
{: , : , : ,
: , : }.get(ext, )
Step 5: Typed Response Helpers
interface TranscriptWord {
word: string;
start: number;
end: number;
confidence: number;
speaker?: number;
punctuated_word?: string;
}
interface TranscriptResult {
transcript: string;
confidence: number;
words: TranscriptWord[];
duration: number;
requestId: string;
}
function parseResult(result: any): TranscriptResult {
const alt = result.results.channels[0].alternatives[0];
return {
transcript: alt.transcript,
confidence: alt.confidence,
words: alt.words ?? [],
duration: result.metadata.duration,
requestId: result.metadata.request_id,
};
}
Step 6: SDK v5 Migration Notes
import { createClient } from '@deepgram/sdk';
const dg = createClient(apiKey);
await dg.listen.prerecorded.transcribeUrl(source, options);
await dg.listen.live(options);
await dg.speak.request({ text }, options);
import { DeepgramClient } from '@deepgram/sdk';
const dg = new DeepgramClient({ apiKey });
await dg.listen.v1.media.transcribeUrl(source, options);
await dg.listen.v1.connect(options);
await dg.speak.v1.audio.generate({ text }, options);
Output
- Singleton client pattern with environment validation
- Text-to-speech (Aura-2) with stream-to-file
- Audio intelligence pipeline (summary, topics, sentiment, intents)
- Python production service class
- Typed response helpers
- v5 migration reference
Error Handling
| Error | Cause | Solution |
|---|
401 Unauthorized | Invalid API key | Check DEEPGRAM_API_KEY value |
400 Unsupported format | Bad audio codec | Convert to WAV/MP3/FLAC |
speak.request is not a function | SDK version mismatch | Check import, v5 uses speak.v1.audio.generate |
| Empty TTS response | Empty text input | Validate text is non-empty before calling |
summarize returns null | Feature not enabled | Pass summarize: 'v2' (string, not boolean) |
Resources
Next Steps
Proceed to deepgram-data-handling for transcript storage and processing patterns.
