# ボイスクローン
> 承認済みのサンプル音声から再利用可能なボイスをクローンします。

承認済みのサンプル音声から再利用可能なボイスをクローンします。

## Agent の主経路

Universal Skill から MCP ツール `beatra.voices.clone` を使います。この
ツールは課金対象で、同意確認が必須で、非同期タスクを返します。

1. ユーザーがその声の権利を持っていることを確認します。明示的な確認の後で
   のみ `consent_attested: true` を設定します。
2. ローカルサンプルを `beatra.assets.upload` でアップロードし、その
   artifact ID を使います。10 秒〜5 分の、クリーンな単一話者の音声が最適です。
3. 不透明な `client_request_id` を 1 つ作り、最終的な引数を一度だけ送信します。
4. `beatra.tasks.get` でポーリングします。終端状態の応答が新しい `voice_id`
   を返します。

## AI ガイド

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

## ツール引数

```json
{
  "sample": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "display_name": "Brand narration - female",
  "consent_attested": true,
  "client_request_id": "voice-clone-opaque-1"
}
```

`sample` は artifact、HTTPS URL、data URI を受け付けます。`display_name` は
必須（≤255 文字）。`consent_attested: true` がないリクエストは拒否されます。

## オプションの品質プロンプト（prompt）

より高い類似度が必要な場合は `prompt` を追加します：同じ声の短い抜粋
（8 秒未満）とその書き起こしです。エンジンは抜粋を文字単位で整合させ、
クローンの音色をシャープにします。メインサンプルが長い場合ややノイズを
含む場合に特に有効です。

```json
{
  "sample": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "prompt": {
    "sample": { "type": "artifact", "artifact_id": "artifact_prompt..." },
    "text": "抜粋の書き起こし（文字単位で正確に）。"
  },
  "display_name": "Brand narration - female",
  "consent_attested": true,
  "client_request_id": "voice-clone-opaque-1"
}
```

`prompt.sample` は `sample` と同じ参照形式を受け付けます。`prompt.text`
（≤2,000 文字）は抜粋と正確に一致させ、句読点で終えてください。長さが 8 秒以上と
測定された抜粋や、末尾に句読点のない書き起こしは課金前に拒否されます。`prompt` を省略すれば
メインサンプルのみからクローンします。プロンプトの追加で追加課金は
発生しません。

## モデル・コントロール・コスト

ユーザーがモデルを指名しない限り `model` は省略（または `auto`）します。
選択可能なモデル、受け付けるサンプル形式、固定価格は
`capability: "voice_clone"` の `beatra.models.list` で取得します。

`auto`（およびカードが `constraints.automatic_formal_activation: true` の
モデル）では、ボイスクローンは、アクティブ化されたボイスの作成に成功したときに
一度だけ固定料金が発生します。成功とは、Beatra がクローンをアクティブ化する短い
正式合成をすでに完了したことを意味します——このアクティブ化は料金に含まれ、
以後の音声合成は別課金です。クローンまたはアクティブ化に失敗した場合、
課金は保持されません。

## 別途アクティブ化が必要なモデル

明示的に指定する一部のモデルは 2 段階で完了します。クローンでは無料の試聴が
作られ、別途有料でアクティブ化すると音声合成に使えるようになります。これらは
`auto` の対象にならず、`beatra.models.list` は
`include_activation_required: true` を渡したときだけ一覧に含めます（カードは
`constraints.automatic_formal_activation: false`）。ユーザーが名指しで求めた
場合にのみ使ってください。

`doubao-voice-clone-2.0`:

- `language` は必須で、サンプル内で話されている言語を指定します：`zh`、`en`、
  `ja`、`ko`、`es`、`es-MX`、`pt`、`pt-BR`、`id`、`ms`、`th`、`vi`、`fil`、
  `de`、`fr`、`ru`、`ar`。未指定や一覧にない値は 422 `unsupported_option` に
  なります。
- サンプルは WAV、MP3、OGG、M4A、AAC のいずれかで 10 MiB 以下である必要が
  あり、満たさない場合は課金前に 422 `voice_sample_rejected` になります。1 人が
  話す 14〜30 秒が最適で、既定では先頭 25 秒だけを使います。`prompt` は無視され、
  `option_ignored` 警告が返ります。
- クローンと試聴は無料です。タスクは `output.status: "pending_activation"` で
  成功し、`preview`（選んだ言語の固定文をクローンしたボイスで読み上げたもの）、
  `activation.price_credits`、`activation.quote`（アクティブ化の見積もり、後述）、
  `expires_at` を返します。試聴をユーザーに再生してください。
- アクティブ化待ちのボイスは音声合成に使えません（合成は 422
  `voice_activation_required`）。名前の変更はできますが、デフォルトには設定でき
  ません。`expires_at`（通常はクローンから 7 日後）までにアクティブ化しないと
  `expired`（422 `voice_preview_expired`）になり、クローンし直す必要があります。
