Product
Text-to-Sound-Effects API: Generate SFX from a Prompt
- Written by
- Sonilo Team
- Published
The text-to-sound-effects API turns a short text description into an isolated, licensed sound effect — no video required, no background music mixed in, just the sound you asked for.
Quick answer
POST /v1/text-to-sfx generates a standalone sound effect from a text prompt — think glass shattering, footsteps on gravel, distant thunder, a UI click, or a whoosh transition. It's built for Foley, impacts, ambience, and interface sounds, not for background music (use text-to-music for that) and not for sound tied to a specific video's visual events (use video-to-sfx for that). Every request is processed asynchronously: you get a task_id back immediately, then poll for the finished audio file. Output is fully licensed via Shutterstock, so it's commercial-safe out of the box.
| Field | Type | Notes |
|---|---|---|
| prompt | string | Required. 1-2000 characters. e.g. "glass shattering, footsteps on gravel, distant thunder". |
| duration | integer | Required. Length of the output in seconds, 1-180. |
| audio_format | string | Optional. One of wav, mp3, aac, flac. No default — omit to use the API's standard format. |
Example request
The request body is multipart/form-data, not JSON. Send your prompt and duration as form fields:
curl -X POST https://api.sonilo.com/v1/text-to-sfx -H "Authorization: Bearer $SONILO_API_KEY" -F prompt="glass shattering, footsteps on gravel, distant thunder" -F duration=6 -F audio_format=wav
This endpoint is always async — there's no sync or streaming mode. The call above returns 202 immediately with {"task_id": "...", "status": "processing"}. Poll GET /v1/tasks/{task_id} until status is succeeded or failed:
curl https://api.sonilo.com/v1/tasks/$TASK_ID -H "Authorization: Bearer $SONILO_API_KEY"
When status is succeeded, the response includes an sfx object with url, content_type, and file_size — download the file from url and you're done. Prefer not to hand-roll polling? The official SDKs handle it for you: pip install sonilo (Python) or npm install sonilo (JavaScript/TypeScript).
FAQ
What's the maximum duration for text-to-sfx?
180 seconds, with a 1-second minimum. duration is a required integer field.
What audio formats can I get?
Set audio_format to wav, mp3, aac, or flac. The field is optional and has no default, so pick one explicitly if your pipeline expects a specific container and codec.
How is this different from video-to-sfx?
text-to-sfx generates a sound effect from a written prompt alone — there's no video input and no attempt to sync to on-screen events. video-to-sfx instead analyzes an uploaded video and generates sound effects timed to what's happening in the footage. Use text-to-sfx when you know exactly what sound you want and don't have (or don't need) a video to anchor it to.
Do I need to poll, or is there a synchronous option?
Polling is required — text-to-sfx is always processed asynchronously, with no sync or streaming mode. Expect an immediate 202 with a task_id, then check GET /v1/tasks/{task_id} until it reports succeeded or failed.
Is the output licensed for commercial use?
Yes. Every sound effect generated through the API is fully licensed via Shutterstock, so it's cleared for commercial projects without separate rights clearance. In independent benchmarking with the open-source audio-eval toolkit (https://github.com/shwj114114/audio_eval), Sonilo Sound Effects 1.0 outperformed ElevenLabs SFX v2 on 16 of 24 text-to-sound-effects metrics.
Related Sonilo pages
- Full API reference: https://platform.sonilo.com/docs/api/text-to-sfx
- Pricing: https://sonilo.com/pricing
- Python SDK: pip install sonilo
- JavaScript/TypeScript SDK: npm install sonilo
