AI ディレクター

音声合成の前に AI ディレクターが文章を読み解いて演出し、人が語っているような声に仕上げます。

AI ディレクターは原文とユーザーの要望を読み取り、対象のボイスが実際に表現できる書き方で、感情、演技、 効果音、間、読み方を加えた台本を返します。返された台本はそのまま音声合成に使えます。加えるのは演出だけで、 原文は一文字も変更しません。ボイスを指定しない場合は、合うボイスとモデルを推薦し、その理由も示します。

Agent の主経路

Universal Skill から MCP ツール beatra.speech.prepare_script を使います。このツールは課金対象で、 非同期タスクを返します。

1. 原文を input に、仕上がりへの要望があれば instructions に渡します。ユーザーがボイスやモデルを 指定していれば一緒に渡し、なければ省略して AI ディレクターに推薦させます。
2. 不透明な client_request_id を 1 つ作って一度だけ送信し、beatra.tasks.get で終端状態まで ポーリングします。
3. 返された各台本の synthesis をそのまま beatra.speech.synthesize の引数にし、自分の client_request_id を加えて呼び出します。synthesis が null の台本はそのままでは合成できません。 理由は警告で確認できます。
4. ユーザーが調整を求めたら（例：「2 段落目をもっと緊迫させて」）、その文を instructions に 加えて（前の要望は残したまま）もう一度呼び出し、合成し直します。

AI ガイド

ツール引数

{
  "input": "夜は静まり返っていた。彼はドアを押し開けた。「誰かいますか？」返事はなかった。",
  "instructions": "少しサスペンス風に。問いかけはささやき声で。",
  "client_request_id": "script-opaque-1"
}

• input：原文。対応するどの言語でもよく、最大 50,000 文字です。原文にすでに書かれたマークアップ （{pause 0.5} など）はそのまま残し、AI ディレクターはその上に加えるだけです。指定したボイスや モデルが 1 回で読める長さ（ElevenLabs は 10,000 文字）を超える場合は、音声合成と同じ 422 エラーを 返し、料金は発生しません。
• instructions：任意。自然な言葉で書いた要望で、言語は問わず最大 2,000 文字です。指定した場合は要望を 優先し、要望が触れていない部分は文章の意味に沿って自然に演出します。省略すると、全体を文章の意味に沿って 自然に演出します。
• voice、model：任意。意味と既定値は beatra.speech.synthesize と同じです。どちらも省略すると AI ディレクターが推薦し、ボイスだけ指定するとそのボイスのモデルから選び、モデルだけ指定するとその モデルで使えるボイスから推薦します。
• language：任意。通常は省略します（既定の auto で自動判定）。ユーザーが言語を指定した場合や、 文章からは分からない方言（広東語 yue など）のときだけ渡します。
• context：任意の上級者向け設定です。長い文章を分けて演出するとき、その部分の前後の文章を {"before": "…", "after": "…"} の形で渡します（それぞれ最大 2,000 文字）。口調を理解するためだけに使い、 マークアップの追加、読み上げ、返却はしません。対象モデルが対応していれば、before の末尾を前の文として synthesis.previous_text に入れ、前後の口調をつなげます。

結果

タスクが成功すると、output に台本のリストが入ります。

{
  "type": "speech_script",
  "model": "ai-director",
  "directed": true,
  "scripts": [
    {
      "synthesis": {
        "input": "{emotion calm}夜は静まり返っていた。彼はドアを押し開けた。{emotion fearful}{whisper}「誰かいますか？」返事はなかった。",
        "voice": "voice_01JX...",
        "model": "elevenlabs-v4-turbo",
        "language": "ja"
      },
      "summary": "緊張感のある幕開け。問いかけはささやき声で",
      "voice_selection": {
        "source": "recommended",
        "voice": "voice_01JX...",
        "model": "elevenlabs-v4-turbo",
        "name": "Hiroki",
        "preview_url": "https://cdn.beatra.cn/voices/previews/voice_01JX....mp3",
        "reason": "若い男性の声。オーディオブック向けで、一文ごとに演じ分けられます。"
      },
      "alternatives": [
        {"voice": "voice_01JY...", "model": "elevenlabs-v4-turbo", "name": "Rin",
         "preview_url": "https://cdn.beatra.cn/voices/previews/voice_01JY....mp3", "reason": "若い女性の声。オーディオブック向けです。"}
      ],
      "estimate": {"weighted_characters": 72, "price_credits": "18"},
      "warnings": []
    }
  ],
  "warnings": []
}

