Documentation Index
Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
Use this file to discover all available pages before exploring further.
Hot reload and the on-prem migration APIs (add-voices, add-pdict) require release tag sonic-20260310 or later.
Hot reload
New voice artifacts are picked up automatically by your self-hosted deployment without requiring an API server restart. Hot reload is enabled by default.
When a migration file lands in your GCS bucket, the API server detects and applies it automatically. No API server restarts or Helm upgrades are needed.
To disable hot reload, set enable_hot_reload to false in your tfvars — see Managed Kubernetes for full configuration.
enable_hot_reload = false
Hot reload does not support PVC voices. If you migrate voices with include_loras: true, you must restart the worker pods for the LoRA checkpoints to take effect.
Adding voices
Add voices from the Cartesia voice library to your self-hosted deployment using the POST /onprem/add-voices endpoint. You can migrate up to 50 voices per request. The migration runs asynchronously — voices typically become available on your self-hosted deployment within 4–5 minutes.
curl -X POST "https://api.cartesia.ai/onprem/add-voices" \
-H "Cartesia-Version: 2025-04-16" \
-H "X-API-Key: $CARTESIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"voice_ids": ["a0e99841-438c-4a64-b679-ae501e7d6091"],
"model_id": "sonic-3",
"include_loras": true
}'
This endpoint is called against the Cartesia cloud API (api.cartesia.ai), not your self-hosted deployment. Your API key must belong to an organization with an active on-prem contract.
Request body
| Parameter | Type | Required | Description |
|---|
voice_ids | string[] | Yes | Voice IDs or aliases to add. Maximum 50 per request. |
model_id | string | Yes | The model the voices will be used with (e.g., "sonic-3", "sonic-english"). |
include_loras | boolean | No | Set to true to include LoRA checkpoints for cloned voices. Defaults to false. |
| Header | Required | Description |
|---|
X-API-Key | Yes | Your Cartesia API key. |
Cartesia-Version | No | API version header. Defaults to 2025-04-16. |
Error responses
| Status | Condition |
|---|
400 | Missing or empty voice_ids, missing model_id, or more than 50 voice IDs. |
403 | No on-prem access, or a requested voice is not accessible. |
422 | Malformed request body. |
500 | Internal server error. |
Verifying a voice
After migration completes, verify a voice is available on your self-hosted deployment with GET /voices/<id>.
curl -X GET "http://<your-host>:<port>/voices/<voice-id>" \
-H "Cartesia-Version: 2025-04-16" \
-H "X-API-Key: $CARTESIA_API_KEY" | jq '.'
Adding pronunciation dictionaries
Add pronunciation dictionaries from the Cartesia cloud to your self-hosted deployment using the POST /onprem/add-pdict endpoint. You can migrate up to 50 dictionaries per request. The migration runs asynchronously — dictionaries typically become available on your self-hosted deployment within 4–5 minutes.
curl -X POST "https://api.cartesia.ai/onprem/add-pdict" \
-H "Cartesia-Version: 2025-04-16" \
-H "X-API-Key: $CARTESIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"pronunciation_dict_ids": ["a0e99841-438c-4a64-b679-ae501e7d6091"]
}'
This endpoint is called against the Cartesia cloud API (api.cartesia.ai), not your self-hosted deployment. Your API key must belong to an organization with an active on-prem contract, and must own each dictionary being migrated.
Request body
| Parameter | Type | Required | Description |
|---|
pronunciation_dict_ids | string[] | Yes | Pronunciation dictionary IDs to add. Maximum 50 per request. Duplicates are removed server-side. |
| Header | Required | Description |
|---|
X-API-Key | Yes | Your Cartesia API key. |
Cartesia-Version | No | API version header. Defaults to 2025-04-16. |
Error responses
| Status | Condition |
|---|
400 | Missing or empty pronunciation_dict_ids, or more than 50 entries. |
403 | No on-prem access, or a requested dictionary is not owned by the caller. |
404 | A requested dictionary ID does not exist. |
422 | Malformed request body. |
500 | Internal server error. |
Verifying a pronunciation dictionary
After migration completes, verify a dictionary is available on your self-hosted deployment with GET /pronunciation-dicts/<id>.
curl -X GET "http://<your-host>:<port>/pronunciation-dicts/<dict-id>" \
-H "Cartesia-Version: 2025-04-16" \
-H "X-API-Key: $CARTESIA_API_KEY" | jq '.'
