---
title: "A sound effect or an ambience as a stereo WAV."
method: POST
path: "/api/agents/run/sound_effect"
tags: ["Production engines"]
---

# A sound effect or an ambience as a stereo WAV.

`POST /api/agents/run/sound_effect`

## Request

- Base URL: `https://tomorrowlives.com`
- URL: `https://tomorrowlives.com/api/agents/run/sound_effect`
- Auth: HTTP bearer

Renders one sound from the engine's own synth as a stereo WAV, or an ambience of the beds mixed together. Give sound (a name from sound_list) with a, b and c as sound_list says, or give ambience: any of engine, air, surf, rain, drum, gull and creak, each 0 to 1, with seconds (1 to 30, default 10; loop true makes it seamless, its end crossfaded into its start, for a game that plays it on repeat; an ambience otherwise fades out). seed varies a one-shot, rate is 44100 or 48000, and peak_db (-30 to 0, default -3) is where the loudest sample sits, so a footstep and a thunder come back at one level; raw true keeps the synth's own. Nothing is sampled from a recording. Costs 1 unit.

## Request body

- object
  - `sound` 'step' | 'door' | 'take' | 'blow' | 'hurt' | 'fell' | 'woke' | 'work' | 'ending' | 'thunder' | 'splash' | 'clang' | 'swing' | 'lob' | 'thud' | 'note' | 'reed' | 'engine' | 'murmur' | 'animal' | 'siren': A sound name from sound_list. Give this, or ambience.
  - `a` number: The sound's first parameter, as sound_list says what it does for this sound.
  - `b` number: The sound's second parameter, 0 to 1, as sound_list says.
  - `c` number: The sound's third parameter, -1 to 1, as sound_list says.
  - `seed` integer: A whole number that varies a one-shot sound.
  - `ambience` object: Instead of sound: a mix of beds (engine, air, surf, rain, drum, gull, creak), each a level from 0 to 1.
    - `engine` number
    - `air` number
    - `surf` number
    - `rain` number
    - `drum` number
    - `gull` number
    - `creak` number
  - `seconds` number: Length of an ambience in seconds, 1 to 30 (default 10).
  - `loop` boolean: True to make an ambience seamless, its end crossfaded into its start.
  - `rate` 44100 | 48000: Sample rate in hertz: 44100 or 48000.
  - `peak_db` number: Where the loudest sample sits in dBFS, -30 to 0 (default -3).
  - `raw` boolean: True to keep the synth's own level instead of normalising to peak_db.

## Response `200`

The job's result and files

- Job
  - `job` string
  - `verb` string
  - `units` integer
  - `ms` integer
  - `result` unknown
  - `files` object[]
    - `name` string
    - `bytes` integer
    - `content_type` string
    - `url` string
    - `url_expires_at` string, date-time

## Other responses

- `400`: The input is not valid
- `401`: No valid API key
- `402`: A pass or a payment is needed: a queued render on the free plan, a unit pack on the free plan (pass_required), a card plan's past-due renewal, or, on the free plan, an owner who has not confirmed their email yet (owner_unconfirmed; a pass needs no confirmation); or a payment did not go through (payment_failed, payment_token_unusable), and nothing was charged
- `403`: The account is suspended, the paying card is not from the United States (region_not_supported), or the address named as its owner said it is not theirs and costed runs are paused until a new owner is named (owner_removed)
- `413`: The input or the output is over its cap; a job stopped by the output cap is not charged
- `422`: The engine refused the input, a limit of the service's refused it (error: video_limit or pull_limit) or stopped the job, or the content policy refused the input (error: content_policy)
- `429`: A limit was hit; reset_at says when it lifts (also in Retry-After)
- `503`: The engines are busy or not installed
- `504`: The job ran past its time and was stopped

---

[API](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines.md) · [All operations](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines/llms.txt) · [OpenAPI document](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines/revisions/afc3d67322ac?raw)