voice-clone

使用する場面

• 録音から声をクローンし、後で使えるように保存したい場合
• 「用我自己的声音朗读」「克隆我的声音」「clone my voice」「custom voice」と言われた場合
• すでにクローンした音声を管理（一覧表示、名前の変更、削除）したい場合
• 音声の上限に達し、枠を空ける必要がある場合

使用しない場面

• 生成1回限りで、何も保存せずに参照音声を使ってクローンしたい場合 — 代わりに reference 音声で /listenhub-voice を使用します
• 既存の ListenHub 音声にテキストを読み上げさせたいだけの場合（/tts を使用します）
• ポッドキャスト、解説動画、音楽、AI 動画を作成したい場合（それぞれのスキルを使用します）

/listenhub-voice と /voice-clone の違い：/listenhub-voice は公開音声 URL からそのリクエスト限りの音声をクローンし、何も保存しません。/voice-clone は独自のスピーカー ID を持つ永続的なプライベートスピーカーを作成します。この音声は /tts、/podcast、および ListenHub のほかのあらゆる機能で使用できます。その代わり、確認手順、プランごとの利用枠、保存される音声枠が必要です。

目的

1〜6 個の参照音声ファイルを、再利用可能なプライベート音声にします。

1. 作成 — 参照音声をアップロードします。タスクによって一時的な音声がクローンされます。
2. ポーリング — クローンの完了を待ち、プレビューを聴きます。
3. 確認 — 音声に名前を付けて保存します。この時点で初めて、永続的なスピーカーになります。

費用が発生するのは確認時です。プランの期間ごとの利用枠内であれば無料で、それを超えると1回につき300クレジットかかります。また、ユーザーが明示的に料金の発生を許可した場合に限り、費用が請求されます。未確認のタスクは7日後に期限切れになります。

厳格な制約

• shared/cli-authentication.md に従って、必ず CLI 認証を確認してください
• CLI の実行、エラー、操作パターンについては shared/cli-patterns.md に従ってください
• 操作を始める前に、shared/config-pattern.md に従って必ず設定を読み込んでください
• ユーザーから明示的な許可を得ずに、音声を確定してはいけません — 確定すると300クレジットを消費する可能性があります。まずプレビューを表示し、その後で確認してください。
• この会話でユーザーがクレジットの使用に同意していない限り、--use-credits を渡してはいけません。これを指定しない場合、サーバーは料金の請求を拒否します。これが安全な既定の動作です。
• ユーザーが同意を得ていない音声をクローンしてはいけません。 録音がユーザー自身の声でない場合は、アップロードする前に話者の許可を得ているか尋ね、許可がない場合は中止してください。
• 話者 ID を捏造してはいけません。確定後に voice-clone speakers の出力から取得してください
• プロバイダー名、内部タスクの状態、DAO、MongoDB、認証情報の詳細を公開してはいけません

選択肢から選ぶ手順では、必ず AskUserQuestion ツールを使用してください。選択肢をプレーンテキストで表示してはいけません。一度に質問するのは1つだけにしてください。次に進む前にユーザーの回答を待ってください。利用枠を使い切るとクローンの確定にクレジットが必要になるため、ユーザーが音声を保存すると明示的に同意する前に `voice-clone confirm` を実行したり、`--auto-confirm` を渡したりしてはいけません。

前提条件

listenhub auth status --json

shared/cli-authentication.md に従って、インストールとログインを自動的に処理してください。音声のクローンには有料プランが必要です。無料アカウントでは、確定時にアップグレードを促すエラーが発生します。

ワークフロー

ステップ1 — 参照音声を集める

ユーザーが音声ファイルのパスを提示していない場合は、パスを尋ねてください。ローカルファイルを1〜6個受け付けます（.mp3、.wav、.m4a、.flac、.ogg、.aac）。通常は1ファイルを使用します。

事前に伝えておく制限：1ファイルあたり5MB以下、合計20MB以下です。背景音楽のない、クリアな音声を最もよくクローンできます。

