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.
- Check current versions — inspect installed Node/Python SDK versions and list
the models your account can reach.
- JS SDK package migration — uninstall the legacy community
elevenlabs
package, install @elevenlabs/elevenlabs-js, and update imports on an
upgrade/elevenlabs-sdk branch.
- 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.
- Voice settings migration — verify
stability, similarity_boost, style,
and speed against each model's capabilities.
- API endpoint changes — confirm the stable
/v1/ endpoints and adopt the
enhanced /v2/voices search where useful.
- 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.
- 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):
npm uninstall elevenlabs
npm install @elevenlabs/elevenlabs-js
git checkout -b upgrade/elevenlabs-sdk
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:
- Migrate a Node.js app off the legacy
elevenlabs community package —
branch, swap the package, update the client, and validate with a smoke test.
- Migrate a deprecated model with a WebSocket-safe fallback — move toward
eleven_v3 while keeping streaming working via automatic downgrade.
- 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):
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
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.
