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.

9 fields mapped, with a rollback plan

Prompt

Connect MCP
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.

  1. WellSaid

    POST https://api.wellsaidlabs.com/v1/tts/stream

    Cartesia
    POST /tts/bytes
  2. WellSaid

    X-Api-Key header

    Cartesia
    X-API-Key and Cartesia-Version: 2026-08-14
    Note
    Same header name. Add the version header.
  3. WellSaid

    speaker_id: a numeric avatar ID such as 3

    Cartesia
    voice: {"id": "<voice id>"}
    Note
    Avatar IDs don't carry over. Pick a library voice per avatar.
  4. WellSaid

    text (1,000 characters at most)

    Cartesia
    transcript
  5. WellSaid

    model: caruso or legacy

    Cartesia
    model_id: sonic-3.6
    Note
    WellSaid falls back to legacy when model is missing. Always send model_id on Cartesia.
  6. WellSaid

    audio_configs.file_format: mp3, wav or s16le

    Cartesia
    output_format.container: mp3, wav or raw with pcm_s16le
  7. WellSaid

    audio_configs.sample_rate (8000 to 96000)

    Cartesia
    output_format.sample_rate (8000 to 48000)
    Note
    Rates above 48000 have no equivalent. Resample if your pipeline needs them.
  8. WellSaid

    X-Enable-SSML: true (limited SSML)

    Cartesia
    SSML-style tags in transcript: break, spell, emotion, speed, volume
    Note
    No header needed. Check each tag you send today against Cartesia's list.
  9. WellSaid

    library_ids (replacement libraries)

    Cartesia
    pronunciation_dict_id (one dictionary)
    Note
    Copy 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.

  1. WellSaid

    X-Api-Key header

    Cartesia
    X-API-Key plus Cartesia-Version: 2026-08-14
    Note
    You 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.

  1. Model or plan

    WellSaid API

    WellSaid
    Contact sales
    Note
    No API price on the pricing page. A trial key you request after signing up lasts 14 days and covers up to 50 calls.
  2. Model or plan

    Starter (studio app)

    WellSaid
    $19 a month
    Note
    $10 a month billed annually; 20 download minutes a month, English voices. Priced per download minute, not per character.
  3. Model or plan

    Pro (studio app)

    WellSaid
    $49 a month
    Note
    $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 pricing

Sources

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.

  1. Limit

    Free tier

    Cartesia
    20,000 credits a month on the Free plan (about 20,000 characters)
    WellSaid
    Trial with 3 download minutes a month and no commercial rights
  2. Limit

    Request limit

    Cartesia
    No published maximum; stream long text over the TTS WebSocket
    WellSaid
    1,000 characters per request
  3. Limit

    Voices

    Cartesia
    1,022 voices in the library, plus instant clones
    WellSaid
    Over 200 voices and styles
  4. Limit

    Languages

    Cartesia
    44 languages for text to speech
    WellSaid
    English only on Starter and Pro; other languages on Enterprise

Cartesia's figures come from its pricing page and voice library.

Cartesia pricing and plan limits

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.

  1. Create a Cartesia API key on the Free plan and render a lesson you already produced on WellSaid.

  2. List the speaker_id values you use and pick a library voice for each, starting from the pairs below.

  3. 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.

  4. Export your replacement libraries into one Cartesia pronunciation dictionary, and check every SSML tag you send.

  5. Run both behind a flag for a course or two, then retire the WellSaid key.

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.

Contact Sales

Start building.

Create an API key, then hand your coding agent the migration prompt and a few of your own scripts.

Try Cartesia