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

# アーティファクトの管理

> Cartesia クラウドのボイスと発音辞書をセルフホストデプロイメントに追加します

<Note>
  ホットリロードおよびオンプレミス移行 API（`add-voices`、`add-pdict`）は、リリースタグ `sonic-20260310` 以降が必要です。
</Note>

## ホットリロード

新しいボイスアーティファクトは、API サーバーの再起動なしにセルフホストデプロイメントに自動的に取り込まれます。ホットリロードはデフォルトで有効です。

マイグレーションファイルが GCS バケットに配置されると、API サーバーがそれを検出して自動的に適用します。API サーバーの再起動や Helm のアップグレードは不要です。

ホットリロードを無効化するには、tfvars で `enable_hot_reload` を `false` に設定します。完全な設定は [マネージド Kubernetes](/self-hosted/managed-kubernetes) を参照してください。

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

<Warning>
  ホットリロードは PVC ボイスをサポートしていません。`include_loras: true` でボイスを移行する場合、LoRA チェックポイントを有効にするためにワーカー Pod を再起動する必要があります。
</Warning>

## ボイスの追加

`POST /onprem/add-voices` エンドポイントを使って、Cartesia ボイスライブラリからセルフホストデプロイメントにボイスを追加できます。1 リクエストにつき最大 50 個のボイスを移行できます。移行は非同期で実行され、ボイスは通常 4〜5 分以内にセルフホストデプロイメント上で利用可能になります。

```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>
  このエンドポイントは、セルフホストデプロイメントではなく、**Cartesia クラウド API**（`api.cartesia.ai`）に対して呼び出します。API キーは、アクティブなオンプレミス契約を持つ組織に属している必要があります。
</Note>

### リクエストボディ

| パラメータ           | 型          | 必須  | 説明                                                   |
| --------------- | ---------- | --- | ---------------------------------------------------- |
| `voice_ids`     | `string[]` | はい  | 追加するボイス ID またはエイリアス。1 リクエストにつき最大 50 個。               |
| `model_id`      | `string`   | はい  | ボイスを使用するモデル（例: `"sonic-3.5"`、`"sonic-english"`）。     |
| `include_loras` | `boolean`  | いいえ | クローンボイスの LoRA チェックポイントを含める場合は `true`。デフォルトは `false`。 |

### ヘッダー

| ヘッダー               | 必須  | 説明                                 |
| ------------------ | --- | ---------------------------------- |
| `X-API-Key`        | はい  | Cartesia API キー。                   |
| `Cartesia-Version` | いいえ | API バージョンヘッダー。デフォルトは `2025-04-16`。 |

### エラーレスポンス

| ステータス | 条件                                                  |
| ----- | --------------------------------------------------- |
| `400` | `voice_ids` が欠落・空、`model_id` が欠落、または 51 個以上のボイス ID。 |
| `403` | オンプレミスアクセスがない、または要求されたボイスにアクセスできない。                 |
| `422` | リクエストボディの形式が不正。                                     |
| `500` | 内部サーバーエラー。                                          |

## ボイスの確認

移行完了後、`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 '.'
```

## 発音辞書の追加

`POST /onprem/add-pdict` エンドポイントを使って、Cartesia クラウドからセルフホストデプロイメントに発音辞書を追加できます。1 リクエストにつき最大 50 個の辞書を移行できます。移行は非同期で実行され、辞書は通常 4〜5 分以内にセルフホストデプロイメント上で利用可能になります。

```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>
  このエンドポイントは、セルフホストデプロイメントではなく、**Cartesia クラウド API**（`api.cartesia.ai`）に対して呼び出します。API キーは、アクティブなオンプレミス契約を持つ組織に属しており、かつ移行対象の各辞書を所有している必要があります。
</Note>

### リクエストボディ

| パラメータ                    | 型          | 必須 | 説明                                             |
| ------------------------ | ---------- | -- | ---------------------------------------------- |
| `pronunciation_dict_ids` | `string[]` | はい | 追加する発音辞書 ID。1 リクエストにつき最大 50 個。重複はサーバー側で除去されます。 |

### ヘッダー

| ヘッダー               | 必須  | 説明                                 |
| ------------------ | --- | ---------------------------------- |
| `X-API-Key`        | はい  | Cartesia API キー。                   |
| `Cartesia-Version` | いいえ | API バージョンヘッダー。デフォルトは `2025-04-16`。 |

### エラーレスポンス

| ステータス | 条件                                              |
| ----- | ----------------------------------------------- |
| `400` | `pronunciation_dict_ids` が欠落・空、または 51 個以上のエントリ。 |
| `403` | オンプレミスアクセスがない、または要求された辞書を呼び出し元が所有していない。         |
| `404` | 要求された辞書 ID が存在しない。                              |
| `422` | リクエストボディの形式が不正。                                 |
| `500` | 内部サーバーエラー。                                      |

## 発音辞書の確認

移行完了後、`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 '.'
```