- アカウントごとの上限：アクティブ化待ちのボイスは 10 件まで（409
  `voice_limit_reached`。1 件をアクティブ化または削除してください）、クローンは
  UTC の 1 日あたり 20 回まで（429 `rate_limited`、
  `details.reason: voice_training_daily_limit`）、同時に進行できるクローンは
  1 件まで（429 `rate_limited`、`details.reason: voice_training_in_progress`。
  終わってから再試行してください）。全体が混雑しているときは
  `voice_training_busy` になります。約 30 秒後に再試行してください。

任意の `model_options.doubao` で学習を調整できます。値は課金前に検証され、未知の
キーや範囲外の値は 422 `unsupported_option` になります。

| キー | 型と範囲 | 効果 |
| --- | --- | --- |
| `sample_text` | 文字列、1,000 文字以内 | サンプルで話している内容。音声との差が大きいサンプルは拒否されます（`voice_sample_rejected`、`details.reason: sample_text_mismatch`）。`zh`、`en`、`ja`、`ko`、`es`、`es-MX`、`pt`、`pt-BR`、`id`、`fr`、`ru` のみ検証し、その他の言語では無視して `option_ignored` 警告を返します。 |
| `enable_audio_denoise` | 真偽値（既定 `false`） | 学習前に背景ノイズを除去します。 |
| `enable_audio_denoise_with_snr` | 真偽値 | サンプルの SN 比が `denoise_max_snr_thresh` より低いときだけノイズを除去します。 |
| `denoise_max_snr_thresh` | 整数、1〜99（既定 50） | これより低い SN 比のときにノイズを除去します。 |
| `reject_min_snr_thresh` | 数値、0 より大きく 100 未満（既定 5） | SN 比がこれより低いサンプルを拒否します。 |
| `voice_clone_denoise_model_id` | `SpeechInpaintingV2`（既定）または `VocalDiffusionV2VocalDiffusionV2_44k` | ノイズ除去のモデル。 |
| `voice_clone_enable_mss` | 真偽値 | 学習前に声と背景音楽を分離します。 |
| `enable_crop_by_asr` | 真偽値 | 先頭 25 秒ではなく、音声認識で学習区間を選びます。 |
| `enable_check_prompt_text_quality` | 真偽値 | 学習前に `sample_text` の品質を確認します。 |
| `enable_check_audio_quality` | 真偽値 | 学習前にサンプルの音質を確認します。 |
| `disable_volume_normalization` | 真偽値 | 録音時の音量を保ちます。 |

```json
{
  "sample": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "display_name": "My voice",
  "model": "doubao-voice-clone-2.0",
  "language": "ja",
  "model_options": { "doubao": { "enable_audio_denoise": true } },
  "consent_attested": true,
  "client_request_id": "voice-clone-opaque-2"
}
```

## ボイスのアクティブ化

`beatra.voices.activate` はアクティブ化待ちのボイスを音声合成に使えるように
します。クローンの結果に見積もりが含まれているので、1 回の呼び出しでアクティブ化
できます。

1. クローン結果の `activation.quote` には `price_credits`、`balance_credits`、
   `sufficient_balance`、`preview`、`zh`・`en`・`ja` の `terms`、
   `terms_version`、`confirmation_token`、`token_expires_at`（24 時間）が含まれ
   ます。
2. ユーザーに価格と条件を伝え、明示的な同意を得てください。自動でアクティブ化
   してはいけません。
3. `voice_id`、`confirmation_token`、`confirm_credits`（見積もりの
   `price_credits`）を付けて 1 回呼び出します。価格が一度だけ差し引かれ、非同期
   タスクが返ります。`beatra.tasks.get` でポーリングしてください。成功すると
   ボイスは `ready` になり、出力にはボイスと、作成できた場合は最終試聴が含まれ
   ます。

`confirmation_token` なしで呼び出すと（トークンを失った、または 24 時間を過ぎた
場合）、新しい見積もりが返り、課金はされません。

```json
{
  "voice_id": "voice_01JX...",
  "confirmation_token": "<activation.quote の値>",
  "confirm_credits": 100000,
  "client_request_id": "voice-activate-opaque-1"
}
```

- トークンの期限切れ、価格の変更、または見積もりと異なる `confirm_credits` は
  422 `price_confirmation_required` になり、`details.quote` に新しい見積もりが
  入ります。課金はされません。新しい見積もりを伝えて、改めて同意を得てください。
- アクティブ化に失敗した場合は自動で返金され、成功後は返金されません。
  アクティブ化したボイスの録音は差し替えできません。声を変えるには新しいボイスを
  クローンし、それをアクティブ化します。
- アカウントごとの上限：同時に進行できるアクティブ化は 1 件まで（429
  `rate_limited`、`details.reason: voice_activation_in_progress`）、UTC の 1 日
  あたり 3 件まで。4 件目は 429 `voice_activation_daily_limit` になり、課金は
  されず、メッセージはサポートへの連絡を案内します。
- アクティブ化を実行できない場合は `internal_error` になり、課金はされません
  （または全額返金されます）。メッセージは `request_id` を添えてサポートに連絡
  するよう案内します。
