# Sound effects
> Generate sound effects and loopable ambient audio from text prompts.

Generate sound effects, Foley cues, and seamless loopable ambient audio from text prompts.

## Primary agent path

Use the Universal Skill with the MCP tool `beatra.audio.generate_sfx`. The tool
is billable and returns an asynchronous task.

1. If model constraints, output formats, or prices matter, call
   `beatra.models.list` with `capability: "sound_effects"`. Otherwise use
   `model: "auto"` or omit `model` (resolves to `elevenlabs-sfx-v3`).
2. Write a concrete acoustic prompt describing the sound, texture, and timing.
   Omit `duration_seconds` when you want the model to pick a natural length, or
   pass an explicit duration between `0.5` and `30.0` seconds.
3. Create one opaque `client_request_id` and submit the final arguments once.
4. Poll the returned task with `beatra.tasks.get` until it is terminal.

## AI guide

AI integration guide: https://docs.beatra.ai/llms/audio-sound-effects.md

## Tool arguments

```json
{
  "prompt": "Soft steady rain on a wooden porch roof with distant warm thunder",
  "duration_seconds": 10.0,
  "loop": true,
  "prompt_influence": 0.35,
  "format": "mp3",
  "client_request_id": "sfx-opaque-1"
}
```

- `prompt` (required, `1`–`2,000` characters): text description of the sound
  effect, Foley action, UI cue, or ambient bed. Blank prompts or prompts over
  2,000 characters are rejected before billing with `422 invalid_request`.
- `model` (optional, default `"auto"`): `"auto"` or `"elevenlabs-sfx-v3"`.
- `duration_seconds` (optional, `0.5`–`30.0` seconds): target clip length.
  Omit `duration_seconds` (`null`) to let the model pick the optimal duration
  for the prompt. Explicit values below `0.5` or above `30.0` seconds are
  rejected before billing with `422 invalid_request`.
- `loop` (optional, boolean, default `false`): when `true`, generates a clip
  whose end transitions seamlessly back to its start — suited to game loops,
  room tone, and background ambience. To extend a loopable clip to an exact
  minute-scale duration afterward, pass the resulting artifact to
  `beatra.audio.process` with `operation: "loop"` (see
  [audio processing](https://docs.beatra.ai/en/docs/capabilities/speech/audio-processing)).
- `prompt_influence` (optional, `0.0`–`1.0`, default `0.3`): controls how
  tightly generation adheres to the prompt wording. Higher values follow the
  prompt more literally; lower values leave more acoustic room to the model.
- `format` (optional, default `"mp3"`): `"mp3"` (44.1 kHz), `"wav"` (24 kHz
  16-bit mono PCM in a RIFF `WAVE` `audio/wav` container), `"opus"` (48 kHz), or
  `"pcm"` (raw 24 kHz 16-bit signed little-endian mono PCM, `audio/pcm`).
- `model_options` (optional, object): forward-compatible bag for
  model-specific extension options.

## Models, controls, and cost

`beatra.models.list` with `capability: "sound_effects"` is the live source for
selectable models, parameter ranges, supported formats, and credit rates. Do
not hardcode prices in agent prompts.

Sound effects are prepaid by **audio seconds** (`ceil(duration_seconds)`) with
a minimum per-request floor:

- `elevenlabs-sfx-v3`: `13 credits` per second, minimum `61 credits` per request.
- When `duration_seconds` is omitted, billing reserves **5 seconds** (`65 credits`).
- Explicit `0.5`–`4.0` second clips reserve the `61`-credit minimum; a `10`-second
  clip reserves `130 credits`; a `30`-second clip reserves `390 credits`.

## Result

When the task succeeds, `output` carries the generated audio artifact:

```json
{
  "type": "sound_effects",
  "model": "elevenlabs-sfx-v3",
  "loop": true,
  "audio": {
    "artifact_id": "artifact_01JX...",
    "url": "https://cdn.beatra.ai/tenants/.../sfx.mp3",
    "duration_seconds": 10.0,
    "mime_type": "audio/mpeg",
    "size_bytes": 160432
  }
}
```

## Task status and recovery

`queued` and `running` are not failures. Keep polling the same `task_id`; never
submit a replacement because work is still running. On a lost create response,
retry the identical arguments with the same `client_request_id`. If any input
changes, use a new ID. Failed tasks automatically refund the reserved credits.
Artifact URLs are CDN addresses — copy them to your own storage promptly.

## REST API

Direct protocol integrations may use `POST /v1/audio/sound-effects` with a
stable `Idempotency-Key` header, optional `callback_url`,
`callback_signing_key_id`, and `metadata`, plus the shared task endpoints.
Follow the generated [API reference](https://docs.beatra.ai/en/docs/api-reference). Skill + MCP is the
recommended integration; use REST for custom, non-agent applications.