Back to Details

text-to-sfx

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sonilo Text-to-SFX

Sonilo 文本转SFX

Generate a single sound effect from a text description — no video involved. The prompt IS the input, so describe the action and materials directly. Generation runs as an async task on the backend; the tool polls internally and hands back the saved file.
Setup: See the setup-api-key skill.
⚠️ Cost: this tool makes an API call that may incur charges. Only call it when explicitly requested.
Matching sound to footage instead? Use video-to-sfx — it reads the cut and can pin sounds to specific moments, which a text prompt cannot do.
仅根据文本描述生成单个音效——无需视频参与。提示词即为输入内容，请直接描述动作和材质。生成任务在后台以异步方式运行；工具会自动内部轮询，并返回保存好的文件。
设置： 请查看setup-api-key技能。
⚠️ 费用说明： 本工具会调用API，可能产生费用。仅在明确被请求时使用。
想要为视频片段匹配音效？ 使用video-to-sfx——它可以读取剪辑内容，并将音效固定到特定时刻，而文本提示词无法做到这一点。

Transport: MCP or CLI

传输方式：MCP 或 CLI

Pick one at the start of the session and stay on it. Do not mix the two inside a single job, and do not announce the choice.
  1. Sonilo MCP tools visible in this session (
    text_to_sfx
    and friends) — use them. This is the preferred path: it needs no shell, and it is the only one that survives a very long generation. If a call fails to authenticate — rather than failing on its inputs — this transport is not usable in this session: go to 2 instead of retrying it.
  2. No usable Sonilo MCP tools, but 
    sonilo account
    exits 0     — use the CLI commands below. Same API, same account, same credential file. Probe with 
    sonilo account
    , not 
    sonilo whoami
    : whoami exits 0 even when signed out, so it cannot tell the two states apart.
  3. Neither — stop and run the setup-api-key skill. Do not call 
    api.sonilo.com
    with curl to work around it; both transports handle uploads, polling and retries that a bare request does not.
在会话开始时选择其中一种方式并保持使用，不要在单个任务中混合使用两种方式，也无需告知用户你的选择。
  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
    来规避问题；上述两种传输方式均能处理上传、轮询和重试，而裸请求无法做到这些。

Quick Start

快速开始

MCP tool call (recommended)

MCP工具调用（推荐）

text_to_sfx(
    prompt="Thunder rumbling in the distance with light rain",
    duration=6
)
text_to_sfx(
    prompt="Thunder rumbling in the distance with light rain",
    duration=6
)

Python (
pip install sonilo
)

Python（
pip install sonilo
）

python
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")
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
)

JavaScript / TypeScript（
npm install sonilo
）

ts
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,
});
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
or 
pip install sonilo-cli
)

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
Always async under the hood — the CLI submits and polls for you. 
--format
accepts 
wav|mp3|aac|flac
.
bash
sonilo text-to-sfx --prompt "Thunder rumbling in the distance with light rain" --duration 6
后台始终采用异步处理——CLI会提交任务并自动轮询。
--format
参数支持
wav|mp3|aac|flac
格式。

cURL (raw REST API, no MCP host)

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"
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": "..."} poll GET /v1/tasks/{task_id} until status is succeeded/failed

-> {"task_id": "..."} 轮询GET /v1/tasks/{task_id}直到状态为成功/失败


The endpoint returns `{"task_id": ...}` (HTTP 202) and the result is fetched from `GET /v1/tasks/{task_id}` once `status` is terminal. The MCP tool does this polling for you and returns the saved path directly — you only see the `task_id` if the call times out (see [task-recovery](../task-recovery)).

该端点会返回`{"task_id": ...}`（HTTP 202状态码），当`status`变为终态后，可通过`GET /v1/tasks/{task_id}`获取结果。MCP工具会自动完成轮询，并直接返回保存路径——仅当调用超时（详见[task-recovery](../task-recovery)）时，你才会看到`task_id`。

Tool

工具

ToolDescription
text_to_sfx(prompt, duration, audio_format?, output_directory?)
Generate one SFX clip from a text description only.
工具描述
text_to_sfx(prompt, duration, audio_format?, output_directory?)
仅根据文本描述生成一个SFX片段。