- すでに `ready` のボイス（`auto` でクローンしたすべてのボイスとすべてのプリ
  セットボイスを含む）に対して呼び出しても、課金も変更もありません。
- アクティブ化の実行中はボイスを削除できません（409 `conflict`、
  `details.reason: voice_operation_in_progress`）。

価格はクローンカードの `pricing`（`billing_basis: successful_activated_voice`）
と各見積もりにあります。アクティブ化したボイスの削除は取り消せず、アクティブ化の
料金は返金されません。すでに送信済みの音声合成タスクはそのまま完了します。

アクティブ化した Doubao のクローンボイスは、長文を含めて `doubao-seed-tts-2.0`
で、学習した言語で合成します。読めない言語を `language` に指定すると（中国語の
クローンボイスでは中国語・英語・`auto` 以外）、このボイスをどの言語の録音から
クローンしたかを示す `option_ignored` の案内が返り、中国語のクローンボイスは長文
パスではそのリクエストを拒否します（3,000 文字以内に分けて送るか、その言語の録音
でクローンし直してください）。テキスト自体の言語は確認しません。字幕、ポーズ、
読み方のルールはその言語のプリセットボイスと同じです。`emotion`、`direction`、
`previous_text` は指示に従うボイスと同じようにモデルへ送られ、実際の効果は
Doubao モデルによります。

## タスクの状態とリカバリー

`queued` と `running` は失敗ではありません。同じ `task_id` をポーリングし
続け、実行中だからといって代替リクエストを送らないでください。作成応答を
失った場合は、同じ `client_request_id` で同一の引数を再送します。入力が
少しでも変わったら新しい ID を使います。ボイスが `ready` になれば（アクティブ化
が必要なボイスはアクティブ化の後）、返された `voice_id` は
[音声合成](https://docs.beatra.ai/ja/docs/capabilities/speech/text-to-speech)の `voice` フィールドに
そのまま使え、長期間有効で、[ボイス管理](https://docs.beatra.ai/ja/docs/capabilities/speech/voices)で
確認・削除できます。

## ElevenLabs：明示指定、成功時に利用可能

`model: "elevenlabs-voice-clone"` を明示してください。クローンの `auto` や既定の機能一覧では選ばれません。
利用可能なアカウントでは `GET /v1/catalog/models/elevenlabs-voice-clone` でカードを確認でき、
完全な `/v1/models` 一覧にも含まれます。内部検証中は一般アカウントには提供されません。

成功したクローンは**1 回 7,270 クレジット**で、すぐに `ready` となり、
`elevenlabs-v4-turbo` と `elevenlabs-v4` に使えます。クローンタスクはボイスの作成だけを行い、
音声合成・プレビュー生成・追加のアクティブ化は行いません。後の音声合成は個別に見積もり・課金します。
アカウントまたはデスクトップ画面で無料プレビューを選ぶと、クローンした声で固定の短文を合成し、以後の再生用に保存します。プレビューの失敗はクローンの結果や料金を変えず、元の録音を合成結果として再生することもありません。自分の文章や異なる設定での合成は、別途見積もりの確認が必要です。
すでに ready のボイスへの activate は無料で、変更しません。

- 権利を確認した 1 人の WAV・MP3・M4A・AAC・OGG 録音を使ってください。10 秒以上・20 MiB 以下で、
  推奨は 1–2 分です。3 分を超えても追加の効果は期待しません。`prompt` と専用クローンオプションは警告付きで無視します。
- UTC 日ごと（北京 08:00 リセット）に成功・進行中の新規クローンはアカウント合計 3 件までです。
  失敗は当日の枠を解放し、同じリクエストの再送は新しい枠を消費しません。
- 同じ `voice_id` の所有権は維持されます。削除まで元の録音を保持し、必要なら内部で無料再構築します。
  名前・互換モデルは変わりませんが、待ち時間が増える場合があり、モデル変更後の同一波形は保証しません。
- 一時的な作成・再構築の容量不足は新規リクエストを課金前に拒否します。受付後の音声合成の失敗はその合成分を返金します。
  保存サンプルが恒久的に拒否された場合は `voice_unavailable` となり、サポートへの連絡が必要です。過去の成功したクローン料金は返金しません。
- 削除時は受付済みの音声タスクが完了してから保存サンプルも削除します。元に戻すことはできず、クローン料金は返金しません。

## REST で呼び出す

プロトコル直結の統合は `POST /v1/voices`、`POST /v1/voices/{voice_id}/activate`
と共有タスクエンドポイントを使えます。生成された API 定義に従ってください：
[クローン](https://docs.beatra.ai/ja/docs/api-reference/operations/voices/clone_voice_v1_voices_post) ·
[アクティブ化](https://docs.beatra.ai/ja/docs/api-reference/operations/voices/activate_voice_v1_voices__voice_id__activate_post)。推奨の統合方法は Skill + MCP です。REST は Agent ではないカスタム
アプリケーション向けです。