Migrate your ElevenLabs TTS to Cartesia

Move this codebase from ElevenLabs to Cartesia for text to speech. Keep ElevenLabs working behind a flag until I switch over.

December 31, 2026: ElevenLabs Default voices expire. ElevenLabs says every Default voice expires on this date and stops being accessible. If your app calls a Default voice ID, you have to choose a new voice before then on either platform. (https://elevenlabs.io/docs/overview/capabilities/voices)

## 1. Find the calls
Search for `api.elevenlabs.io` or `ELEVENLABS_API_KEY`. The request to replace is `POST /v1/text-to-speech/{voice_id}`. 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: ElevenLabs sends the key in `xi-api-key` header from `ELEVENLABS_API_KEY`. Replace it with `X-API-Key` from `CARTESIA_API_KEY` on the Cartesia path only, and keep `ELEVENLABS_API_KEY` for the ElevenLabs path. An ElevenLabs API key can be scoped to certain endpoints, given a credit quota or locked to allowlisted IPs. Write those rules down before you retire the key.
- Add `CARTESIA_API_KEY` wherever the project documents its environment (`.env.example`, README, deploy config). Never hardcode the key.
- Request size: ElevenLabs caps a request at 10,000 characters per request on Eleven v4 and Multilingual v2, 5,000 on v3, 40,000 on Flash v2.5. 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: ElevenLabs allows Multilingual v2 allows 2 concurrent requests on Free, 3 on Starter, 5 on Creator, 10 on Pro and 15 on Scale or Business; Flash allows twice that. 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 ElevenLabs 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: Audiobook or long-form narration, male → `ed82c17b-4704-4d34-be43-5d19065acdf1` (Carl - Steady Storyteller); Audiobook or long-form narration, female → `a33f7a4c-100f-41cf-a1fd-5822e8fc253f` (Lauren - Lively Narrator); Support agent on a call, female → `9626c31c-bec5-4cca-baa8-f8ba9e84c8bc` (Jacqueline - Reassuring Agent); Onboarding or support agent, male → `a5136bf9-224c-4d76-b823-52bd5efcffcc` (Jameson - Easygoing Support).

## 3. Field mapping, ElevenLabs → Cartesia
- `POST /v1/text-to-speech/{voice_id}` → `POST /tts/bytes`. The voice moves from the path into the body.
- `xi-api-key` header → `X-API-Key` and `Cartesia-Version: 2026-08-14`
- `voice_id` in the path → `voice`: `{"id": "<voice id>"}`. Voice IDs are specific to each vendor and never carry over.
- `text` → `transcript`
- `model_id`: `eleven_multilingual_v2`, `eleven_flash_v2_5` or `eleven_v4` → `model_id`: `sonic-3.6`
- `language_code` → `language`, such as `en` or `en-GB`. `eleven_multilingual_v2` rejects `language_code`, so many ElevenLabs requests leave it out. Set `language` on every Cartesia request.
- `voice_settings.speed` → `generation_config.speed` (0.6 to 1.5)
- `voice_settings`: `stability`, `similarity_boost`, `style` → `generation_config.emotion`, plus the voice you pick. These knobs have no one-to-one match. Render the same script on both vendors and judge by ear.
- Audio tags such as `[whispering]` or `[laughing]` (v3 and v4) → An `<emotion>` tag in the `transcript`. An `<emotion>` tag shifts the tone mid-line. Sound effects such as `[applause]` have no match.
- `output_format` query parameter, such as `pcm_16000` or `ulaw_8000` → `output_format` object in the body, such as `raw` with `pcm_mulaw` at 8000
- `POST /v1/text-to-speech/{voice_id}/with-timestamps` (character alignment) → TTS WebSocket with `add_timestamps` or `add_phoneme_timestamps`. `/tts/bytes` returns no timing. Cartesia times words and phonemes, and has no character-level alignment.
- `previous_text`, `next_text`, `previous_request_ids`, `next_request_ids` → One WebSocket `context_id` with `continue: true`. `/tts/bytes` has no stitching fields. Send a long passage as chunks in one context so the prosody carries across.
- `pronunciation_dictionary_locators` (up to 3) → `pronunciation_dict_id` (one dictionary). Merge your dictionaries into one before you upload it.

## 4. ElevenLabs fields with no Cartesia equivalent
- `voice_settings.use_speaker_boost`. What to do: Drop the field and choose a voice that already sits close to the original speaker.

## 5. 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 = "Chapter one. The lighthouse keeper had not seen a ship in eleven days."
VOICE_ID = "6ccbfb76-1fc6-48f7-b71d-91ac6298247b"  # 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": "raw",
            "encoding": "pcm_s16le",
            "sample_rate": 16000,
        },
    },
)
response.raise_for_status()
open("out.pcm", "wb").write(response.content)
```

## 6. Roll out
1. Choose ElevenLabs or Cartesia per request from one config flag, defaulting to ElevenLabs.
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 ElevenLabs 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
- ElevenLabs text-to-speech convert reference: https://elevenlabs.io/docs/api-reference/text-to-speech/convert
- ElevenLabs convert with timestamps reference: https://elevenlabs.io/docs/api-reference/text-to-speech/convert-with-timestamps
- ElevenLabs models: https://elevenlabs.io/docs/models
- ElevenLabs API authentication: https://elevenlabs.io/docs/api-reference/authentication
- ElevenLabs text-to-speech best practices (SSML and audio tags): https://elevenlabs.io/docs/overview/capabilities/text-to-speech/best-practices
- Cartesia TTS bytes API reference: https://docs.cartesia.ai/api-reference/tts/bytes
- Cartesia TTS WebSocket API reference: https://docs.cartesia.ai/api-reference/tts/websocket
- 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.