Sound Effects

Generate sound effects from text prompts, trim them, and save them to your library

Overview

The Audio Effects page turns a text description into a sound effect: "heavy wooden door creaking open", "retro arcade power-up", "rain on a tin roof, looping". Generated effects can be auditioned on a waveform, trimmed to a region, downloaded, and saved to Saved Content for reuse.

Generating an Effect

1Describe the sound. Name the source, the space, and the motion: "metal sword drawn from a leather sheath, close-up".
2Set the duration in seconds. The provider enforces a maximum length (typically 10-30s).
3Optionally adjust prompt influence and loop (see below), then generate.
4Audition on the waveform. Drag to select a region to preview or download just a slice.
5Download the file, or Save SFX to add it to Saved Content — as a new item or a new version of an existing one.

Generation options

Option	Type	Description
`durationSeconds`*	number	Length of the effect. Longer costs more tokens (per-second pricing).
`promptInfluence`	number 0-1	How literally to follow the prompt. Low = more variety, high = closer adherence. Default 0.3.
`loop`	boolean	Generate a seamless loop — ideal for ambient beds like rain, wind, or machinery.

Writing good SFX prompts

•Lead with the sound source: "glass bottle rolling on concrete".
•Add the acoustic space: "...in a large empty warehouse".
•Describe motion and timing: "three slow knocks, then silence".
•For loops, describe steady-state textures rather than one-shot events.

Pricing

Sound effects are charged per second of requested audio, using the provider's configured rate (with optional free seconds and a minimum). Tokens are reserved before generation and refunded automatically if it fails, so a failed generation never costs anything.

Saving to Your Library

Saved effects live in Saved Content with the generation prompt as their description, the decoded duration, and optional tags. Saving supports Save as New and Update Existing — updating appends a new version to an existing effect, and the new version becomes the active one.

API Access

SFX generation requires the sfx:write scope. The API uploads the result to storage and returns a URL (not base64); pass save to also store it in Saved Content.

POST/api/v1/sfx/generatesfx:write

Field	Type	Description
`text`*	string	What the sound effect should sound like
`durationSeconds`*	number	Length in seconds (provider max applies)
`promptInfluence`	number 0-1	Prompt adherence vs variety (default 0.3)
`loop`	boolean	Generate a seamless loop
`save`	object	Optional { name, projectId?, tags? } — also save to Saved Content

Generate and save in one call:

curl -s https://<host>/api/v1/sfx/generate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "heavy castle door slamming shut, big stone hall reverb",
    "durationSeconds": 4,
    "save": { "name": "Castle Door Slam", "tags": ["door", "impact", "castle"] }
  }'

Response:

{
  "success": true,
  "result": {
    "audioUrl": "https://<r2-public>/sfx/<org>/unassigned/<uuid>.mp3",
    "audioKey": "sfx/<org>/unassigned/<uuid>.mp3",
    "contentType": "audio/mpeg",
    "filename": "sfx_<uuid>.mp3",
    "tokensCharged": 8,
    "savedContent": { "id": "...", "name": "Castle Door Slam", "contentType": "sfx", ... }
  }
}

MCP

The same operation is available to AI agents as the generate_sfx MCP tool — see MCP Server.