音效生成

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

Agent 主路径

通过 Universal Skill 使用 MCP 工具 beatra.audio.generate_sfx。该工具计费，返回异步任务。

当模型约束、输出格式或价格有影响时，用 capability: "sound_effects" 调用 beatra.models.list；否则使用 model: "auto" 或省略 model（默认解析为 elevenlabs-sfx-v3）。
用具体的听觉描述写出声音材质、动作节奏与空间感。需要模型自己决定自然时长时省略 duration_seconds，或显式传入 0.5–30.0 秒之间的时长。
创建一个不透明的 client_request_id，把最终参数提交一次。
用 beatra.tasks.get 轮询返回的任务直到终态。

AI 指南

给 AI 的集成说明

接入自有应用时，可以把这份 API 指南复制给 Claude、Codex 或其他编程助手。

Markdown

工具参数

{
  "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"（见音频处理）。
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 返回生成的音频产物：

{
  "type": "sound_effects",
  "model": "elevenlabs-sfx-v3",
  "loop": true,
  "audio": {
    "artifact_id": "artifact_01JX...",
    "url": "https://cdn.beatra.cn/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）及共享任务端点，详见接口参考。推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。