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

# Managing Artifacts

> Add voices and pronunciation dictionaries from the Cartesia cloud to your self-hosted deployment

<Note>
  Hot reload and the on-prem migration APIs (`add-voices`, `add-pdict`) require release tag `sonic-20260310` or later.
</Note>

## 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](/self-hosted/managed-kubernetes) for full configuration.

```hcl theme={null}
enable_hot_reload = false
```

<Warning>
  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.
</Warning>

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

```bash theme={null}
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",
    "include_loras": true
  }'
```

<Note>
  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.
</Note>

### 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"`).  |
| `include_loras` | `boolean`  | No       | Set to `true` to include LoRA checkpoints for cloned voices. 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>`.

```bash theme={null}
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.

```bash theme={null}
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"]
  }'
```

<Note>
  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.
</Note>

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

### 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>`.

```bash theme={null}
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 '.'
```