Parameters

参数

ParameterTypeDefaultNotes
prompt
string—Required. 1–2000 chars.
duration
int—Required. 1–180 seconds. There is no source to take the length from, so you must set it.
audio_format
string
aac
(
.m4a
)
wav
, 
mp3
, 
aac
, or 
flac
.
output_directory
string
SONILO_MCP_BASE_PATH
Absolute, or relative to the base path.
参数类型默认值说明
prompt
字符串—必填。长度1-2000字符。
duration
整数—必填。1-180秒。由于没有来源可获取时长，因此必须手动设置。
audio_format
字符串
aac
（
.m4a
）		可选值：
wav
、
mp3
、
aac
或
flac
。
output_directory
字符串
SONILO_MCP_BASE_PATH
绝对路径，或相对于基础路径的相对路径。

Prompting

提示词撰写

The prompt is the only input — there is no footage to map. Describe the action and the materials directly, and combine elements: "Heavy rain on a tin roof" beats "Rain"; "Cinematic braam, horror" or "8-bit retro jump sound" for stylized cues. The same materials vocabulary and sound-bundle thinking as the video path applies: references/sfx-prompting.md.
Generate once and iterate on the prompt, not on rerolls — failed runs auto-refund, but your own retry is a new charge.
提示词是唯一的输入——没有视频片段可映射。请直接描述动作和材质，并组合元素：例如“铁皮屋顶上的大雨”比“雨”的效果更好；如需风格化提示音，可使用“电影式轰鸣，恐怖风格”或“8位复古跳跃音效”。适用于视频路径的材质词汇和音效组合思路同样适用于此：references/sfx-prompting.md。
生成一次后，请通过调整提示词来迭代优化，而非重新生成——失败的任务会自动退款，但自行重试会产生新的费用。

Workflow Tips

工作流程提示

  • This is for a single clip with no video context — a UI chime, a whoosh, a foley element you'll layer yourself. If the user has footage, use video-to-sfx instead.
  • Duration is required here. Don't guess it — ask if the user hasn't said.
  • Don't confuse this with music. For a background score or soundtrack, use text-to-music or video-to-music.
  • 本工具适用于无视频上下文的单个片段——比如UI提示音、呼啸声、需自行叠加的拟音元素。如果用户有视频片段，请使用video-to-sfx工具。
  • 此处必须指定时长。请勿猜测——如果用户未说明，请询问。
  • 请勿与音乐生成混淆。如需生成背景配乐或原声，请使用text-to-music或video-to-music工具。

Recovering a Timed-Out Call

恢复超时调用

Async on the backend already; a long generation can still exceed 
TIME_OUT_SECONDS
. If it does, the error carries a 
task_id
— the job keeps running (and is already charged). Call 
get_sfx_task(task_id)
— 
get_generation_task(task_id)
on the hosted server — later to retrieve the result; see task-recovery.
后台已采用异步处理；但长时间生成任务仍可能超出
TIME_OUT_SECONDS
限制。如果发生超时，错误信息中会包含
task_id
——任务仍会继续运行（且已产生费用）。稍后可调用
get_sfx_task(task_id)
（托管服务器上为
get_generation_task(task_id)
）来获取结果；详见task-recovery。

Output Files

输出文件

Saved in the requested 
audio_format
(
.wav
/
.mp3
/
.flac
, or 
.m4a
for the 
aac
default), named from the prompt (slugified) or 
sfx-<first 8 chars of the task id>
.
文件将以请求的
audio_format
保存（
.wav
/
.mp3
/
.flac
，默认
aac
格式为
.m4a
），文件名由提示词转换而来（简化格式）或为
sfx-<任务ID的前8位字符>
。

Error Handling

错误处理

Common errors: 
401
invalid key, 
402
insufficient balance / trial exhausted, 
422
invalid parameters (e.g. duration out of range), 
429
rate limit. See the account skill.
常见错误：
401
密钥无效，
402
余额不足/试用期限已满，
422
参数无效（例如时长超出范围），
429
请求频率超限。详见account技能。