Migration guides / WellSaid
WellSaid alternative: move your WellSaid API to Cartesia
WellSaid's default API key allows 1,000 characters a request and 3 requests a second, which decides how you batch every long script.
Migrate from WellSaid with your coding agent
Paste this into Claude Code, Cursor or Codex in the repo that calls WellSaid. It carries the field mapping, the Cartesia request and a rollout that keeps WellSaid behind a flag until you switch.
Prompt
Move this codebase from WellSaid to Cartesia for text to speech. Keep WellSaid working behind a flag until I switch over.
## 1. Find the calls
Search for `api.wellsaidlabs.com` or `WELLSAID_API_KEY`. The request to replace is `POST https://api.wellsaidlabs.com/v1/tts/stream`. List every call site before you edit anything.
## 2. Target
- Request: `POST https://api.cartesia.ai/tts/bytes`
- Model: `model_id: "sonic-3.6"`
- Headers: `X-API-Key` read from the `CARTESIA_API_KEY` environment variable, and `Cartesia-Version: 2026-08-14`
- Auth swap: WellSaid sends the key in `X-Api-Key` header. Replace it with `X-API-Key` from `CARTESIA_API_KEY` on the Cartesia path only, and keep WellSaid's key for the WellSaid path. You request an API trial key after creating an account. Paid API plans go through sales.
- Add `CARTESIA_API_KEY` wherever the project documents its environment (`.env.example`, README, deploy config). Never hardcode the key.
- Request size: WellSaid caps a request at 1,000 characters per request. Cartesia publishes no per-request maximum, so keep any chunking the code already does and split at sentence boundaries; for long text, stream over the Cartesia TTS WebSocket.
- Concurrency: WellSaid allows 3 requests per second on the default API key. Look up the Cartesia plan's concurrent request limit at https://www.cartesia.ai/pricing, cap parallel requests at it, and retry rate-limit errors with backoff.
- Voice IDs don't carry over. Keep each voice ID in one named constant or config value, put a placeholder where each WellSaid voice was, and list them for me so I can pick replacements at https://www.cartesia.ai/voices.
- Suggested starting points to put in those placeholders, for me to confirm by ear: Alana B. (3), clear US narration → `f0377496-2708-4cc9-b2f8-1b7fdb5e1a2a` (Elaine - Confident Guide); Wade C. (30), calm, deep US narration → `ed82c17b-4704-4d34-be43-5d19065acdf1` (Carl - Steady Storyteller); Ramona J. (5), friendly promo → `58fbaf73-d7de-4e82-a6b3-118180e7057c` (Janet - Sunny Speaker); Joe F. (28), promo with gravitas → `dbfa416f-d5c3-4006-854b-235ef6bdf4fd` (Damon - Commanding Narrator).
## 3. Field mapping, WellSaid → Cartesia
- `POST https://api.wellsaidlabs.com/v1/tts/stream` → `POST /tts/bytes`
- `X-Api-Key` header → `X-API-Key` and `Cartesia-Version: 2026-08-14`. Same header name. Add the version header.
- `speaker_id`: a numeric avatar ID such as `3` → `voice`: `{"id": "<voice id>"}`. Avatar IDs don't carry over. Pick a library voice per avatar.
- `text` (1,000 characters at most) → `transcript`
- `model`: `caruso` or `legacy` → `model_id`: `sonic-3.6`. WellSaid falls back to `legacy` when `model` is missing. Always send `model_id` on Cartesia.
- `audio_configs.file_format`: `mp3`, `wav` or `s16le` → `output_format.container`: `mp3`, `wav` or `raw` with `pcm_s16le`
- `audio_configs.sample_rate` (8000 to 96000) → `output_format.sample_rate` (8000 to 48000). Rates above 48000 have no equivalent. Resample if your pipeline needs them.
- `X-Enable-SSML: true` (limited SSML) → SSML-style tags in `transcript`: `break`, `spell`, `emotion`, `speed`, `volume`. No header needed. Check each tag you send today against [Cartesia's list](https://docs.cartesia.ai/build-with-cartesia/capability-guides/ssml-tags).
- `library_ids` (replacement libraries) → `pronunciation_dict_id` (one dictionary). Copy each library's replacements into one Cartesia dictionary.
## 4. Reference request
Match the language and HTTP client the codebase already uses. This is the same request in Python:
```python
import os
import requests
text = "Module four covers the new expense policy. Receipts over fifty dollars need a manager's approval."
VOICE_ID = "f0377496-2708-4cc9-b2f8-1b7fdb5e1a2a" # from /voices
response = requests.post(
"https://api.cartesia.ai/tts/bytes",
headers={
"X-API-Key": os.environ["CARTESIA_API_KEY"],
"Cartesia-Version": "2026-08-14",
},
json={
"model_id": "sonic-3.6",
"transcript": text,
"voice": {"id": VOICE_ID},
"language": "en",
"output_format": {
"container": "mp3",
"sample_rate": 44100,
"bit_rate": 128000,
},
},
)
response.raise_for_status()
open("out.mp3", "wb").write(response.content)
```
## 5. Roll out
1. Choose WellSaid or Cartesia per request from one config flag, defaulting to WellSaid.
2. Run the same scripts through both and save the clips side by side for me to listen to. Check that the container, encoding and sample rate match what downstream code expects.
3. Leave the WellSaid client, call and key in place so rollback is flipping the flag. Don't delete them in this change.
4. Run the existing tests, and add one that checks the Cartesia request body.
## Docs
- WellSaid TTS stream API reference: https://docs.wellsaidlabs.com/reference/ttsstream
- WellSaid getting started: https://docs.wellsaidlabs.com/docs/getting-started-1
- WellSaid model selection: https://docs.wellsaidlabs.com/reference/model-selection-with-the-api
- WellSaid voice avatars: https://docs.wellsaidlabs.com/reference/available-voice-avatars
- Cartesia TTS bytes API reference: https://docs.cartesia.ai/api-reference/tts/bytes
- Cartesia SSML tags: https://docs.cartesia.ai/build-with-cartesia/capability-guides/ssml-tags
When you're done, tell me which files changed, which fields you couldn't map, and how to flip the flag.Every WellSaid field, mapped to Cartesia
The prompt carries this table. Each row is a field in your WellSaid request and the Cartesia field that replaces it.
- WellSaid
POST https:// api.wellsaidlabs.com/ v1/ tts/ stream CartesiaPOST /tts/bytes - WellSaid
X-Api-KeyheaderCartesiaX-API-KeyandCartesia-Version: 2026-08-14NoteSame header name. Add the version header. - WellSaid
speaker_id: a numeric avatar ID such as3Cartesiavoice:{"id": "<voice id>"}NoteAvatar IDs don't carry over. Pick a library voice per avatar. - WellSaid
text(1,000 characters at most)Cartesiatranscript - WellSaid
model:carusoorlegacyCartesiamodel_id:sonic-3.6NoteWellSaid falls back tolegacywhenmodelis missing. Always sendmodel_idon Cartesia. - WellSaid
audio_configs.file_format:mp3,wavors16leCartesiaoutput_format.container:mp3,wavorrawwithpcm_s16le - WellSaid
audio_configs.sample_rate(8000 to 96000)Cartesiaoutput_format.sample_rate(8000 to 48000)NoteRates above 48000 have no equivalent. Resample if your pipeline needs them. - WellSaid
X-Enable-SSML: true(limited SSML)CartesiaSSML-style tags intranscript:break,spell,emotion,speed,volumeNoteNo header needed. Check each tag you send today against Cartesia's list. - WellSaid
library_ids(replacement libraries)Cartesiapronunciation_dict_id(one dictionary)NoteCopy each library's replacements into one Cartesia dictionary.
WellSaid API key and auth, mapped to Cartesia
Cartesia reads the key from the X-API-Key header and pins the API version with Cartesia-Version on every request.
- WellSaid
X-Api-KeyheaderCartesiaX-API-KeyplusCartesia-Version: 2026-08-14NoteYou request an API trial key after creating an account. Paid API plans go through sales.
WellSaid API pricing per 1,000 characters
List prices per 1,000 characters from the vendor's own pricing page. Plans, regions and volume discounts change what you pay.
- Model or plan
WellSaid API
WellSaidContact salesNoteNo API price on the pricing page. A trial key you request after signing up lasts 14 days and covers up to 50 calls. - Model or plan
Starter (studio app)
WellSaid$19 a monthNote$10 a month billed annually; 20 download minutes a month, English voices. Priced per download minute, not per character. - Model or plan
Pro (studio app)
WellSaid$49 a monthNote$33 a month billed annually; 180 download minutes a month, English voices
On Cartesia, usage draws from your plan's credits: 20,000 credits a month on the Free plan (about 20,000 characters). Enterprise pricing is custom.
Cartesia plans and pricingSources
Prices read from each company's pricing page in November 2026.
WellSaid limits compared with Cartesia
Published limits from both companies. Plans change them, so check both pages before you size a rollout.
- Limit
Free tier
Cartesia20,000 credits a month on the Free plan (about 20,000 characters)WellSaidTrial with 3 download minutes a month and no commercial rights - Limit
Request limit
CartesiaNo published maximum; stream long text over the TTS WebSocketWellSaid1,000 characters per request - Limit
Voices
Cartesia1,022 voices in the library, plus instant clonesWellSaidOver 200 voices and styles - Limit
Languages
Cartesia44 languages for text to speechWellSaidEnglish only on Starter and Pro; other languages on Enterprise
Cartesia's figures come from its pricing page and voice library.
Cartesia pricing and plan limitsSources
- WellSaid pricingwellsaid.io
- WellSaid API specificationsdocs.wellsaidlabs.com
- WellSaid API FAQdocs.wellsaidlabs.com
Limits read from each company's documentation in November 2026.
WellSaid voices and where to start on Cartesia
Voice avatars chosen by numeric speaker_id, each with a style such as Narration or Promo
Each card is a starting point for a common WellSaid pick, matched by language and use. Listen before you choose.
What you get on Cartesia
What changes once the WellSaid call is gone.
API prices on a public page
WellSaid publishes no API price; paid API plans go through its sales team. Cartesia's API rates are listed on /pricing, and you can start on the Free plan.
Localize past English
WellSaid's Starter and Pro plans include English voices only, and other languages come with Enterprise. Sonic 3.6 speaks 44, chosen per request with language.
Caption timing per word
Set add_timestamps on the TTS WebSocket and each audio chunk arrives with its words and their start and end times, ready for captions in a course player.
How to migrate from WellSaid to Cartesia
The same changes the prompt makes, if you'd rather make them yourself.
Create a Cartesia API key on the Free plan and render a lesson you already produced on WellSaid.
List the
speaker_idvalues you use and pick a library voice for each, starting from the pairs below.Swap the endpoint, headers and body as in the code above. Remove the code that splits scripts at 1,000 characters only after you've tested long passages over the WebSocket.
Export your replacement libraries into one Cartesia pronunciation dictionary, and check every SSML tag you send.
Run both behind a flag for a course or two, then retire the WellSaid key.
Sources
Request shapes checked against vendor documentation in November 2026.
Compare and read next
Frequently asked questions
How much does WellSaid Labs cost?
WellSaid's studio plans are Starter at $19 a month ($10 billed annually), Pro at $49 ($33 annually) and Business at $160 per user a month, billed annually. Those plans are priced in download minutes. The API has no published price; WellSaid sets API plans through sales.
Is WellSaid free?
WellSaid's free trial gives 3 download minutes a month with no commercial rights. An API trial key, requested after signup, runs 14 days and includes up to 50 API calls. Cartesia's Free plan gives 20,000 credits a month through the same API you'd use in production.
Does WellSaid support languages other than English?
On Enterprise. Starter and Pro list English voices only, and the caruso model speaks English only. If you're localizing training content, Sonic 3.6 covers 44 languages; check yours on the language list.
What doesn't carry over from WellSaid?
Avatar IDs, output above 48 kHz and any SSML tag outside Cartesia's five. Replacement libraries collapse into a single pronunciation dictionary per request.
Can I keep WellSaid as a fallback while I switch?
Yes, while your WellSaid contract runs. Route each course or module to one vendor from a config flag, so a whole lesson always uses one voice. If a module sounds wrong on Cartesia, point it back to WellSaid and try another library voice.
Get started today
Talk to an expert.
Connect with a member of our team and learn how Cartesia can help you build world-class voice experiences.
Start building.
Create an API key, then hand your coding agent the migration prompt and a few of your own scripts.