ボイスクローン

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

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 ガイド

ツール引数

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

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

明示的に指定する一部のモデルは 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": { "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 モデルによります。

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

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 ではないカスタム アプリケーション向けです。