text-to-sfx

Original：🇺🇸 English

Translated

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.

45installs

Sourcesonilo-ai/skills

Added on2026-08-16

NPX Install

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

SKILL.md Content

View Translation Comparison →

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_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.
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.
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.

Quick Start

MCP tool call (recommended)

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()  # 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

)

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,
});

CLI (

npm install -g sonilo-cli

or

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

.

cURL (raw REST API, no MCP host)

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

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:

invalid key,

insufficient balance / trial exhausted,

invalid parameters (e.g. duration out of range),

rate limit. See the account skill.

text-to-sfx

NPX Install

Tags

SKILL.md Content

Sonilo Text-to-SFX

Transport: MCP or CLI

Quick Start

MCP tool call (recommended)

Python (
`pip install sonilo`
)

JavaScript / TypeScript (
`npm install sonilo`
)

CLI (
`npm install -g sonilo-cli`
or
`pip install sonilo-cli`
)

cURL (raw REST API, no MCP host)

Tool

Parameters

Prompting

Workflow Tips

Recovering a Timed-Out Call

Output Files

Error Handling

text-to-sfx

NPX Install

Tags

SKILL.md Content

Sonilo Text-to-SFX

Transport: MCP or CLI

Quick Start

MCP tool call (recommended)

Python (pip install sonilo)

JavaScript / TypeScript (npm install sonilo)

CLI (npm install -g sonilo-cli or pip install sonilo-cli)

cURL (raw REST API, no MCP host)

Tool

Parameters

Prompting

Workflow Tips

Recovering a Timed-Out Call

Output Files

Error Handling

Python (
`pip install sonilo`
)

JavaScript / TypeScript (
`npm install sonilo`
)

CLI (
`npm install -g sonilo-cli`
or
`pip install sonilo-cli`
)