# 音声合成
> プリセットまたはクローンしたボイスで、テキストを音声に合成します。

プリセットまたはクローンしたボイスで、テキストを音声に合成します。

## Agent の主経路

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

1. まずボイスを選びます。`beatra.voices.list` がプリセットとクローンの
   `voice_id` と試聴 URL を返します。
2. モデル・言語・フォーマット・価格が結果に影響する場合は
   `capability: "text_to_speech"` で `beatra.models.list` を呼びます。
   そうでなければ `model: "auto"` を使うか `model` を省略します。
3. 不透明な `client_request_id` を 1 つ作り、最終的な引数を一度だけ送信します。
4. 返されたタスクを `beatra.tasks.get` で終端状態までポーリングします。

より人が語っているような声にしたい場合は、先に `beatra.speech.prepare_script` で
[AI ディレクター](https://docs.beatra.cn/ja/docs/capabilities/speech/ai-director)に文章を読み解かせ、口調・間・感情を演出してから、
返された台本をこのツールで合成します。

## AI ガイド

AI integration guide: https://docs.beatra.cn/llms/audio-text-to-speech.md

## ツール引数

```json
{
  "voice": "voice_01JX...",
  "input": "Welcome to Beatra — make your first call in three minutes.",
  "language": "en-US",
  "format": "mp3",
  "speed": 1.0,
  "client_request_id": "tts-opaque-1"
}
```

`voice` には[ボイス管理](https://docs.beatra.cn/ja/docs/capabilities/speech/voices)が返す任意の
`voice_id` を指定できます（プリセットでも[クローンボイス](https://docs.beatra.cn/ja/docs/capabilities/speech/voice-clone)でも可）。
各ボイスは 1 つのエンジンに属します（`compatible_models`）。モデルによっては、ボイスごとに従うコントロールが異なり、
ボイスの `persona` に書かれています。
ストリーミングとリアルタイム会話はこの機能には含まれません。

## マークアップ

`input` には閉じたトークン集合を書けます。トークンは選択したモデルの `constraints.input_max_characters` 上限と、
加重文字の課金の両方に数えます。語彙と各モデルの値域は
`beatra.models.list` のモデルカード `constraints.script_markup` です。
同じマークアップがすべての音声モデルで使えます。モデルが表現できないものは除去または無視され、
警告が返ります（近似で置き換えることはありません）。このページ下部の「モデル固有のオプション」は
`model_options` のフィールドであり、マークアップではありません。
書き方を誤ったマークアップでもリクエストは失敗しません。直せるものは正しいトークンとして扱い、直せないものは除去するか書かれたとおりに読み、`markup_adjusted` で理由と正しい書き方を返します。マークアップだけで読み上げるテキストがないリクエストだけは、どのモデルでも課金前に 422 で拒否されます。

- `{pause <seconds>}` — 無音。小数は最大 2 桁で、モデルカードの `script_markup.pause.range` の範囲内（MiniMax は最長 99.99 秒、Doubao は 10 秒で、超えた分は上限に切り詰められ警告が返ります）。秒数には単位も付けられます（`{pause 500ms}`、`{pause 0.5s}`）。ElevenLabs は pause を実行せず、除去して `markup_degraded` を返します（「ElevenLabs v4 と v4 Turbo」を参照）。書き方を誤った pause（`{pause}`、`{pause abc}` など）とテキスト全体の先頭・末尾の pause は除去し、連続する pause（間に読めるテキストがない）は最初の 1 つだけ残します。いずれも `markup_adjusted` を返します。
- 音のタグ：`{laugh}` 笑い声、`{chuckle}` 軽い笑い、`{sigh}` ため息、`{breath}` 息継ぎ、`{cough}` 咳、`{clear-throat}` 咳払い、`{gasp}` 息をのむ音、`{groan}` うめき声、`{inhale}` 吸気、`{exhale}` 呼気、`{pant}` 荒い息、`{sniff}` 鼻をすする音、`{hmm}` 「うーん」（迷い・考え中）。`script_markup.tags` にモデルが出せるタグが並びます。対応していないモデルではタグを取り除き（読み上げません）、`markup_degraded` 警告を返します。
- `{pron <word> <reading>}` — マークした箇所だけ語の読みを固定します。同じ語のほかの箇所は既定の読みのままで、1 回のリクエストで同じ字に別々の読みを指定できます。読み記法は拼音です。音節を直結し、各音節は声調数字 1–5 で終わり、ü は v、中国語の語は 1 文字につき 1 音節です。それ以外の記法は未対応です。音節の間に空白があれば結合します。読みの書き方を誤った場合（読みがない、拼音でない、音節数が合わない）は書かれたとおりに読み、`markup_adjusted` を返します。読みが複数に分かれていて、どれかが拼音でない場合（右波括弧の閉じ忘れなど）は、グループ全体を本文として残し、`unknown_markup` を返します。例：`孩子{pron 长 zhang3}大了，头发也很{pron 长 chang2}。`
- `{sub <word> <spoken text>}` — マークした箇所の語を指定した文言（最大 100 文字）で読み上げます。字幕には元の語が表示されます。ブランド名、略語、英単語、1 桁ずつ読ませたい数字に使います。読み方がない場合は元の語を読み、`markup_adjusted` を返します。読み方が 100 文字を超える場合はグループ全体を本文として残し、`unknown_markup` を返します。例：`{sub W3C 万维网联盟}`。
- `{{` — 文字どおりの左波括弧です。`{{` と書いた位置は `{` として読まれ、この 2 文字自体はトークンとして解析されません。その後のテキストは通常どおり解析されるため、左波括弧だけをエスケープし、右波括弧はそのまま書いてください。
- `{emotion <感情>}` — 行内の感情：この位置から次の `{emotion …}` までこの感情で読みます。リクエストの `emotion` が最初の感情で、値も同じです。モデルカードに `script_markup.inline_emotion` があるモデルだけが文ごとに切り替えます。ほかのモデルはマーカーを除去してリクエスト全体を `emotion` で合成し、`markup_degraded` を返します（対応モデルがあれば示します）。値が無効な場合は除去し（読み上げません）、`markup_adjusted` を返します。例：`我们出发吧。{emotion happy}看，前面就是海！{emotion sad}可惜明天就要回去了。`
- 演技マーカー — 後に続く文に効き、次の段落には持ち越しません。使えるマーカーはモデルカードの `script_markup.performance` のとおりで、載っているモデルだけが演じます。ほかのモデルは除去し、`markup_degraded` を返します（対応モデルがあれば示します）。
- 綴りの近い書き方は正しいトークンとして扱い（`{laughs}`、`{Laugh}` は `{laugh}`）、`markup_adjusted` を返します。全角の波括弧の中が既知の書き方（`｛pause 1｝` など）なら正しいトークンとして扱い、`markup_adjusted` を返します。それ以外の全角の波括弧は本文です。知らない波括弧の内容（`{name}` など）や、マークアップに似ていても余計な内容があるもの（`{pause: 1000}`、`{pause and think}`）は本文としてそのまま残し、`unknown_markup` を返します。角括弧・丸括弧の中の文字（`[笑]`、`（小声）` など）は本文として上流にそのまま渡し、演技指示に見える場合は `unrecognized_markup` を返します。感情や演技の語については、現在のモデルが演じられる正しいトークンだけを提案します。

各モデルカードの `constraints.limitations` には、そのモデルの制限が文章で書かれています。呼び出すモデルのカードを読んでください。例：

- 音量・速度・音高はリクエスト全体に適用され、特定の一文や一語には効きません。感情も同じですが、モデルカードに `script_markup.inline_emotion` があるモデルは例外です。部分的に変えたい場合は複数回の呼び出しに分ける（それぞれパラメータと音声ファイルが別になります）か、テキストの書き換え（省略記号・短い文・言い回し）で調整してください。
- モデルによっては、長いテキスト（3,000 文字を超えると非同期パス）で高品質な数値正規化が使えない、または `{pause}`・`{pron}` マークアップを取り除きます（警告あり）。必要な場合は段落の区切りで 3,000 文字以下のリクエストに分けてください。

## 演技の指示と前の文

次の 2 つのオプションフィールドは、この音声をどう読むかを伝えます。従うモデルはモデルカードの `controls` に並びます（関連する数値は `constraints.direction_max_characters` と `constraints.previous_text_tail_characters`）。

- `direction` — リクエスト全体への自然言語の演技指示。例：`像在耳边说悄悄话一样，轻声地说`、`read it like breaking news`。一、二文に収めてください。`direction_max_characters` を超える指示は無視され、警告が返ります。実際の効果はモデル、ボイス、テキストによります。音量は `volume` で指定してください。
- `previous_text` — この音声の直前に来るテキスト（会話の前の台詞、前の段落）で、別々に合成した音声の口調をつなげます。長さは自由で、モデルは末尾の `previous_text_tail_characters` 文字だけを使います。読み上げられません。

どちらも課金されず、リクエストを失敗させることもありません。フィールドに従わないモデル・ボイス・パスはそれを無視して `option_ignored` 警告を返し、音声は通常どおり生成されます。モデルによっては、ボイス（たとえばキャラクター系ボイスはどちらにも従わない）にも左右されます。モデルカードの `constraints.limitations` に書かれています。`emotion` も同じで、モデルやボイスが表現できない感情は無視され、警告が返ります。課金前にボイスがこれらのコントロールに従うか知りたい場合は、同じリクエストを下記の validate に送ってください。同じ警告が無料で返ります。

課金する送信の前に `beatra.speech.validate` または
`POST /v1/audio/speech/validate` を使えます。同じ解析と警告チェックを行い、
加重文字数と必要クレジットを返します。タスクは作成せず、クレジットも消費せず、
音声エンジンも呼び出しません。`Idempotency-Key` は不要です。ElevenLabs の 2 件同時実行の上限と現在の容量は確認しません。

warnings があるとき、それは 202（冪等リプレイを含む）、
`GET /v1/tasks/{task_id}`、`beatra.tasks.get`、顧客コールバックの
`task.warnings` に出ます。タスク一覧、`expand`、アカウント詳細、admin は
保証しません。字幕の `text_begin` / `text_end` はエンジンが実際に読んだテキスト
（マークアップを各エンジンの形へコンパイルしたもの、または取り除いたもの）への
オフセットであり、送信原文へはマッピングし直しません（ElevenLabs は例外で、位置はマークアップを除き各 `{sub}` を書かれた語で表示したテキストを指します。マークアップがなければ送信したテキストそのものです）。字幕の区間がこのテキストと
一致する場合、`text` では `{pron}`・`{sub}` の語が元の表記で表示され、音のタグは含まれません。
課金の文字数は後述の「モデル・コントロール・コスト」の節を参照してください。`output.characters` はエンジンが
実際に読んだ文字数のため、二つの数は異なり得ます。ElevenLabs では `output.characters` が課金された加重文字数です。

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

共通コントロールは `input`（必須、上限はモデルカードを参照）、`voice`（必須）、
`language`、`format`（デフォルト `mp3`。ほかの対応形式はモデルカードの `constraints.formats`）、
`speed`（0.5–2.0）、`volume`（モデルカードの `constraints.volume` の範囲内。例：>0–10、0.5–2。範囲外は課金前に拒否されます）、`pitch`（−1–1、正規化：0 = 元の音高、
−1 は最低、1 はモデルが許容する最高音高。細かい調整は 0.25 のような小数）,
`emotion`、`sample_rate`、`subtitle_enable`（デフォルト `false`。`true` にすると
文単位の字幕が `output.subtitles` として音声とともに返ります。無料です。選んだボイスや言語で
モデルが字幕を作れない場合は課金前に拒否され、`constraints.limitations` にその条件が書かれています。
MiniMax と Doubao は実行時の字幕失敗後も音声を返す場合があります。ElevenLabs は要求された字幕を必須とし、交付できない場合はタスクを失敗させて返金します）。
`language` はモデルによって一部しか使われません。選んだモデルでの扱いは `constraints.limitations` に
書かれています。各コントロールは選択したモデルのメタデータに従ってのみ
使用します。フォーマットによって対応サンプリングレートは異なります
（例：`opus` はモデルによって 8/16/24 kHz のみ、または固定の 48 kHz で `sample_rate` を受け付けません）。すべてのフォーマットに共通のレート一覧を前提にせず、モデルカードの
`constraints.sample_rates_by_format` を参照してください。

選択可能なモデル、対応言語、フォーマット、サンプルレート、価格の最新の
事実源は `beatra.models.list` です。モデルカタログや価格表を agent の
プロンプトに複製しないでください。

音声はリクエスト見積で前払いされ、加重文字数に応じて**線形**に課金されます
（単価は加重文字 1,000 あたりで提示）：漢字 1 文字は 2、それ以外のコードポイントは 1 と数えます。送信した原文（マークアップを含む）で数えます。エンジンが受け取る制御テキストを長さで課金するモデルでは、エンジンに送るテキストのほうが長ければそちらで数えます。そこでは pause や読みが制御タグになり、タグを含む（または本文が `<speak` で始まる）リクエストは全文がその形式で送られます（`&`・`<`・`>` はエスケープされます）。正確な文字数は validate が返します。

## モデル固有のオプション

`model_options` は特定のモデル系列だけが実行するオプションで、系列名で区切ります。モデルカードの `controls` に、そのモデルが実行するキーが並びます（例：`model_options.doubao.explicit_dialect`）。別系列のキーは効きません。モデルが `option_ignored` 警告で知らせることがあります。

### MiniMax：読み辞書

難読漢字や複数の読みを持つ漢字は、同音の漢字に書き換えなくても、読みを直接指定できます:

```json
{
  "model_options": {
    "minimax": {
      "pronunciation_dict": {
        "tone": ["湛/(zhan4)", "晞/(xi1)", "厌/(yan1)"]
      }
    }
  }
}
```

形式は `文字/(ピンイン+声調番号)`。声調番号は四声が 1–4、軽声が 5 です。
辞書の項目はリクエスト内のその語のすべての箇所に適用されます。1 か所だけ直す場合は、
上記の `{pron}` マークアップを使ってください。MiniMax 系モデルのみ対応で、
他のモデルはこのフィールドを無視します。

### Doubao

- `model_options.doubao.explicit_dialect` — `beijing`、`dongbei`、`henan`、`shaanxi`、`shanghai`、`sichuan`、`tianjin`（広東語は `language: "yue-HK"`）。方言を話せるのは `languages_supported` に `yue` を含むボイスだけで、ほかのボイスは課金前に拒否されます。
- `model_options.doubao.silence_duration` — 最後の語のあとに足す無音（0–30,000 ミリ秒）。
- `model_options.doubao.explicit_language` — 読み上げ言語を強制します（`zh-cn`、`en`、`ja`、`es-mx`、`ko`、`de`、`fr` など）。これはヒントではなくフィルターです。ほかの言語の文は飛ばされ、ボイスが読めないテキストは音声になりません（タスクは失敗し、返金されます）。`nl`、`no`、`uk`、`fi`、`da`、`cs`、`hu`、`el`、`ro`、`hi`、`es-es` は中国語（`zh_…`）のプリセットボイスでのみ有効です。長いテキストで使えるのは `zh-cn`、`en`、`es-mx`、`id`、`pt-br` だけです。
- `model_options.doubao.latex_parser` — `"v2"` で LaTeX の数式を読み上げます（教育向け）。
- `model_options.doubao.pronunciation_dict` — `{"tone": ["北京/(bei3)(jing1)", "omg/oh my god"]}`：最大 5,000 件で、その語のすべての箇所に適用されます（読みまたは置き換え文言）。1 か所だけ直すなら `{pron}` を使ってください。

テキストで `{pause}` や `{pron}` を使う場合はマークアップが優先されます。`latex_parser` と `pronunciation_dict` は無視され、警告が返ります。エンジンがマークアップの変換後の形式と同時に扱えないためです。

## 言語

`language` はオプションのプロバイダー中立な BCP-47 タグです（例：`zh-CN`、
`yue-HK`、`en-US`）。Beatra は主言語サブタグを選択モデルと照合します。
省略するとボイスまたはプロバイダーが選択します。自動言語検出を明示的に
要求する場合のみ固定値 `auto` を渡してください（モデルカードの
`constraints.language_auto` が対応可否を示します）。未対応の言語は黙って
置き換えられず、拒否されます。

`language` の使い方はモデルによって異なります。ボイスへの認識ヒントとして使うモデルもあれば、
中国語と英語を既定で読み、それ以外の言語では `language` で言語認識をオンにする（たとえば中国語の
ボイスが日本語を読む場合、渡さないと読めないことがあります）とともに方言（`yue`）を選ぶモデルもあります。
後者では各ボイスが `languages_supported` の言語だけを読み、ボイスが話せない言語を渡すと
`option_ignored` 警告が返ります。結果が失敗にしかならない場合は課金前に拒否されます（広東語を話せないボイスへの
広東語、ボイスが読めない言語の長いテキスト）。どちらかはモデルカードの `constraints.limitations` で確認してください。

現在の音声モデルは以下の最大 40 言語をカバーし、各モデルはその一部に対応します。モデル別のリアルタイムな
事実源は `beatra.models.list` の `constraints.supported_languages` です。

| コード | 言語 | コード | 言語 |
| --- | --- | --- | --- |
| `zh` | 中国語 | `tr` | トルコ語 |
| `yue` | 広東語 | `nl` | オランダ語 |
| `en` | 英語 | `uk` | ウクライナ語 |
| `es` | スペイン語 | `th` | タイ語 |
| `fr` | フランス語 | `pl` | ポーランド語 |
| `ru` | ロシア語 | `ro` | ルーマニア語 |
| `de` | ドイツ語 | `el` | ギリシャ語 |
| `pt` | ポルトガル語 | `cs` | チェコ語 |
| `ar` | アラビア語 | `fi` | フィンランド語 |
| `it` | イタリア語 | `hi` | ヒンディー語 |
| `ja` | 日本語 | `bg` | ブルガリア語 |
| `ko` | 韓国語 | `da` | デンマーク語 |
| `id` | インドネシア語 | `he` | ヘブライ語 |
| `vi` | ベトナム語 | `ms` | マレー語 |
| `fa` | ペルシア語 | `sk` | スロバキア語 |
| `sv` | スウェーデン語 | `hr` | クロアチア語 |
| `fil` | フィリピン語 | `hu` | ハンガリー語 |
| `no` | ノルウェー語 | `sl` | スロベニア語 |
| `ca` | カタルーニャ語 | `nn` | ニーノシュク |
| `ta` | タミル語 | `af` | アフリカーンス語 |

## ElevenLabs v4 と v4 Turbo

`elevenlabs-v4` と `elevenlabs-v4-turbo` はすべてのアカウントで利用でき、デフォルトのモデルカタログに表示されます。80 個のプリセットボイスも使えます（[ボイス管理](https://docs.beatra.cn/ja/docs/capabilities/speech/voices)を参照）。`elevenlabs-v4` は 2 つのうち最も表現力が高いモデルです。`elevenlabs-v4-turbo` は同じボイスと言語を使い、より高速で、料金は約半分です。v4 は学習を続けるため、同じボイスでも時間とともに結果が変わることがあり、同じ `seed` でもモデル更新後に同じ結果になる保証はありません。

| モデル | 加重 1,000 文字あたりのクレジット |
| --- | ---: |
| `elevenlabs-v4-turbo` | 240 |
| `elevenlabs-v4` | 450 |

ElevenLabs のボイスで `model: "auto"` を使うと、互換モデルの中で Turbo が優先されます。モデルは受付前に確定し、失敗時にモデルやボイスを切り替えません。

### 長さと数え方

1 回のリクエストは最大 **10,000 文字**で、Unicode コードポイントで数えます。原文とコンパイル後のテキスト（マークアップ適用後）のそれぞれが上限の対象です。ほかのエンジンは 50,000 までです。超過は課金前に `422 invalid_request` となります。本文を短くするか、マークアップを減らすか、`emotion` を外して再検証してください。自動で複数の音声に分割することはありません。

上限ではコードポイント 1 つを 1 と数えるため、見た目が 1 つの記号でも 2 以上になることがあります。

- 漢字、英字、コードポイント 1 つの絵文字は 1 です。
- 絵文字の連続は、すべてのコードポイントを数えます。👍🏽 = 2、❤️ = 2、🇨🇳 = 2、1️⃣ = 3、👨‍👩‍👧‍👦 = 7。
- 結合文字は別々に数えます。デーヴァナーガリーの母音記号、アラビア語の補助記号、分解形のアクセント記号はそれぞれ 1 加わります。

課金も同じコードポイントの規則に重みを付けます。漢字 1 文字は 2、それ以外のコードポイントは 1 です。原文とコンパイル後のテキストを加重で数え、大きいほうで課金します。ElevenLabs では `output.characters` がこの課金された加重文字数です。

### フォーマット・言語・コントロール

- 言語は `en`、`zh`、`ja`、`ko`、`es`、`pt`、`ar`、`hi`、`fr`、`it`。`language` を省略するか `auto` を指定すると自動認識、ほかの明示言語は課金前に拒否します。
- MP3 は 22,050 / 24,000 / 44,100 Hz（既定 44,100）、WAV・生 PCM は 8,000 / 16,000 / 22,050 / 24,000 / 32,000 Hz（既定 24,000）。Opus は 48,000 Hz 固定で、`sample_rate` は省略必須です。FLAC は提供しません。PCM の結果は `mime_type` が `audio/L16` で、実際の `duration_seconds` が付きます。推定音声が 1 件の結果のサイズ上限を超える非常に長い WAV/PCM リクエストは、課金前に 422 `unsupported_option`（フィールド `format`）で拒否されます。これは 32,000 Hz の中国語・日本語・韓国語の長いテキスト（約 7,500 文字以上）にだけ当てはまります。MP3 または Opus、低いサンプルレート、短いテキストを使ってください。
- `direction` と既定値以外の `speed`、`volume`、`pitch` は `option_ignored` 警告とともに無視されます。
- `emotion` は `fluent` 以外の 7 種類に対応します。Beatra は各段落（空行で区切ります）の先頭に感情タグ（`[sad]` など）を加えます。感情はタグの位置から始まり、長い段落では弱まることがあるため、必要に応じて空行で段落を分けてください。タグの分だけ送信テキストが長くなるため、課金文字数が増えることがあり（課金は原文と送信テキストの多いほう）、10,000 文字の上限にも数えられます。`fluent` は `option_ignored` とともに無視されます。13 個の音のタグ（`{laugh}` など）はすべて対応し、置いた位置でその音を出します。効果はボイスとテキストによって変わり、`{sigh}`・`{breath}` などの息の音は控えめで、聞き取りにくいことがあります。
- pause は実行しません。`{pause}` は `markup_degraded` とともに除去されます（モデルカードの範囲は [0, 0]）。書き方を誤った pause は共通ルールで除去され、`markup_adjusted` が返ります。`{pron}` は書かれたとおりに読まれ、`markup_degraded` が返ります。
- 行内の感情は文ごとに効きます。`{emotion <感情>}` の位置に感情タグを入れ、その後の各段落の先頭にも現在の感情を入れ直します。`fluent` は警告とともに無視され、その後の段落には感情タグを入れません。演技マーカーはモデルカードの `script_markup.performance` のとおりに演じます。両モデルとも 10 個すべてに対応しています：`{whisper}` ささやき、`{shout}` 叫ぶ、`{excited}` 興奮、`{sarcastic}` 皮肉、`{curious}` 好奇心、`{tearful}` 涙声、`{playful}` おどけた、`{nervous}` 緊張、`{tired}` 疲れた、`{gentle}` やさしい。タグは次に読み上げる内容の直前に入り、後に続く文に効き、段落をまたぎません。挿入したタグは字幕に出ず、送信テキストに数えられます。
- `{sub 元の語 読み方}` は読み方を発声し、字幕には元の語を表示します。自分で書いた角括弧は顧客のテキストとしてそのまま渡され、字幕にも残ります。Beatra のマークアップではありません。上流のモデルがそれを音や口調として演じることがあります。
- `subtitle_enable: true` は、実測の文字タイムスタンプによる文単位の字幕を約束します。ElevenLabs の字幕の `text_begin`、`text_end` は、マークアップを除き各 `{sub}` を書かれた語で表示したテキストを指します。マークアップがなければ送信したテキストそのものです。有効な字幕を作れない場合はタスクが失敗し、この合成は返金されます。音声だけの成功はなく、有料の文字起こしでタイムスタンプを補うこともありません。
- `previous_text` と `model_options.elevenlabs.next_text` は文脈としてだけ使われ、課金されません。Beatra がモデルに送るのは、前の文の末尾 100 文字と次の文の先頭 100 文字です。

`model_options.elevenlabs` は `stability`・`similarity_boost`（有限数 0–1）、`seed`（整数 0–4,294,967,295）、`next_text`（文字列）、`apply_text_normalization` を受け付けます。現在有効な正規化の値はモデルカードの `constraints.limitations` に記載され、両モデルとも現在は `auto` のみで、`on`、`off` は警告付きで無視されます。未知のキーも警告付きで無視され、既知のキーの不正な値は課金前に拒否されます。

料金を確認する前に、**実際に送る全パラメータ**で無料の検証を行ってください。validate は加重文字数と料金を返し、同じ構文と上限を確認しますが、2 件の同時実行上限と現在の容量は確認しません。そのため検証を通ったリクエストでも、下記のエラーになることがあります。テストでは 2,000 文字で約 1 分、10,000 文字では数分かかることがあります。同じタスクをポーリングし続けてください。

### 上限とエラー

ElevenLabs の音声合成タスクは、1 アカウントあたり同時に 2 件までです。v4 と v4 Turbo の合計です。無料の非公開[クローン試聴](https://docs.beatra.cn/ja/docs/capabilities/speech/voice-clone)も 2 件に含まれ、MiniMax と Doubao のタスクは含まれません。

課金前のエラー。課金されず、タスクも作成されないため、再試行では同じ Idempotency-Key / `client_request_id` を使っても、新しいものを使ってもかまいません。`voice_unavailable` は例外で、恒久的な状態のため再試行できません。

| エラー | `details.reason` | 意味と対処 |
| --- | --- | --- |
| 429 `rate_limited` | `speech_inflight_limit` | ElevenLabs の音声合成タスクがすでに 2 件進行中です。1 件の完了を待ってください。`retry_after_seconds` は 20 で、REST では同じ秒数の `Retry-After` レスポンスヘッダーも返ります（MCP にヘッダーはないため `details.retry_after_seconds` を使います）。 |
| 503 `model_unavailable` | `voice_temporarily_busy` | クローンボイスを準備中または復元中です。`retry_after_seconds` 後に再試行してください（約 30 秒。前回の復元を確認中の間は数分）。 |
| 503 `model_unavailable` | `voice_temporarily_unavailable` | このクローンボイスは現在復元できません。ほかのボイスは使えます。復旧時刻がわかる場合は `available_at` に示されます。 |
| 422 `invalid_request`、`unsupported_option`、`voice_unavailable`、`voice_retired` | — | リクエストを修正してください。下の「ボイスの提供終了」とクローンのページも参照してください。 |

タスクの受付後のエラーはタスクエラーで、すべて全額返金されます。再試行には新しい `client_request_id` または `Idempotency-Key` が必要です。

| タスクエラー | 発生する場面 |
| --- | --- |
| `model_rate_limited` | モデルの処理能力が満杯です。 |
| `model_unavailable` | モデルの利用枠が尽きました。復旧時刻がわかる場合は `available_at` に示されます。 |
| `invalid_request` | モデルがテキストを長すぎるとして拒否しました。 |
| `model_output_invalid` | モデルが使えない音声を返しました。 |
| `voice_retired` | リクエストの受付後にボイスが提供終了しました。 |
| `voice_unavailable`、または reason が `voice_temporarily_busy` / `voice_temporarily_unavailable` の `model_unavailable` | 実行時にクローンボイスを準備できませんでした。意味は課金前と同じで、タスクは返金されます。 |

### ボイスの提供終了

提供終了が予定されているプリセットボイスは、終了日までは一覧に残り、使えます。そのボイスオブジェクトには `retirement: {"retire_at": "<ISO 8601 UTC>", "replacement_voice_id": "<id または null>"}` が付き、予定がないときこのフィールドはありません。そのボイスでの合成は成功し、終了日と（わかる場合は）推奨の代替ボイスを示す `voice_retiring` 警告（中国語の文言、フィールドは `voice`）が付きます。終了日を過ぎると、リクエストは 422 `voice_retired` を返し、`details.retirement_at` に終了時刻、わかる場合は `details.replacement_voice_id` に代替ボイスが入ります。確認は受付時と実行時の 2 回行われ、実行時に該当するとタスクは失敗して返金されます。代替ボイスは提案であり、Beatra がボイスを自動で置き換えることはありません。保存されたサンプルから復元できなくなったクローンボイスは 422 `voice_unavailable` を返します。これは恒久的な状態なので再試行せず、サポートにお問い合わせください。その合成は課金されず、元のクローン料金は返金されません。

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

`queued` と `running` は失敗ではありません。同じ `task_id` をポーリングし
続け、実行中だからといって代替リクエストを送らないでください。作成応答を
失った場合は、同じ `client_request_id` で同一の引数を再送します。入力が
少しでも変わったら新しい ID を使います。失敗したタスクは自動で返金されます。
音声アーティファクト、実際のモデル、課金額は終端状態のタスク応答からのみ
返してください。アーティファクト URL は CDN アドレスです——速やかに自分の
ストレージへコピーしてください。

## REST で呼び出す

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