ステップ2 — 同意を確認する

録音がユーザー自身の声でない場合は、話者の許可を得ているか尋ねてください。許可がない場合は中止してください。同意なく他人の声をクローンすることを回避する方法を探してはいけません。

ステップ3 — 言語を選ぶ

録音の言語を尋ねてください。選択肢は zh または en です。

Step 4 — 作成して完了を待つ

listenhub voice-clone create --file <path> --lang <zh|en> --json

複数のファイルを指定する場合は、--file を繰り返します。このコマンドはクローン作成が完了するまでポーリングし、一時的な音声のプレビューである demoAudioUrl を返します。--no-wait を指定するとタスク ID がすぐに返されます。後から listenhub voice-clone get <taskId> --json で確認できます。

タスクが失敗した場合は、理由を簡潔に伝えてください。通常、音声が短すぎる、長すぎる、または明瞭な発話がないことが原因です。別の録音で再試行することを提案してください。

Step 5 — プレビューを提示し、保存する前に確認する

ユーザーにプレビュー URL を伝え、この音声を保存するかどうかを尋ねてください。自分の判断で確定してはいけません。

保存を希望する場合は、名前（最大 50 文字）と性別（male／female／other）を尋ねてから、次を実行してください。

listenhub voice-clone confirm --task-id <taskId> --name "<name>" --gender <gender> --json

応答に、クォータを使い切っており 300 クレジットが必要と表示された場合は、使用する前にユーザーに確認してください。明確な承諾を得てから、次を実行してください。

listenhub voice-clone confirm --task-id <taskId> --name "<name>" --gender <gender> --use-credits --json

Step 6 — スピーカー ID を伝える

listenhub voice-clone speakers --json

一覧から新しい音声の speakerInnerId を読み取り、音声が必要な場所ならどこでも使用できることをユーザーに伝えてください。たとえば、次のように使えます。

listenhub tts create --text "..." --speaker-id <speakerInnerId>

クローン音声の管理

目的	コマンド
音声、クォータ、残りの確定回数を一覧表示する	listenhub voice-clone speakers --json
音声を 1 つ確認する	listenhub voice-clone speaker <speakerId> --json
名前／性別を変更する	listenhub voice-clone update <speakerId> --name "<name>" --gender <gender> --json
音声を削除する（枠を空ける）	listenhub voice-clone delete <speakerId> --json

speakers は maxSpeakers（プランで一度に保持できる音声の数）と remainingConfirmations（この期間に残っている確定回数）を返します。ユーザーが maxSpeakers に達している場合は、別の音声をクローンする前に、既存の音声のうちどれを削除するか尋ねてください。削除すると枠は空きますが、すでに消費した確定回数は返却されません。

エラー処理

症状	意味	対処方法
アップグレードが必要	音声のクローン作成には有料プランが必要です	ユーザーに伝え、再試行しないでください
クレジットが必要	クォータを使い切っており、課金が承認されていません	--use-credits を指定して再実行する前に確認してください
音声数の上限に達しました	プランで既に maxSpeakers 個の音声を保持しています	一覧表示して 1 つ削除することを提案してください
既に確定済み	タスクは以前に確定されています	voice-clone speakers からスピーカー ID を読み取ってください。二重に課金されることはありません
発話を検出できない／時間が無効	参照音声を使用できません	より明瞭な、または長い録音を依頼してください
処理中／一時的に利用できません	別の確定処理が進行中か、一時的な障害が発生しています	数秒待ってから、同じコマンドを再試行してください

注意事項

• openapi コマンドグループでは、API キーを使用するユーザー向けに同じフローを利用でき、日本語と一度だけ実行する --auto-confirm モードも使用できます：listenhub openapi voice-clone create --consent ...。ユーザーが明示的に API キーを使用している場合を除き、上記のログイン済みコマンドを優先してください。
• クローン音声はアカウント内でのみ使用でき、スピーカーの一覧表示では公式音声と並んで表示されます。