mcpField
T
text-to-sfx

text-to-sfx

github.com/sonilo-ai创意与媒体1171.4k 次安装1 天前更新
代码仓库

关于 text-to-sfx

text-to-sfx 是 Sonilo 的 Skill，可根据文字描述生成单段音效，无需视频输入，适合需要独立音效的创作者，并通过 MCP 工具或命令行返回音频文件。

主要功能

  1. 01根据文字生成单段音效
  2. 02可选音效时长
  3. 03支持 WAV、MP3、AAC 或 FLAC
  4. 04支持 MCP 与命令行
  5. 05自动轮询生成任务

适用场景

  1. 01根据描述制作 UI 提示音
  2. 02生成用于剪辑叠加的呼啸声
  3. 03无需视频素材制作拟音效果

MCP 相关

`text_to_sfx` MCP 工具接收描述和可选参数，轮询异步生成任务，并返回已保存文件的路径。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sonilo-ai/skills --skill text-to-sfx

安装后在 Claude Code 中输入/text-to-sfx确认已加载。

详细介绍

Sonilo 文本转音效

根据文本描述生成单个音效——无需视频。提示词就是输入内容，因此请直接描述动作和材料。生成任务会在后端异步运行；工具会在内部轮询，并返回已保存的文件。

设置： 请参阅 setup-api-key 技能。

⚠️ 费用： 此工具会发起可能产生费用的 API 调用。仅在明确收到请求时调用。

想让音效匹配视频素材？ 请使用 video-to-sfx——它会读取剪辑内容，并能将音效固定在特定时刻，而文本提示词无法做到这一点。

传输方式：MCP 或 CLI

在会话开始时选择一种方式，并始终使用该方式。不要在同一任务中混用两种方式，也不要宣布你的选择。

  1. 本会话中可见 Sonilo MCP 工具（text_to_sfx 等）——请使用这些工具。这是首选方式：无需 shell，而且这是唯一能支持超长生成任务的方式。如果调用因身份验证失败，而非输入问题失败，则此会话中无法使用该传输方式：请转到第 2 项，不要重试。
  2. 没有可用的 Sonilo MCP 工具，但 sonilo account 的退出码为 0——请使用以下 CLI 命令。API、账户和凭据文件都相同。请使用 sonilo account 进行探测，而非 sonilo whoami：即使未登录，whoami 也会以 0 退出码结束，因此无法区分这两种状态。
  3. 两者都不可用——请停止并运行 setup-api-key 技能。不要用 curl 调用 api.sonilo.com 来绕过这一限制；这两种传输方式都会处理上传、轮询和重试，而直接请求不会。

快速开始

MCP 工具调用（推荐）
text_to_sfx(
    prompt="Thunder rumbling in the distance with light rain",
    duration=6
)
Python（pip install sonilo）
from sonilo import Sonilo

client = Sonilo()  # reads SONILO_API_KEY

sfx = client.text_to_sfx.generate(prompt="Thunder rumbling in the distance with light rain", duration=6)
sfx.save("thunder.m4a")
JavaScript / TypeScript（npm install sonilo）
import { SoniloClient } from "sonilo";

const client = new SoniloClient(); // reads SONILO_API_KEY

const sfx = await client.textToSfx.generate({
  prompt: "Thunder rumbling in the distance with light rain",
  duration: 6,
});
CLI（npm install -g sonilo-cli 或 pip install sonilo-cli）
sonilo text-to-sfx --prompt "Thunder rumbling in the distance with light rain" --duration 6

底层始终采用异步方式——CLI 会为你提交任务并轮询。--format 接受 wav|mp3|aac|flac。

cURL（原始 REST API，无 MCP 宿主）
curl -X POST "https://api.sonilo.com/v1/text-to-sfx" \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  --data-urlencode "prompt=Thunder rumbling in the distance with light rain" \
  --data-urlencode "duration=6"
# -> {"task_id": "..."}  poll GET /v1/tasks/{task_id} until status is succeeded/failed

端点会返回 {"task_id": ...}（HTTP 202）；当 status 进入终态后，可通过 GET /v1/tasks/{task_id} 获取结果。MCP 工具会为你完成轮询，并直接返回保存路径——只有在调用超时的情况下，你才会看到 task_id（请参阅 task-recovery）。

工具

工具描述
text_to_sfx(prompt, duration?, audio_format?, output_directory?)仅根据文本描述生成一段音效片段。

参数

参数类型默认值说明
promptstring—必填。1–2000 个字符。
durationnumberSonilo 默认值，8 s可选，0.5–180 秒。用户未指定时长时请省略，不要自行设定。允许使用小数值：最短的音效（如门闩声或点击声）持续时间远不到一秒。
audio_formatstringaac（.m4a）wav、mp3、aac 或 flac。
output_directorystringSONILO_MCP_BASE_PATH绝对路径，或相对于基础路径的路径。

提示词编写

提示词是唯一输入——没有视频素材可供映射。请直接描述动作和材料，并组合不同元素：“Heavy rain on a tin roof”（大雨落在铁皮屋顶上）比单独写“Rain”（雨）更好；风格化提示可使用“Cinematic braam, horror”（电影感的低沉冲击音，恐怖风格）或“8-bit retro jump sound”（8 位复古跳跃音效）。与视频方式一样，可以使用相同的材料词汇和音效组合思路：references/sfx-prompting.md。

生成一次，然后迭代修改提示词，而不是反复重生成——失败的运行会自动退款，但你自行重试会产生新的费用。

工作流提示

  • 适用于没有视频上下文的单个音效片段——例如 UI 提示音、呼啸声，或你要自行叠加的拟音元素。如果用户有视频素材，请改用 video-to-sfx。
  • 时长为可选项；切勿自行编造。 传入用户指定的时长。如果用户未指定，则省略 duration，Sonilo 会使用默认值（8 s）——仅当时长确实对用户很重要时才询问。
  • 不要将其与音乐混淆。 如需背景配乐或音轨，请使用 text-to-music 或 video-to-music。

恢复超时的调用

后端已采用异步处理；该工具会轮询至少 45 分钟（如果 TIME_OUT_SECONDS 设置得更高，则会轮询更久），因为请求可能会因上游容量不足而排队这么久。MCP 主机仍可能因自身的工具调用超时而提前中断调用。如果调用超时，错误中会包含 task_id——任务仍会继续运行（并且已计费）。稍后调用 get_sfx_task(task_id)——托管服务上则调用 get_generation_task(task_id)——以获取结果；请参阅 task-recovery。

输出文件

文件以请求的 audio_format 保存（.wav/.mp3/.flac，或默认 aac 对应的 .m4a），文件名取自提示词（转换为 slug 格式），或使用 sfx-<first 8 chars of the task id>。

错误处理

常见错误：401 密钥无效，402 余额不足 / 试用额度已用尽，422 参数无效（例如时长超出范围），429 请求频率超限。请参阅 account 技能。

评论

支持 Markdown