ElevenLabs Upgrade & Migration

Overview

Guide for upgrading the ElevenLabs SDK and migrating between model generations. Covers the JS SDK package rename (community elevenlabs → official @elevenlabs/elevenlabs-js), model ID changes across generations, voice-settings evolution, and API endpoint stability.

Work the seven steps below at a high level from this file; drill into references/migration-guide.md for the full command set and per-step code, and references/examples.md for three end-to-end worked scenarios.

Authentication

All API calls authenticate with an account API key passed as the xi-api-key header. Store it in the ELEVENLABS_API_KEY environment variable — never inline a key in source. The SDK clients read the same value (process.env.ELEVENLABS_API_KEY in Node, api_key=... in Python).

Prerequisites

• Current ElevenLabs SDK installed (Node or Python)
• ELEVENLABS_API_KEY exported in the environment
• Git for version control
• Test suite available
• Staging environment for validation

Instructions

The migration is a seven-step, branch-isolated workflow. Read package manifests and config with Read, apply import/model changes with Edit, add new config files (e.g. config/models.ts) with Write, and run the npm/pip/git commands via Bash. Full commands and code for each step are in references/migration-guide.md.

1. Check current versions — inspect installed Node/Python SDK versions and list

the models your account can reach.

1. JS SDK package migration — uninstall the legacy community elevenlabs

package, install @elevenlabs/elevenlabs-js, and update imports on an upgrade/elevenlabs-sdk branch.

1. Model migration — map deprecated model IDs to current generations using the

migration table, and add a selectModel() helper that falls back off eleven_v3 when WebSocket streaming is required.

1. Voice settings migration — verify stability, similarity_boost, style,

and speed against each model's capabilities.

1. API endpoint changes — confirm the stable /v1/ endpoints and adopt the

enhanced /v2/voices search where useful.

1. Python SDK upgrade — upgrade, pin the version in requirements.txt, and move

from the old module-level generate/set_api_key API to the client object.

1. Validation — run tests plus a TTS smoke test and a voice-list check.

The essential skeleton for the highest-leverage step (the JS package swap):

bash
npm uninstall elevenlabs
npm install @elevenlabs/elevenlabs-js
git checkout -b upgrade/elevenlabs-sdk

typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const client = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
  maxRetries: 3,
  timeoutInSeconds: 60,
});

Model migration map

| Old Model | New Model | Migration Notes | |-----------|-----------|-----------------| | eleven_monolingual_v1 | eleven_multilingual_v2 | 29 languages; same voice IDs work | | eleven_multilingual_v1 | eleven_multilingual_v2 | Better emotional range; same API | | eleven_english_v1 | eleven_turbo_v2_5 | Lower latency; same voice_settings | | eleven_turbo_v2 | eleven_flash_v2_5 | Same quality, lower latency (~75ms) | | eleven_multilingual_v2 | eleven_v3 | Most expressive; 70+ languages; NO WebSocket support |

Full model-selection code, voice-settings and endpoint tables, the Python client migration, and the rollback procedure live in references/migration-guide.md.

Output

Working through this skill produces:

• An upgrade/elevenlabs-sdk branch with the package swap and updated imports.
• Updated dependency manifests — package.json on @elevenlabs/elevenlabs-js, or a

pinned elevenlabs== line in requirements.txt.

• A model-selection helper (config/models.ts) mapping quality/balanced/speed

preferences to current model IDs with a WebSocket-safe fallback.

• Validation evidence: a green test run, a 200 from the TTS smoke test, and a

non-empty voice-list count.

• A rollback path (pinned previous version or git revert) if validation fails.

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | Cannot find module | Old package name | Update import to @elevenlabs/elevenlabs-js | | model_not_found | Deprecated model ID | Map to current model (see table) | | WebSocket fails after model change | eleven_v3 doesn't support WS | Use eleven_flash_v2_5 or eleven_multilingual_v2 | | Voice settings ignored | Wrong parameter names | Verify stability, similarity_boost, style, speed |

Examples

Three complete, copy-pasteable walkthroughs are in references/examples.md:

1. Migrate a Node.js app off the legacy elevenlabs community package —

branch, swap the package, update the client, and validate with a smoke test.

1. Migrate a deprecated model with a WebSocket-safe fallback — move toward

eleven_v3 while keeping streaming working via automatic downgrade.

1. Upgrade the Python SDK from a pre-client generation — move to the client

object and pin the version for reproducible builds.

Minimal first example (the package swap and smoke test):

bash
git checkout -b upgrade/elevenlabs-sdk
npm uninstall elevenlabs && npm install @elevenlabs/elevenlabs-js
npm test
curl -s -o /dev/null -w "%{http_code}" \
  -X POST "https://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"text":"Upgrade test.","model_id":"eleven_flash_v2_5"}'

Resources

• Full migration guide (references/migration-guide.md)
• Worked examples (references/examples.md)
• ElevenLabs JS SDK Releases
• ElevenLabs Python SDK Changelog
• ElevenLabs Models
• ElevenLabs Changelog

Next Steps

For CI integration during upgrades, see the elevenlabs-ci-integration skill, which wires the smoke test and voice-list check into a pipeline gate so a bad SDK or model bump fails the build before it ships.