ボイスクローン

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

Agent の主経路

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

1. ユーザーがその声の権利を持っていることを確認します。明示的な確認の後で のみ consent_attested: true を設定します。
2. ローカルサンプルを beatra.assets.upload でアップロードし、その artifact ID を使います。サンプルの制限は各モデルのモデルカード（sample_* フィールド）に載っています。クリーンな単一話者の録音が最適です。ElevenLabs ではサンプルは 10 秒〜5 分、20 MiB 以下の WAV・MP3・M4A・AAC・OGG が必要で、この制限を超えると課金前に拒否されます。
3. 不透明な client_request_id を 1 つ作り、最終的な引数を一度だけ送信します。
4. beatra.tasks.get でポーリングします。終端状態の応答が新しい voice_id を返します。

AI ガイド

ツール引数

{
  "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 秒未満）とその書き起こしです。エンジンは抜粋を文字単位で整合させ、 クローンの音色をシャープにします。メインサンプルが長い場合ややノイズを 含む場合に特に有効です。

{
  "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 がクローンをアクティブ化する短い 正式合成をすでに完了したことを意味します——このアクティブ化は料金に含まれ、 以後の音声合成は別課金です。クローンまたはアクティブ化に失敗した場合、 課金は保持されません。

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

一部のモデルは明示指定専用です。既定の一覧には含まれず、auto も選びません。beatra.models.list は include_activation_required: true（REST は GET /v1/catalog/capabilities/voice_clone?include_activation_required=true）を渡したときだけ一覧に含めます。これらのカードは constraints.automatic_formal_activation: false です。この一覧の条件だけでは、アクティブ化が必要かどうかはわかりません。下の doubao-voice-clone-2.0 は 2 段階で、クローンでは無料の試聴が作られ、別途有料でアクティブ化すると音声合成に使えるようになります。ElevenLabs のクローンも同じ条件で一覧に載りますが、1 段階で、成功した時点で使えます（ElevenLabs の節を参照）。明示指定専用のモデルは、ユーザーが名指しで求めた場合にのみ使ってください。

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": { "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 時間を過ぎた 場合）、新しい見積もりが返り、課金はされません。

{
  "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 モデルによります。

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

elevenlabs-voice-clone はすべてのアカウントで利用できますが、明示指定専用です。model: "elevenlabs-voice-clone" を渡してください。既定のクローン一覧には含まれず、auto も選びません。探し方は、beatra.models.list に include_activation_required: true（REST は GET /v1/catalog/capabilities/voice_clone?include_activation_required=true）を渡す、GET /v1/catalog/models/elevenlabs-voice-clone を使う、または完全な /v1/models 一覧を見る、のいずれかです。上の 2 段階モデルと同じ一覧条件に当てはまりますが、こちらは 1 段階で、タスクが成功した時点ですぐに使えます。

成功したクローンは1 回 7,270 クレジットで、すぐに ready となり、elevenlabs-v4-turbo と elevenlabs-v4 に使えます。クローンしたボイスはこの 2 つのモデルでのみ使え、両モデルが対応する 10 言語（en、zh、ja、ko、es、pt、ar、hi、fr、it）を話します。クローンタスクはボイスの作成だけを行い、音声合成・プレビュー生成・追加のアクティブ化は行いません。後の音声合成は個別に見積もり・課金します。すでに ready のボイスへの activate は無料で、変更しません。prompt と model_options は警告付きで無視されます。

サンプルの制限。 これらは推奨ではなく制限です。範囲外のサンプルは課金前に拒否されます。

• 形式：WAV、MP3、M4A、AAC、OGG。ほかの形式は 422 unsupported_option を返します。
• 長さ：10 秒以上 5 分以下。サイズ：20 MiB 以下。長さまたはサイズが範囲外だと 422 invalid_request を返します。
• 権利を確認した 1 人の録音を使ってください。推奨は 1–2 分で、3 分を超えてもクローンは良くなりません。

タスクの受付後に上流がサンプルを拒否した場合、タスクは voice_sample_rejected で失敗し、全額返金されます。メッセージには、サンプルが短すぎる、長すぎる、読み取れない、大きすぎる、またはこのボイスに追加の確認が必要、のいずれかが示されます（後者も voice_sample_rejected で失敗し、返金されます）。

1 日の上限。 ElevenLabs のクローンは 1 アカウントあたり UTC 日ごとに最大 3 件で、北京時間 08:00（UTC 0:00）にリセットされます。進行中、成功、上流に届いた後に失敗したクローンは数に含まれます。上のローカルチェックで拒否されたサンプルや、アップロード前に取り消したクローンは含まれません。4 件目は 429 rate_limited（details.reason: voice_creation_daily_limit）を返し、retry_after_seconds と、REST では同じ秒数の Retry-After レスポンスヘッダー（MCP にヘッダーはありません）が付きます。課金はされません。model を省略すると同料金の既定クローンを使えます。同じリクエストの再送で別のクローンが作られることはありません。

一時的なエラー。 どちらも課金されません。

• 503 model_unavailable、details.reason: creation_temporarily_unavailable：このモデルでの新規クローンは一時停止中です。model を省略すると同料金の既定クローンを使えます。available_at が示されている場合は、その後に再試行してください。
• 503 model_unavailable、details.reason: voice_temporarily_busy：クローン処理が混み合っています。retry_after_seconds（約 1 分）後に再試行してください。

無料プレビュー。 アカウントまたはデスクトップ画面で無料プレビューを選ぶと、Beatra がクローンした声で固定の短文を合成し、以後の再生用に保存します。文はクローンの language で決まります（10 言語のいずれか、それ以外は英語）。最初のプレビューは無料で、キャッシュして再利用され、ElevenLabs の音声合成の 2 件同時実行の上限に含まれます（音声合成を参照）。ボイスを先に復元する必要がある場合、プレビューは 503 model_unavailable（details.reason と retry_after_seconds を参照。復元中は voice_temporarily_busy で 30 秒）を返すことがあります。復元はバックグラウンドで続き、次の試行で成功します。ElevenLabs の音声合成タスクがすでに 2 件実行中の間はプレビューは生成されず、プレビューなしで返ります。プレビューの失敗はクローンの結果や料金を変えません。自分の文章や異なる設定での合成は、別途見積もりの確認が必要です。

サンプルとボイス。 クローンは同じ voice_id のままアカウントが所有します。アップロードしたサンプルは、必要なときに内部でボイスを復元できるよう非公開のコピーとして保存されます。復元には時間がかかる場合があり、モデル変更後の同一波形は保証しません。ボイスを削除するかアカウントを閉鎖すると、サンプルは上流のボイスとキャッシュ済みのプレビューとともに削除されます。削除は元に戻せず、クローン料金は返金されません。受付済みの音声合成は完了します。

クローンボイスでの音声合成は、次のように失敗することがあります。一時的にビジー（503 voice_temporarily_busy）または現在復元できない（503 voice_temporarily_unavailable、わかる場合は available_at）場合は課金されず、ほかのボイスにも影響しません。保存されたサンプルから復元できなくなったボイスは 422 voice_unavailable を返します。これは恒久的な状態なので再試行せず、サポートにお問い合わせください。その合成は課金されず、元のクローン料金は返金されません。受付後に失敗した音声合成は、その合成分だけ返金されます。

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

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

REST で呼び出す

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