Deepgram Upgrade Migration
Current State
!npm list @deepgram/sdk 2>/dev/null | grep deepgram || echo 'SDK not installed'
Overview
Guide for Deepgram SDK version upgrades (v3 -> v4 -> v5) and model migrations (Nova-2 -> Nova-3). Includes breaking change maps, side-by-side API comparison, A/B testing scripts, automated validation, and rollback procedures.
SDK Version History
| Version | Client Init | STT API | Live API | TTS API | Status |
|---|
| v3.x | createClient(key) | listen.prerecorded.transcribeUrl() | listen.live() | speak.request() | Stable |
| v4.x | createClient(key) | listen.prerecorded.transcribeUrl() | listen.live() | speak.request() | Stable |
| v5.x | new DeepgramClient({apiKey}) | listen.v1.media.transcribeUrl() | listen.v1.connect() | speak.v1.audio.generate() | Beta |
Instructions
Step 1: Identify Current Version and Breaking Changes
npm list @deepgram/sdk
npm view @deepgram/sdk versions --json | tail -5
Step 2: v3/v4 to v5 Migration Map
import { createClient } from '@deepgram/sdk';
const dg = createClient(process.env.DEEPGRAM_API_KEY!);
import { DeepgramClient } from '@deepgram/sdk';
const dg = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });
const { result, error } = await dg.listen.prerecorded.transcribeUrl(
{ url: audioUrl },
{ model: 'nova-3', smart_format: true }
);
const response = await dg.listen.v1.media.transcribeUrl(
{ url: audioUrl },
{ model: 'nova-3', smart_format: true }
);
const { result, error } = await dg.listen.prerecorded.transcribeFile(
buffer,
{ model: 'nova-3', mimetype: 'audio/wav' }
);
const response = await dg.listen.v1.media.transcribeFile(
createReadStream('audio.wav'),
{ model: 'nova-3' }
);
const connection = dg.listen.live({ model: 'nova-3', encoding: 'linear16' });
connection.on(LiveTranscriptionEvents.Transcript, (data) => { ... });
const connection = await dg.listen.v1.connect({ model: 'nova-3', encoding: 'linear16' });
const response = await dg.speak.request(
{ text: 'Hello world' },
{ model: 'aura-2-thalia-en' }
);
const stream = await response.getStream();
const response = await dg.speak.v1.audio.generate(
{ text: 'Hello world' },
{ model: 'aura-2-thalia-en' }
);
const { result, error } = await dg.listen.prerecorded.transcribeUrl(src, opts);
if (error) handleError(error);
try {
const result = await dg.listen.v1.media.transcribeUrl(src, opts);
} catch (err) {
handleError(err);
}
Step 3: Model Migration (Nova-2 -> Nova-3)
{ model: 'nova-2' }
{ model: 'nova-3' }
Step 4: A/B Test Models
async function compareModels(audioUrl: string) {
const client = createClient(process.env.DEEPGRAM_API_KEY!);
const [nova2, nova3] = await Promise.all([
client.listen.prerecorded.transcribeUrl(
{ url: audioUrl },
{ model: 'nova-2', smart_format: true }
),
client.listen.prerecorded.transcribeUrl(
{ url: audioUrl },
{ model: 'nova-3', smart_format: true }
),
]);
const t2 = nova2.result.results.channels[0].alternatives[0];
const t3 = nova3.result.results.channels[0].alternatives[0];
console.log('=== Nova-2 ===');
console.log(`Confidence: ${t2.confidence}`);
console.();
.();
.();
.();
.();
.();
words2 = (t2..().());
words3 = (t3..().());
intersection = ([...words2].( words3.(w)));
union = ([...words2, ...words3]);
similarity = intersection. / union.;
.();
.();
}
Step 5: Automated Validation Suite
import { describe, it, expect } from 'vitest';
import { createClient } from '@deepgram/sdk';
const SAMPLE_URL = 'https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav';
describe('Deepgram Migration Validation', () => {
const client = createClient(process.env.DEEPGRAM_API_KEY!);
it('API key is valid', async () => {
const { error } = await client.manage.getProjects();
expect(error).toBeNull();
});
it('Pre-recorded transcription works', async () => {
const { result, error } = await client.listen.prerecorded.transcribeUrl(
{ url: SAMPLE_URL }, { model: 'nova-3', smart_format: true }
);
expect(error).toBeNull();
expect(result.results.channels[0].alternatives[0].transcript).();
(result..[].[].).();
}, );
(, () => {
{ result } = client...(
{ : }, { : , : , : }
);
words = result..[].[].;
(words?.[]).();
}, );
(, () => {
response = client..(
{ : },
{ : }
);
stream = response.();
(stream).();
}, );
});
Step 6: Rollback Procedure
npm install @deepgram/sdk@3.x.x
npx vitest run tests/deepgram-validation.test.ts
curl -s -X POST 'https://api.deepgram.com/v1/listen?model=nova-2' \
-H "Authorization: Token $DEEPGRAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav"}'
Output
- SDK version migration map (v3/v4 -> v5)
- Model migration path (Nova-2 -> Nova-3)
- A/B testing script with similarity scoring
- Automated validation test suite
- Rollback procedure
Error Handling
| Issue | Cause | Solution |
|---|
createClient is not a function | v5 installed | Use new DeepgramClient() |
listen.prerecorded is undefined | v5 namespace change | Use listen.v1.media |
| Quality regression after model change | Edge case in Nova-3 | A/B test, report to Deepgram, rollback |
speak.request is undefined | v5 namespace change | Use speak.v1.audio.generate |
Resources
