# ボイス管理
> 音声合成に使えるボイスの照会、絞り込み、削除。

音声合成に使えるボイスの照会、絞り込み、削除。

## Agent の主経路

Universal Skill から MCP ツール `beatra.voices.list` を使います。課金されない
読み取り専用の呼び出しで、プリセットボイスとあなたのアカウントにあるクローンボイスを
返します。

1. `category`（`preset` / `cloned`）、`language`（BCP-47）、`gender`
   （`male` / `female` / `neutral`）、`age_group`（`child` / `youth` / `adult` /
   `senior`）、`use_case`（`audiobook`、`narration`、`news`、`ads`、
   `conversational`、`business`、`character`、`ivr`、`course`、`podcast`、
   `gaming`、`shorts`、`education`、`support`、`social` のいずれか）、`model`
   （対応モデル ID）、`query`（表示名に含まれる文字）、`search`（表示名または
   ペルソナに含まれる文字）、`voice_id`（1 つのボイスに完全一致）で絞り込みます。
   `status` で一覧に含めるボイスを選びます：`ready`（既定。音声合成に使える
   ボイス）、`pending_activation`（有料アクティブ化を待つクローンの試聴）、
   `expired`、`any`。
2. 一覧はページ分割されます。`limit`（1–500、既定 50）と `cursor`（前ページの
   `next_cursor`）を使います。`total_count` は条件に合うボイスの総数で、最後の
   ページでは `next_cursor` が `null` です。
3. 返された `voice_id` は[音声合成](https://docs.beatra.ai/ja/docs/capabilities/speech/text-to-speech)
   の `voice` フィールドにそのまま使えます。`persona` はボイスを 1 文で説明し、
   `preview_url`（汎用サンプル）と `preview_url_scene`（主な用途のサンプル）で
   選ぶ前に無料で試聴できます。

## AI ガイド

AI integration guide: https://docs.beatra.ai/llms/voices-management.md

## ツール引数

```json
{
  "category": "preset",
  "language": "zh-CN",
  "use_case": "audiobook",
  "age_group": "adult",
  "limit": 50
}
```

ボイスのエントリは次の形です：

```json
{
  "voice_id": "voice_preset_niannian",
  "display_name": "念念",
  "category": "preset",
  "language": "zh",
  "gender": "female",
  "age_group": "adult",
  "use_case": ["audiobook", "narration"],
  "persona": "温柔细腻的女声，适合有声书与旁白。",
  "preview_url": "https://cdn.beatra.ai/voices/previews/voice_preset_niannian.mp3",
  "preview_url_scene": "https://cdn.beatra.ai/voices/previews/voice_preset_niannian_scene.mp3",
  "compatible_models": ["minimax-speech-2.8-hd", "minimax-speech-2.8-turbo"],
  "status": "ready"
}
```

別途アクティブ化が必要なモデルでクローンしたボイス（[ボイスクローン](https://docs.beatra.ai/ja/docs/capabilities/speech/voice-clone)
を参照）は `clone_model` も持ち、アクティブ化待ちの間は `preview`（`url`、
`text`、`language`、`version`）と `expires_at` も含みます。その他のボイスの
項目は変わりません。既定（`ready`）の一覧にアクティブ化待ちのボイスが含まれない
場合、テキストの要約にその件数が示されます。

`compatible_models` には、そのボイスを読み上げられる音声モデルが並びます。ボイスはそれぞれ 1 つのエンジンに属するため、`model` は `auto`（この一覧から選びます）にするか、この中のモデルを指定してください。ほかのモデルは課金前に `voice_model_incompatible` で拒否されます。

レスポンスには `next_cursor` と `total_count` も含まれます。REST の
`GET /v1/voices` は同じ絞り込み条件をクエリパラメーターで受け付けます（名前検索は
`query` ではなく `q`）。

## デフォルトボイスと名前の変更

`beatra.voices.list` は `voices` と並べて `default_voice_id` を返します。アカウントにデフォルトボイスがあればその `voice_id`、なければ `null` です。各ボイスの項目は変わりません。

ユーザーが求めたときだけ、`beatra.voices.update` で自分のクローンボイスの名前を変えるか、任意のボイス（クローンまたはプリセット）をデフォルトにします。課金はなく、ボイスを削除することはできません。アクティブ化待ちのボイスは名前を変更できますが、デフォルトにできるのは `ready` のボイスだけです。

```json
{
  "voice_id": "voice_01JX...",
  "display_name": "鵬博士",
  "make_default": true
}
```

## クローンボイスの削除

削除は REST のみです：

```bash curl
curl -X DELETE "$BEATRA_BASE_URL/voices/voice_01JX..." \
  -H "Authorization: Bearer $BEATRA_API_KEY"
```

`204` を返します。削除できるのは自分でクローンしたボイスだけで、プリセット
ボイスは削除できません。

アクティブ化が必要なモデルでクローンしたボイスの削除は取り消せません。
アクティブ化待ち（または期限切れ）のボイスは試聴とともに削除されます。
アクティブ化したボイスでは、アクティブ化の料金は返金されず、すでに送信済みの
音声合成タスクはそのまま完了します。アクティブ化の実行中に削除すると 409
`conflict`（`details.reason: voice_operation_in_progress`）になります。その
タスクが終わってから削除してください。

## REST で呼び出す

プロトコル直結の統合はボイスエンドポイントを直接使えます：
[一覧](https://docs.beatra.ai/ja/docs/api-reference/operations/voices/list_voices_v1_voices_get) ·
[詳細](https://docs.beatra.ai/ja/docs/api-reference/operations/voices/get_voice_v1_voices__voice_id__get) ·
[削除](https://docs.beatra.ai/ja/docs/api-reference/operations/voices/delete_voice_v1_voices__voice_id__delete)。
推奨の統合方法は Skill + MCP です。REST は Agent ではないカスタム
アプリケーション向けです。