assemblyai-upgrade-migration

Analyze, plan, and execute AssemblyAI SDK upgrades with breaking change detection. Use when upgrading the assemblyai npm package, migrating from the old SDK, or switching between speech models (Best, Nano, Universal). Trigger with phrases like "upgrade assemblyai", "assemblyai migration", "assemblyai breaking changes", "update assemblyai SDK".

Ir para a instalação

Repositório: jeremylongshore/tons-of-skills-marketplace
Última atividade na origem: 17 de julho de 2026 às 22:18
Idioma detectado do SKILL.md: inglês
Estrelas: 2.677
Forks: 392

Opções de instalação

Por padrão, está selecionado o prompt que primeiro revisa a origem. Você pode mudar para um comando direto ou baixar uma cópia local.

Revise os arquivos de origem

Leia o SKILL.md e os arquivos complementares exibidos pelo SkillsMP antes de decidir se vai instalar.

Voltar à pesquisa Voltar à instalação

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 =  client..({ :  });
  .(page.. > , );

  .();
}

().(.);

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.