• scripts：台本 1 つにつき合成 1 回です。現在は常に 1 つですが、今後は複数になることがあります （話者ごとに分ける場合など）。1 つずつ処理してください。
• synthesis：この台本を合成するための引数で、そのまま beatra.speech.synthesize に渡します （client_request_id は自分で加えます）。input はマークアップ入りの台本で、ほかに voice、model、 language と、対象のボイスが実際に従う全体設定 emotion、direction、previous_text が入ります （従わない設定は入りません）。そのままでは合成できない場合は null です。使えるボイスがない、 ボイスがこの台本を読めない、または今回は事前チェックを実行できなかった（後で再試行してください）場合で、 理由は警告で確認できます。
• summary：演出を 1 行で説明したもので、パラメーター名やマークアップを含まず、そのままユーザーに 伝えられます。instructions の言語、要望がなければ原文の言語で書かれます。
• voice_selection：この台本のボイスで、voice、model、ボイスの名前 name、試聴リンク preview_url が入ります。source が recommended なら AI ディレクターの推薦で、reason に理由が入ります。given なら指定されたボイスで、reason は null です。ボイスがない場合はフィールド全体が null です。
• alternatives：推薦した場合は最大 3 個の候補が付き、項目は voice_selection と同じです（source は ありません）。ボイスを指定した場合は空のリストです。
• estimate：この台本を合成したときの正確な価格で、無料の事前チェックと同じ値です。synthesis が null のときは estimate も null です。
• directed：false の場合、今回は AI ディレクターが演出を完了できませんでした。台本は原文のままで、 演出の分は課金されません。synthesis があれば、そのまま合成できます。
• 推薦できるボイスがない場合（警告 no_voice_available）、synthesis、voice_selection、estimate は すべて null です。beatra.voices.list でボイスを選び、その voice を付けてもう一度呼び出してください。

候補のボイスに替えたいときは、2 日以内に voice（必要なら model も）だけを変え、ほかの引数は 同じまま、新しい client_request_id でもう一度呼び出します。AI ディレクターは前回の読み解きを 再利用し、同じ読み解きに二重に課金することはありません。新しいボイスに合わせて書き直すだけです。この呼び出しにも 残高の見積もりと同時 2 件までの上限が適用されますが、再利用した読み解きは課金されません。

モデルごとの演出

AI ディレクターは、対象モデルが表現できる書き方だけを使います。

• ElevenLabs：一文ごとの感情の切り替え、ささやきや叫びなどの演技、笑い声やため息などの効果音。
• MiniMax：台本全体で 1 つの感情。間、読み方の指定、効果音に対応します。
• Doubao：台本全体で 1 つの感情。間と読み方の指定に対応します。感情、演技の指示、前の文に従うかは ボイスによって異なります。

ユーザーが求めた効果を選んだボイスで表現できない場合、AI ディレクターはそれ以外を演出し、表現できな かったことと代わりに使ったものを警告で伝えます。一文ごとの演技が必要な場合は、一文ごとに演じ分け られるボイスを選んでください。

警告

最上位の warnings は AI ディレクターからユーザーへの説明で、ユーザーに伝えてください。各台本の warnings はその台本に対する無料の事前チェックの警告で、通常は空です。

課金とタスクの状態

AI ディレクターは推論してから演出を書き込み、完了後に実際の入力・出力・推論トークン数で課金されます。 価格と 1,000 文字あたりの目安は、機能カタログ GET /v1/catalog/capabilities/speech_script に載っています。 開始するには、送信する文章の見積もり額（1,000 文字未満は 1,000 文字として数えます）を残高でまかなえる必要が あります。同じアカウントで進行中の別の AI ディレクタータスクがあれば、その見積もり額も合わせて必要です。 1,000 文字あたり 146 クレジットなら、10,000 文字の文章には 1,460 クレジットが必要です。足りない場合は 402 insufficient_balance（details.reason は director_estimate）が返り、タスクは作成されません。 課金額は実際の使用量に基づき、通常は見積もりを下回ります。directed が false の場合と、2 日以内の 同じ読み解きを再利用した場合、演出の分は課金されません。directed が true の場合は実際のトークン数で 課金されます。AI ディレクターが原文に演出を加える必要がないと判断し、原文のまま返した場合も同様です。 合成は音声合成として別に課金され、価格は各台本の estimate で確認できます。

1 アカウントあたり同時に進行できる AI ディレクタータスクは 2 件までで、プラットフォーム全体で同時に進行できる 数にも上限があります。3 件目を送信すると 429 rate_limited（details.reason は director_inflight_limit）が 返り（MCP 経由ではプランの同時実行数の上限が先に適用されることがあります）、AI ディレクターが混み合っている ときは 429（details.reason は director_busy）が返ります。どちらの場合もタスクは開始されず、課金もありません。 director_inflight_limit の場合は、このアカウントの AI ディレクタータスクが 1 件終わってから送信し直して ください。director_busy の場合は、details.retry_after_seconds の秒数が経ってから再試行してください（REST では Retry-After ヘッダーに同じ秒数が入ります）。AI ディレクターが一時的に使えないときは 503 model_unavailable が返ります。モデルを選ぶ機能ではないため、時間をおいて再試行してください。

queued と running は失敗ではありません。同じ task_id をポーリングし続けてください。作成時の レスポンスを受け取れなかった場合は、同じ client_request_id でまったく同じ引数を再送し、入力が 変わったら新しい ID を使います。タスク一覧（GET /v1/tasks）には結果の要約だけが表示されます。 truncated: true が付き、synthesis は含まれません。合成に使える台本は、タスク ID で取得してください （beatra.tasks.get または GET /v1/tasks/{task_id}）。AI ディレクターの結果は台本であって作品ではないため、 作品一覧には表示されません。コンソールでは、アクティビティと請求で「AI ディレクター」と表示されます。

REST で呼び出す

プロトコルを直接扱う連携では、POST /v1/audio/speech/scripts と共通のタスクエンドポイントを使い、 各台本の synthesis をそのまま POST /v1/audio/speech のリクエスト本文として送ります。生成された API 定義 を参照してください。Skill + MCP での連携をおすすめします。REST はエージェント以外の独自アプリ向けです。