text-to-sfx

原文：🇺🇸 英文

已翻译

当没有匹配的视频时，使用Sonilo根据文本描述生成音效——比如UI提示音、呼啸声、撞击声、环境音、风格化提示音等。适用于用户用文字描述想要的音效并提供时长的场景。如果需要为视频片段匹配音效，请使用video-to-sfx技能；如果需要生成音乐，请使用text-to-music技能。

354次下载

来源sonilo-ai/skills

添加于2026-08-16

NPX安装

npx skill4agent add sonilo-ai/skills text-to-sfx

SKILL.md 内容（中文）

查看翻译对照 →

Sonilo 文本转SFX

仅根据文本描述生成单个音效——无需视频参与。提示词即为输入内容，请直接描述动作和材质。生成任务在后台以异步方式运行；工具会自动内部轮询，并返回保存好的文件。

设置： 请查看setup-api-key技能。

⚠️ 费用说明： 本工具会调用API，可能产生费用。仅在明确被请求时使用。

想要为视频片段匹配音效？ 使用video-to-sfx——它可以读取剪辑内容，并将音效固定到特定时刻，而文本提示词无法做到这一点。

传输方式：MCP 或 CLI

在会话开始时选择其中一种方式并保持使用，不要在单个任务中混合使用两种方式，也无需告知用户你的选择。

当前会话中可见Sonilo MCP工具（
```
text_to_sfx
```
及相关工具）——使用这些工具。这是首选方式：无需shell，且是唯一支持长时间生成任务的方式。如果调用因认证失败（而非输入错误），则该传输方式在当前会话中不可用：请直接切换到方式2，不要重试。
无可用的Sonilo MCP工具，但
sonilo account
命令返回0——使用下方的CLI命令。API、账户和凭证文件均相同。请用
```
sonilo account
```
命令验证，不要用
```
sonilo whoami
```
：即使已登出，whoami仍会返回0，无法区分两种状态。
以上两种方式均不可用——停止操作并运行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

）

python

from sonilo import Sonilo

client = Sonilo()  # 读取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

）

ts

import { SoniloClient } from "sonilo";

const client = new SoniloClient(); // 读取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

）

bash

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主机）

bash

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": "..."}  轮询GET /v1/tasks/{task_id}直到状态为成功/失败

该端点会返回

{"task_id": ...}

（HTTP 202状态码），当

status

变为终态后，可通过

GET /v1/tasks/{task_id}

获取结果。MCP工具会自动完成轮询，并直接返回保存路径——仅当调用超时（详见task-recovery）时，你才会看到

task_id

。

工具

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

参数

参数	类型	默认值	说明
`prompt`	字符串	—	必填。长度1-2000字符。
`duration`	整数	—	必填。1-180秒。由于没有来源可获取时长，因此必须手动设置。
`audio_format`	字符串	`aac` （ `.m4a` ）	可选值： `wav` 、 `mp3` 、 `aac` 或 `flac` 。
`output_directory`	字符串	`SONILO_MCP_BASE_PATH`	绝对路径，或相对于基础路径的相对路径。

提示词撰写

提示词是唯一的输入——没有视频片段可映射。请直接描述动作和材质，并组合元素：例如“铁皮屋顶上的大雨”比“雨”的效果更好；如需风格化提示音，可使用“电影式轰鸣，恐怖风格”或“8位复古跳跃音效”。适用于视频路径的材质词汇和音效组合思路同样适用于此：references/sfx-prompting.md。

生成一次后，请通过调整提示词来迭代优化，而非重新生成——失败的任务会自动退款，但自行重试会产生新的费用。

工作流程提示

本工具适用于无视频上下文的单个片段——比如UI提示音、呼啸声、需自行叠加的拟音元素。如果用户有视频片段，请使用video-to-sfx工具。
此处必须指定时长。请勿猜测——如果用户未说明，请询问。
请勿与音乐生成混淆。如需生成背景配乐或原声，请使用text-to-music或video-to-music工具。

恢复超时调用

后台已采用异步处理；但长时间生成任务仍可能超出

TIME_OUT_SECONDS

限制。如果发生超时，错误信息中会包含

task_id

——任务仍会继续运行（且已产生费用）。稍后可调用

get_sfx_task(task_id)

（托管服务器上为

get_generation_task(task_id)

）来获取结果；详见task-recovery。

输出文件

文件将以请求的

audio_format

保存（

.wav

/

.mp3

/

.flac

，默认

aac

格式为

.m4a

），文件名由提示词转换而来（简化格式）或为

sfx-<任务ID的前8位字符>

。

错误处理

常见错误：

密钥无效，

余额不足/试用期限已满，

参数无效（例如时长超出范围），

请求频率超限。详见account技能。

text-to-sfx

NPX安装

标签

SKILL.md 内容（中文）

Sonilo 文本转SFX

传输方式：MCP 或 CLI

快速开始

MCP工具调用（推荐）

Python（
`pip install sonilo`
）

JavaScript / TypeScript（
`npm install sonilo`
）

CLI（
`npm install -g sonilo-cli`
或
`pip install sonilo-cli`
）

cURL（原生REST API，无MCP主机）

工具

参数

提示词撰写

工作流程提示

恢复超时调用

输出文件

错误处理

text-to-sfx

NPX安装

标签

SKILL.md 内容（中文）

Sonilo 文本转SFX

传输方式：MCP 或 CLI

快速开始

MCP工具调用（推荐）

Python（pip install sonilo）

JavaScript / TypeScript（npm install sonilo）

CLI（npm install -g sonilo-cli 或 pip install sonilo-cli）

cURL（原生REST API，无MCP主机）

工具

参数

提示词撰写

工作流程提示

恢复超时调用

输出文件

错误处理

Python（
`pip install sonilo`
）

JavaScript / TypeScript（
`npm install sonilo`
）

CLI（
`npm install -g sonilo-cli`
或
`pip install sonilo-cli`
）