text-to-sfx
熱門Generate a sound effect from a text description using Sonilo — a UI chime, a whoosh, an impact, ambience, a stylized cue — when there is no video to match. Use when the user describes the sound they want in words and gives a duration. For SFX matched to footage, use the video-to-sfx skill; for music, use text-to-music.
Generate a sound effect from a text description using Sonilo — a UI chime, a whoosh, an impact, ambience, a stylized cue — when there is no video to match. Use when the user describes the sound they want in words and gives a duration. For SFX matched to footage, use the video-to-sfx skill; for music, use text-to-music.
Sonilo Text-to-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.
Transport: MCP or 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.
- Sonilo MCP tools visible in this session (
text_to_sfxand 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. - No usable Sonilo MCP tools, but
sonilo accountexits 0 — use the CLI commands below. Same API, same account, same credential file. Probe withsonilo account, notsonilo whoami: whoami exits 0 even when signed out, so it cannot tell the two states apart. - Neither — stop and run the setup-api-key skill. Do not call
api.sonilo.comwith curl to work around it; both transports handle uploads, polling and retries that a bare request does not.
Quick Start
MCP tool call (recommended)
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 or pip install sonilo-cli)
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.
cURL (raw REST API, no MCP host)
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
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).
Tool
| Tool | Description |
|---|---|
text_to_sfx(prompt, duration, audio_format?, output_directory?) |
Generate one SFX clip from a text description only. |
Parameters
| Parameter | Type | Default | Notes |
|---|---|---|---|
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. |
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.
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.
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.
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>.
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.
