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 ELEVENLABSAPIKEY environment variable — never inline a

key in source. The SDK clients read the same value (process.env.ELEVENLABSAPIKEY

in Node, api_key=... in Python).

Prerequisites

• Current ElevenLabs SDK installed (Node or Python)
• ELEVENLABSAPIKEY 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/setapikey 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):

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

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

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):

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.