AssemblyAI Upgrade & Migration Skill

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

Next Steps

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

Agent Skills: AssemblyAI Upgrade & Migration

Install this agent skill to your local

Skill Files