> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snapgen.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Sound effects

> Generate a sound effect of 0.5 to 30 seconds from a text prompt and receive the audio in the response.

`POST /v1/audio/sound-effects` generates a sound effect from a text description, such as a door creak, footsteps, or an ambience bed, and returns the audio file as the response body. Set `loop` for a sound that repeats seamlessly.

| Model | Length | Price |
| - | - | - |
| [`eleven-sound-effects-v2`](/api-manual/audio/eleven-sound-effects-v2) | 0.5 to 30 seconds (default 5) | \$0.003 per second (\$0.18 per minute) |

<ParamField body="model" type="string" required>
  Set to `eleven-sound-effects-v2`.
</ParamField>

<ParamField body="prompt" type="string" required>
  What the sound should be, up to 1,000 characters.
</ParamField>

<ParamField body="duration_seconds" type="number" default="5">
  Length in seconds, from `0.5` to `30`. Billed rounded up to whole seconds.
</ParamField>

<ParamField body="prompt_influence" type="number">
  From `0` to `1`. Higher values follow the prompt more closely.
</ParamField>

<ParamField body="loop" type="boolean">
  `true` makes a sound that loops seamlessly.
</ParamField>

<ParamField body="response_format" type="string" default="mp3">
  `mp3`, `opus`, or `pcm`. See
  [Output formats](/api-reference/audio-speech#output-formats).
</ParamField>

Fields that aren't listed here return `invalid_request`.

## Response

A successful request returns HTTP `200` with the audio as the body. The
`Content-Type` matches `response_format`: `audio/mpeg`, `audio/ogg`, or
`audio/pcm`. The response carries `x-gateway-execution-id`.

## Billing

The request is billed for `duration_seconds`, rounded up to whole seconds, at
\$0.003 per second. When you omit `duration_seconds`, the gateway requests and
bills 5 seconds (\$0.015). A 2.5-second effect bills 3 seconds (\$0.009), and
the 30-second maximum costs \$0.09. Failed requests aren't charged.

This endpoint rejects `Idempotency-Key`. If a request times out, check your
Console request logs before you retry.

## Errors

| Status | `error.code` | Cause |
| - | - | - |
| 400 | `invalid_request` | `prompt` is missing or blank, `duration_seconds` is out of range, or a field is unknown. |
| 400 | `idempotency_not_supported` | The request has an `Idempotency-Key` header. |
| 400 | `provider_rejected_request` | The provider refused the prompt. |
| 402 | `insufficient_funds` | Your balance can't cover the request. |
| 404 | `model_not_available` | The model ID is unknown or disabled. A key whose allowlist excludes the model gets `api_key_model_not_allowed` (403). |
| 503 | `no_eligible_route` | The model doesn't run on this endpoint, or no route is available right now. |

See [Errors](/errors) for rate limits and provider failures.

<RequestExample>
  ```bash Curl theme={null}
  curl https://api.snapgen.org/v1/audio/sound-effects \
    -H "Authorization: Bearer $SNAPGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "eleven-sound-effects-v2",
      "prompt": "Heavy wooden door creaking open in an empty hall",
      "duration_seconds": 4
    }' \
    --output effect.mp3
  ```

  ```python Python theme={null}
  import json
  import os
  from urllib.request import Request, urlopen

  request = Request(
      "https://api.snapgen.org/v1/audio/sound-effects",
      data=json.dumps({
          "model": "eleven-sound-effects-v2",
          "prompt": "Heavy wooden door creaking open in an empty hall",
          "duration_seconds": 4,
      }).encode(),
      headers={
          "Authorization": f"Bearer {os.environ['SNAPGEN_API_KEY']}",
          "Content-Type": "application/json",
      },
  )

  with urlopen(request) as response, open("effect.mp3", "wb") as file:
      file.write(response.read())
  ```

  ```javascript Node.js theme={null}
  import { writeFile } from "node:fs/promises";

  const response = await fetch("https://api.snapgen.org/v1/audio/sound-effects", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SNAPGEN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "eleven-sound-effects-v2",
      prompt: "Heavy wooden door creaking open in an empty hall",
      duration_seconds: 4,
    }),
  });
  if (!response.ok) throw new Error(await response.text());
  await writeFile("effect.mp3", Buffer.from(await response.arrayBuffer()));
  ```
</RequestExample>

<ResponseExample>
  ```text 200 theme={null}
  HTTP/1.1 200 OK
  content-type: audio/mpeg
  cache-control: no-store
  x-gateway-execution-id: 5b1e9f3a-2c4d-4e6f-8a7b-9c0d1e2f3a4b

  <binary MP3 audio>
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "duration_seconds: Too big: expected number to be <=30",
      "type": "invalid_request_error",
      "param": null,
      "code": "invalid_request"
    }
  }
  ```
</ResponseExample>