Managing Artifacts

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

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.5"
  }'

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.

Migrating to your dev bucket

Every on-prem organization has two artifact buckets: a production bucket (gs://cartesia-{name}) and a dev bucket (gs://dev-cartesia-{name}). Migrations target the production bucket by default. Set dev_bucket to true to migrate voices to the dev bucket instead, so you can test voices on a dev deployment before adding them to production.

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.5"`, `"sonic-english"`).
`dev_bucket`	`boolean`	No	Migrate voices to your dev bucket (`gs://dev-cartesia-{name}`) instead of your production bucket. Defaults to `false`.

Headers

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": ["pdict_ZqKFD5kZqU9goABbzBYZfe"]
  }'

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.

Like add-voices, this endpoint supports migrating to your dev bucket: set dev_bucket to true to target gs://dev-cartesia-{name} instead of your production bucket.

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.
`dev_bucket`	`boolean`	No	Migrate dictionaries to your dev bucket (`gs://dev-cartesia-{name}`) instead of your production bucket. Defaults to `false`.

Headers

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

Overview

Deployments

Guides

Performance

Hot reload

Adding voices

Migrating to your dev bucket

Request body

Headers

Error responses

Verifying a voice

Adding pronunciation dictionaries

Request body

Headers

Error responses

Verifying a pronunciation dictionary

​Hot reload

​Adding voices

​Migrating to your dev bucket

​Request body

​Headers

​Error responses

​Verifying a voice

​Adding pronunciation dictionaries

​Request body

​Headers

​Error responses

​Verifying a pronunciation dictionary

Hot reload

Adding voices

Migrating to your dev bucket

Request body

Headers

Error responses

Verifying a voice

Adding pronunciation dictionaries

Request body

Headers

Error responses

Verifying a pronunciation dictionary