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

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

## 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 ガイド

AI integration guide: https://docs.beatra.ai/llms/audio-sound-effects.md

## ツール引数

```json
{
  "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"` に渡せます（[オーディオ処理](https://docs.beatra.ai/ja/docs/capabilities/speech/audio-processing)を参照）。
- `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 が入ります。

```json
{
  "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 リファレンス](https://docs.beatra.ai/ja/docs/api-reference)を参照してください。推奨の統合方法は Skill + MCP です。REST は Agent ではないカスタムアプリケーション向けです。