効果音生成

テキストのプロンプトから効果音、フォーリー音、シームレスにループする環境音を生成します。

Agent の主経路

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

1. モデルの制約、出力フォーマット、価格を確認する必要がある場合は capability: "sound_effects" で beatra.models.list を呼びます。それ以外は model: "auto" を使うか model を省略します（elevenlabs-sfx-v3 が選ばれます）。
2. 音の質感、動き、空間の広がりを具体的にプロンプトに書きます。自然な長さをモデルに 任せる場合は duration_seconds を省略し、長さを決める場合は 0.5〜30.0 秒の 範囲で指定します。
3. 不透明な client_request_id を 1 つ作り、最終的な引数を一度だけ送信します。
4. 返されたタスクを beatra.tasks.get で終端状態までポーリングします。

AI ガイド

ツール引数

{
  "prompt": "木の軒先に降り続く穏やかな雨音と、遠くで低く響く雷鳴",
  "duration_seconds": 10.0,
  "loop": true,
  "prompt_influence": 0.35,
  "format": "mp3",
  "client_request_id": "sfx-opaque-1"
}

• prompt（必須、1〜2,000 文字）：効果音、フォーリー、UI サウンド、環境音の説明。空文字または 2,000 文字超は課金前に 422 invalid_request で拒否されます。
• model（任意、既定 "auto"）："auto" または "elevenlabs-sfx-v3"。
• duration_seconds（任意、0.5〜30.0 秒）：目標の秒数。省略（null）するとプロンプトに合う長さをモデルが自動選択します。0.5 秒未満または 30.0 秒超の値は課金前に 422 invalid_request で拒否されます。
• loop（任意、真偽値、既定 false）：true にすると終端から先頭へ自然につながるループ音源を生成します（ゲームのループ音や環境音に最適）。生成後に分単位の正確な長さへ延ばす場合は、返された artifact を beatra.audio.process の operation: "loop" に渡せます（オーディオ処理を参照）。
• prompt_influence（任意、0.0〜1.0、既定 0.3）：プロンプトの文言にどれだけ忠実に従うかを調整します。高いほど記述どおりになり、低いほどモデルに自然な表現の幅を与えます。
• format（任意、既定 "mp3"）："mp3"（44.1 kHz）、"wav"（24 kHz 16-bit モノラル RIFF WAVE audio/wav コンテナ）、"opus"（48 kHz）、"pcm"（生データの 24 kHz 16-bit リトルエンディアン モノラル PCM、audio/pcm）に対応します。
• model_options（任意、オブジェクト）：モデル固有の拡張指定を渡すための前方互換フィールドです。

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

選択可能なモデル、パラメータ範囲、対応フォーマット、クレジット単価の最新の事実源は capability: "sound_effects" を指定した beatra.models.list です。Agent のプロンプトに価格表をハードコードしないでください。

効果音は出力秒数（ceil(duration_seconds)）に応じた前払いで、1 リクエストあたりの最低料金があります。

• elevenlabs-sfx-v3：1 秒あたり 13 クレジット、1 リクエストあたり最低 61 クレジット。
• duration_seconds を省略した場合は 5 秒として課金されます（65 クレジット）。
• 0.5〜4.0 秒の指定は最低料金の 61 クレジット、10 秒は 130 クレジット、30 秒は 390 クレジット です。

結果

タスクが成功すると、output に生成されたオーディオの artifact が入ります。

{
  "type": "sound_effects",
  "model": "elevenlabs-sfx-v3",
  "loop": true,
  "audio": {
    "artifact_id": "artifact_01JX...",
    "url": "https://cdn.beatra.ai/tenants/.../sfx.mp3",
    "duration_seconds": 10.0,
    "mime_type": "audio/mpeg",
    "size_bytes": 160432
  }
}

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

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

REST で呼び出す

プロトコル直結の統合では、固定の Idempotency-Key ヘッダー（および任意の callback_url、callback_signing_key_id、metadata）を付けて POST /v1/audio/sound-effects と共有タスクエンドポイントを使えます。生成されたAPI リファレンスを参照してください。推奨の統合方法は Skill + MCP です。REST は Agent ではないカスタムアプリケーション向けです。