Migration guides / Coqui TTS
Coqui TTS alternative: move XTTS-v2 to an API
If you self-host XTTS-v2, moving to Cartesia turns a GPU server and a model download into one HTTPS request.
What happened to Coqui TTS
The dated events that ended the Coqui TTS API, each linked to its source.
Last release of coqui-ai/TTS
v0.22.0 is the final release in Coqui's own repository. Fixes since then ship only in the Idiap fork, so a pinned TTS install gets no patches.
Migrate from Coqui TTS with your coding agent
Paste this into Claude Code, Cursor or Codex in the repo that calls Coqui TTS. It carries the field mapping, the Cartesia request and a rollout that keeps Coqui TTS behind a flag until you switch.
Prompt
Move this codebase from Coqui TTS to Cartesia for text to speech. Keep Coqui TTS working behind a flag until I switch over.
Company shut down on January 2024. Coqui, the company behind the `TTS` library and XTTS-v2, announced in early January 2024 that it was shutting down. The original `coqui-ai/TTS` repository last shipped a release, v0.22.0, on December 12, 2023. Idiap Research Institute maintains a fork published on PyPI as `coqui-tts`.
December 12, 2023: Last release of coqui-ai/TTS. v0.22.0 is the final release in Coqui's own repository. Fixes since then ship only in the Idiap fork, so a pinned `TTS` install gets no patches. (https://github.com/coqui-ai/TTS/releases)
## 1. Find the calls
Search for `TTS.api`. The request to replace is `TTS("tts_models/multilingual/multi-dataset/xtts_v2").to("cuda")`. 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: Coqui TTS sends the key in None; the library runs inside your own process. Replace it with `X-API-Key` from `CARTESIA_API_KEY` on the Cartesia path only, and keep Coqui TTS's key for the Coqui TTS path. Moving to an API adds a secret to manage. Keep it server-side.
- Add `CARTESIA_API_KEY` wherever the project documents its environment (`.env.example`, README, deploy config). Never hardcode the key.
- Voice IDs don't carry over. Keep each voice ID in one named constant or config value, put a placeholder where each Coqui TTS 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: Friendly assistant or app prompts → `db6b0ed5-d5d3-463d-ae85-518a07d3c2b4` (Skylar - Friendly Guide); Calm male narration → `98a34ef2-2140-4c28-9c71-663dc4dd7022` (Clyde - Calm Narrator); Expressive storytelling → `a33f7a4c-100f-41cf-a1fd-5822e8fc253f` (Lauren - Lively Narrator).
## 3. Field mapping, Coqui TTS → Cartesia
- `TTS("tts_models/multilingual/multi-dataset/xtts_v2").to("cuda")` → `POST /tts/bytes`. Nothing loads in your process. Each synthesis is one HTTPS request.
- No auth (the model runs in your own process) → `X-API-Key` and `Cartesia-Version: 2026-08-14`. Keep the key on your server, in `CARTESIA_API_KEY`.
- Model name `xtts_v2` → `model_id`: `sonic-3.6`
- `text` → `transcript`
- `speaker_wav`: a reference clip sent with every call → `voice`: `{"id": "<voice id>"}`. Clone the same clip once with `client.voices.clone(clip=..., language=..., name=...)` and store the ID it returns.
- `speaker`: a built-in XTTS speaker name → `voice`: `{"id": "<voice id>"}` from the voice library. Built-in XTTS speakers do not exist on Cartesia. Pick a library voice by role.
- `language`, one of 17 codes such as `en` or `zh-cn` → `language`, such as `en` or `en-GB`. Check each code you send against Cartesia's [language list](/languages).
- `file_path="out.wav"` → `output_format` with `container: wav`. The API returns audio bytes. Your code writes the file.
- `speed` (XTTS inference, default 1.0) → `generation_config.speed` (0.6 to 1.5)
- `model.inference_stream(...)` for chunked audio → TTS WebSocket. `/tts/bytes` also streams its response body as audio is generated.
- A fine-tuned XTTS checkpoint → Professional voice clone. Checkpoints do not transfer. A professional clone trains on 30 minutes of audio and needs a Startup plan or higher.
## 4. Coqui TTS fields with no Cartesia equivalent
- `temperature`, `top_k`, `top_p`, `repetition_penalty`, `length_penalty`. What to do: Drop them. Sonic 3.6 exposes no sampling parameters; choose the voice and emotion by ear.
## 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 = "Welcome back. Your next lesson starts in two minutes."
VOICE_ID = "6ccbfb76-1fc6-48f7-b71d-91ac6298247b" # from /voices, or your clone
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": "wav",
"encoding": "pcm_s16le",
"sample_rate": 24000,
},
},
)
response.raise_for_status()
open("out.wav", "wb").write(response.content)
```
## 6. Roll out
1. Choose Coqui TTS or Cartesia per request from one config flag, defaulting to Coqui TTS.
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 Coqui TTS 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
- coqui-ai/TTS README: https://github.com/coqui-ai/TTS
- Idiap coqui-ai-TTS fork: https://github.com/idiap/coqui-ai-TTS
- XTTS documentation (Idiap fork): https://coqui-tts.readthedocs.io/en/latest/models/xtts.html
- XTTS-v2 model card: https://huggingface.co/coqui/XTTS-v2
- Cartesia TTS bytes API reference: https://docs.cartesia.ai/api-reference/tts/bytes
- Cartesia voice cloning guide: https://docs.cartesia.ai/build-with-cartesia/capability-guides/clone-voices
When you're done, tell me which files changed, which fields you couldn't map, and how to flip the flag.Every Coqui TTS field, mapped to Cartesia
The prompt carries this table. Each row is a field in your Coqui TTS request and the Cartesia field that replaces it.
- Coqui TTS
TTS("tts_models/multilingual/ multi-dataset/ xtts_v2").to("cuda") CartesiaPOST /tts/bytesNoteNothing loads in your process. Each synthesis is one HTTPS request. - Coqui TTS
No auth (the model runs in your own process)
CartesiaX-API-KeyandCartesia-Version: 2026-08-14NoteKeep the key on your server, inCARTESIA_API_KEY. - Coqui TTS
Model name
xtts_v2Cartesiamodel_id:sonic-3.6 - Coqui TTS
textCartesiatranscript - Coqui TTS
speaker_wav: a reference clip sent with every callCartesiavoice:{"id": "<voice id>"}NoteClone the same clip once withclient.voices.clone(clip=..., language=..., name=...)and store the ID it returns. - Coqui TTS
speaker: a built-in XTTS speaker nameCartesiavoice:{"id": "<voice id>"}from the voice libraryNoteBuilt-in XTTS speakers do not exist on Cartesia. Pick a library voice by role. - Coqui TTS
language, one of 17 codes such asenorzh-cnCartesialanguage, such asenoren-GBNoteCheck each code you send against Cartesia's language list. - Coqui TTS
file_path="out.wav"Cartesiaoutput_formatwithcontainer: wavNoteThe API returns audio bytes. Your code writes the file. - Coqui TTS
speed(XTTS inference, default 1.0)Cartesiageneration_config.speed(0.6 to 1.5) - Coqui TTS
model.inference_stream(...)for chunked audioCartesiaTTS WebSocketNote/tts/bytesalso streams its response body as audio is generated. - Coqui TTS
A fine-tuned XTTS checkpoint
CartesiaProfessional voice cloneNoteCheckpoints do not transfer. A professional clone trains on 30 minutes of audio and needs a Startup plan or higher.
Coqui TTS 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.
- Coqui TTS
None; the library runs inside your own process
CartesiaX-API-KeyplusCartesia-Version: 2026-08-14NoteMoving to an API adds a secret to manage. Keep it server-side.
Coqui TTS 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
XTTS-v2 with the TTS library
Coqui TTSNo license feeNoteFree to download. Your cost is the GPUs and servers that run it, and the XTTS-v2 weights allow only non-commercial use.
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.
Coqui TTS 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)Coqui TTSFree to download; the model license permits non-commercial use only - Limit
Voices
Cartesia1,022 voices in the library, plus instant clonesCoqui TTSZero-shot cloning from a reference clip; the model card cites a 6-second sample - Limit
Languages
Cartesia44 languages for text to speechCoqui TTS17 languages on XTTS-v2
Cartesia's figures come from its pricing page and voice library.
Cartesia pricing and plan limitsSources
Limits read from each company's documentation in November 2026.
Coqui TTS voices and where to start on Cartesia
Any speaker_wav clip you pass, or a built-in XTTS speaker name
Each card is a starting point for a common Coqui TTS pick, matched by language and use. Listen before you choose.
What you get on Cartesia
What changes once the Coqui TTS call is gone.
No GPU or model weights to run
Cartesia hosts the model. You stop provisioning CUDA machines, downloading the XTTS-v2 checkpoint and warming it up after every deploy.
Clone once, reuse the ID
XTTS reads speaker_wav on every call. On Cartesia you clone a voice once from 10 seconds of audio, on a Pro plan or higher, and send its ID with each request.
Volume and emotion per request
generation_config sets speed from 0.6 to 1.5, volume from 0.5 to 2.0 and an emotion on each call. XTTS exposes speed alongside sampling knobs such as temperature and top_k.
How to migrate from Coqui TTS to Cartesia
The same changes the prompt makes, if you'd rather make them yourself.
Create a Cartesia API key and store it where your XTTS server reads its config today.
Clone each
speaker_wavyou use: upload the same file through the cloning guide. Ten seconds is the minimum, and Sonic 3.6 learns from up to 60.Replace the model load and
tts_to_filewith the request above. XTTS-v2 outputs 24 kHz, so asking for 24000 keeps downstream audio code unchanged.Move
speedintogeneration_configand delete the sampling parameters.Route traffic to Cartesia behind a flag. Once the XTTS path has carried no traffic for a release, shut down its GPU instances and delete the cached weights.
Coqui TTSSources
Request shapes checked against vendor documentation in November 2026.
Compare and read next
Frequently asked questions
Is Coqui TTS still maintained?
Not by Coqui. The company shut down in January 2024, and coqui-ai/TTS has had no release since v0.22.0 in December 2023. Idiap's fork keeps the library alive as coqui-tts on PyPI; version 0.28.0 shipped on October 19, 2026. Either way, you still run the model yourself, which is the part a hosted Coqui TTS alternative removes.
Can I use XTTS-v2 commercially?
The XTTS-v2 weights ship under the Coqui Public Model License 1.0.0, which says it "allows only non-commercial use" of the model and its outputs (license text). The library code is a separate license. Read both with your counsel before you ship audio from XTTS-v2 in a paid product.
How much audio does a voice clone need on each?
Coqui's model card says XTTS-v2 clones from a 6-second clip, and the Idiap docs say 3 seconds. Cartesia's instant clone needs 10 seconds, takes up to 60 on Sonic 3.6 to keep more of the accent, and requires a Pro plan or higher. A professional clone, the closest thing to fine-tuning XTTS, takes 30 minutes of audio on a Startup plan or higher.
What doesn't carry over from XTTS-v2?
Sampling controls (temperature, top_k, top_p, repetition_penalty, length_penalty) have no Cartesia fields. Fine-tuned checkpoints don't transfer, and per-call zero-shot cloning becomes a stored voice ID. Cartesia also runs only as a network API, so an offline or on-device XTTS deployment has no direct replacement.
How do I roll back if a voice sounds wrong?
Keep one XTTS instance running and pick the backend per request from a flag. If a cloned voice misses, send that voice's traffic back to XTTS while you re-clone from a longer or cleaner clip. Turn the GPU off only after the flag has sat at 100% Cartesia for a full release.
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.
