AssemblyAI Upgrade & Migration

Overview

Guide for upgrading the assemblyai npm package and migrating between SDK versions, including the major v3 to v4 migration and speech model transitions.

Prerequisites

• Current assemblyai package installed
• Git for version control
• Test suite available

Instructions

Step 1: Check Current Version

# Check installed version
npm list assemblyai

# Check latest available version
npm view assemblyai version

# See what changed
npm view assemblyai --json | jq '.versions[-5:]'

Step 2: Review Changelog

# View release notes
open https://github.com/AssemblyAI/assemblyai-node-sdk/releases

# Or check from CLI
gh release list --repo AssemblyAI/assemblyai-node-sdk --limit 10

Step 3: Create Upgrade Branch

git checkout -b upgrade/assemblyai-sdk-v$(npm view assemblyai version)
npm install assemblyai@latest
npm test

Step 4: Major Migration — Old SDK to Current (v4.x)

If migrating from @assemblyai/sdk (old package) to assemblyai (current):

// BEFORE (old package — @assemblyai/sdk)
import { AssemblyAI as OldClient } from '@assemblyai/sdk';
const client = new OldClient({ apiKey: '...' });

// AFTER (current package — assemblyai)
import { AssemblyAI } from 'assemblyai';
const client = new AssemblyAI({ apiKey: '...' });

# Remove old package, install new
npm uninstall @assemblyai/sdk
npm install assemblyai

Key changes in the migration:

Old (@assemblyai/sdk)	New (assemblyai)
import { AssemblyAI } from '@assemblyai/sdk'	import { AssemblyAI } from 'assemblyai'
client.transcripts.create()	client.transcripts.transcribe() (blocks until done)
Manual polling with client.transcripts.get()	transcribe() auto-polls, submit() for manual control
RealtimeTranscriber class	client.streaming.createService()
client.realtime.createTemporaryToken()	client.streaming.createTemporaryToken()

Step 5: Transcription Method Changes

// v3 pattern: create + poll loop
const job = await client.transcripts.create({ audio_url: url });
let transcript;
while (true) {
  transcript = await client.transcripts.get(job.id);
  if (transcript.status === 'completed' || transcript.status === 'error') break;
  await new Promise(r => setTimeout(r, 3000));
}

// v4 pattern: transcribe() handles everything
const transcript = await client.transcripts.transcribe({
  audio: url,  // Note: 'audio' not 'audio_url'
});

// v4 pattern: submit() for webhook-based (no polling)
const submitted = await client.transcripts.submit({
  audio: url,
  webhook_url: 'https://your-app.com/webhook',
});

Step 6: Streaming Migration

// v3 pattern: RealtimeTranscriber class
import { RealtimeTranscriber } from 'assemblyai';
const rt = new RealtimeTranscriber({ apiKey: '...' });
rt.on('transcript', (msg) => { /* ... */ });
await rt.connect();

// v4 pattern: client.streaming.createService()
const transcriber = client.streaming.createService({
  speech_model: 'nova-3',
  sample_rate: 16000,
});
transcriber.on('transcript', (msg) => { /* ... */ });
await transcriber.connect();

Step 7: Speech Model Migration

// Switch from legacy models to Universal-3
const transcript = await client.transcripts.transcribe({
  audio: audioUrl,
  speech_model: 'best',    // Uses Universal-3 (highest accuracy)
  // Other options: 'nano' (fastest, lowest cost)
  // Note: 'best' supports word_boost (up to 1000 terms)
});

// For streaming: nova-3 or nova-3-pro
const transcriber = client.streaming.createService({
  speech_model: 'nova-3-pro',  // Most accurate streaming model
  sample_rate: 16000,
});

Step 8: Verify After Upgrade

import { AssemblyAI } from 'assemblyai';

async function verifyUpgrade() {
  const client = new AssemblyAI({ apiKey: process.env.ASSEMBLYAI_API_KEY! });

  // Test async transcription
  const transcript = await client.transcripts.transcribe({
    audio: 'https://storage.googleapis.com/aai-web-samples/5_common_sports_702.wav',
  });
  console.assert(transcript.status === 'completed', 'Transcription should complete');
  console.assert(transcript.text && transcript.text.length > 0, 'Should have text');

  // Test LeMUR
  const { response } = await client.lemur.task({
    transcript_ids: [transcript.id],
    prompt: 'What is this about? Reply in one sentence.',
  });
  console.assert(response.length > 0, 'LeMUR should respond');

  // Test transcript listing
  const page = await client.transcripts.list({ limit: 1 });
  console.assert(page.transcripts.length > 0, 'Should list transcripts');

  console.log('All checks passed.');
}

verifyUpgrade().catch(console.error);

Output

• Updated assemblyai package to latest version
• Migrated import paths and method calls
• Updated streaming setup to current patterns
• Verified all API endpoints work post-upgrade

Error Handling

Issue	Cause	Solution
Cannot find module 'assemblyai'	Old package name	npm uninstall @assemblyai/sdk && npm install assemblyai
transcripts.create is not a function	API changed in v4	Use transcripts.transcribe() or transcripts.submit()
audio_url not recognized	Parameter renamed	Use audio instead of audio_url
Streaming not connecting	API changed	Use client.streaming.createService()
TypeScript errors	Type definitions changed	Update imports to match new types

Resources

• AssemblyAI Node SDK Releases
• AssemblyAI SDK Migration Guide
• AssemblyAI npm Package

Next Steps

For CI integration during upgrades, see assemblyai-ci-integration.