# 音效生成
> 根据文字描述生成音效与可无缝循环的环境音。

根据文字描述生成动作拟音、交互提示音与可无缝循环的环境氛围音。

## 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`，把最终参数提交一次。
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` 字符）：音效、拟音动作、界面提示音或环境底噪的文字描述。空字符串或超过 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` 时生成首尾平滑衔接的可循环片段，适合游戏循环音效、环境底声与氛围铺底。若后续需要把循环片段延展到精确的分钟级时长，可把产物交给 `beatra.audio.process` 的 `operation: "loop"`（见[音频处理](https://docs.beatra.ai/zh/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`（可选，对象）：前向兼容的模型专属扩展选项袋。

## 模型、控制项与成本

`beatra.models.list`（传入 `capability: "sound_effects"`）是可选模型、参数范围、支持格式与积分单价的实时事实来源；请勿在 Agent 提示词中硬编码价格表。

音效按**音频秒数**（`ceil(duration_seconds)`）预扣积分，并设单次最低起步价：

- `elevenlabs-sfx-v3`：每秒 `13 积分`，单次最低 `61 积分`。
- 省略 `duration_seconds` 时按 **5 秒**计费（`65 积分`）。
- 显式指定 `0.5`–`4.0` 秒按最低 `61 积分` 计费；`10` 秒为 `130 积分`；`30` 秒为 `390 积分`。

## 结果

任务成功时，`output` 返回生成的音频产物：

```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 调用

直连协议集成可使用 `POST /v1/audio/sound-effects`（携带固定的 `Idempotency-Key` 请求头，可选 `callback_url`、`callback_signing_key_id` 与 `metadata`）及共享任务端点，详见[接口参考](https://docs.beatra.ai/zh/docs/api-reference)。推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。