Guide for planning and executing Deepgram SDK upgrades (v2 to v3), model migrations (Nova to Nova-2), and API version transitions with A/B testing, validation, and rollback procedures.
Document current SDK version (npm list @deepgram/sdk), model in use, and configuration. Review GitHub releases for breaking changes.
Update imports (createClient instead of new Deepgram), method calls (listen.prerecorded.transcribeUrl instead of transcription.preRecorded), and response handling (destructured { result, error }).
Switch from Nova to Nova-2 for improved accuracy (47 languages vs 36). The model parameter is a simple config change; all other options remain the same.
Compare models side-by-side on test audio: measure confidence scores, processing times, and transcript quality before committing.
Run automated validation: test API connectivity, pre-recorded transcription, and live transcription connection. Monitor dashboards for 30 minutes post-deploy.
Record deployment versions. Keep rollback instructions ready: revert package version, reinstall, verify tests, redeploy.
See detailed implementation for advanced patterns.
| Issue | Cause | Solution |
|---|---|---|
| Import errors | Old import syntax | Update to { createClient } |
| Method not found | API change | Use listen.prerecorded.transcribeUrl |
| Response structure | Destructuring change | Use { result, error } pattern |
| Quality regression | Model change | A/B test before committing |
| Type | Description | Risk |
|---|---|---|
| SDK Version | v2.x to v3.x | Medium (breaking changes) |
| Model Migration | Nova to Nova-2 | Low (config change) |
| API Version | v1 to v2 | High (endpoint changes) |
// Old: import Deepgram from '@deepgram/sdk'
// New:
import { createClient } from '@deepgram/sdk';
const deepgram = createClient(apiKey);
const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
{ url: audioUrl }, { model: 'nova-2', smart_format: true }
);