| name | elevenlabs-upgrade-migration |
| description | Upgrade ElevenLabs SDK versions and migrate between API model generations.
Use when upgrading the elevenlabs-js or elevenlabs Python SDK, migrating from
v1 to v2 models, or handling deprecations across the JS package rename and
model ID changes.
Trigger with: "upgrade elevenlabs", "elevenlabs migration",
"elevenlabs breaking changes", "update elevenlabs SDK",
"migrate elevenlabs model", "eleven_v3 migration".
|
| allowed-tools | Read, Write, Edit, Bash(npm:*), Bash(pip:*), Bash(git:*) |
| version | 1.6.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","voice","ai","elevenlabs","migration","upgrade"] |
| compatibility | Designed for Claude Code |
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.
