Sound effects

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

Tool arguments

{
  "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).
• 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:

{
  "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. Skill + MCP is the recommended integration; use REST for custom, non-agent applications.