音声合成

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

Agent の主経路

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

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

AI ガイド

AI 連携 Markdown

独自アプリケーションに組み込む場合は、この API ガイドを Claude や Codex などにコピーできます。

Markdown

ツール引数

{
  "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 にはボイス管理が返す任意の voice_id を指定できます。プリセットとクローンボイスの挙動は同じです。ストリーミングとリアルタイム会話はこの機能には含まれません。

共通コントロールは input（必須、≤50,000 文字）、voice（必須）、 language、format（デフォルト mp3、ほかに wav/flac/opus/pcm）、 speed（0.5–2.0）、volume（>0–10）、pitch（−12–12）、emotion、 sample_rate です。各コントロールは選択したモデルのメタデータに従ってのみ使用します。

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

音声はリクエスト見積で前払いされ、加重文字数に応じて線形に課金されます（単価は加重文字 1,000 あたりで提示）：漢字 1 文字は 2、それ以外は 1 と数えます。

言語

language はオプションのプロバイダー中立な BCP-47 タグです（例：zh-CN、 yue-HK、en-US）。Beatra は主言語サブタグを選択モデルと照合します。省略するとボイスまたはモデルが言語を検出します。未対応の言語は黙って置き換えられず、拒否されます。

現在の音声モデルは以下の 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`	アフリカーンス語

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

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

REST で呼び出す

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