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

# Audio Sound Effects

> Generate non-speech audio from a text prompt. Synchronous, flat per-generation pricing.

Synchronous endpoint. Describe a sound — door slam, rain, sword unsheathing, ambient room — get back a clip. Pairs naturally with [`/v1/audio/music`](/api-reference/audio-music) for video and game soundtracking.

```bash theme={null}
curl -X POST https://kymaapi.com/v1/audio/sfx \
  -H "Authorization: Bearer $KYMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "heavy wooden door slamming shut in stone hallway, with reverb",
    "duration_seconds": 3
  }' \
  --output door.mp3
```

## Request

`application/json` body.

<ParamField body="model" type="string" default="elevenlabs-sfx">
  SFX model. Currently only `elevenlabs-sfx` is shipped.
</ParamField>

<ParamField body="prompt" type="string" required>
  Description of the sound. Max 500 characters. Also accepts `text` as an alias.
</ParamField>

<ParamField body="duration_seconds" type="number">
  Optional duration `0.5` to `22` seconds. Omit to let the model auto-pick a sensible length.
</ParamField>

<ParamField body="prompt_influence" type="number" default="0.3">
  How literal the prompt should be (0 = creative, 1 = strict). Range `0`–`1`.
</ParamField>

<ParamField body="response_format" type="string" default="mp3_44100_128">
  Audio format. Same options as [audio/speech](/api-reference/audio-speech#request).
</ParamField>

<ParamField query="save_to_blob" type="string">
  Optional query param. Set to `1` to have Kyma upload the resulting MP3 to Vercel Blob, write a `multimodal_jobs` row, and return JSON `{ job_id, kind: "audio", url, duration_sec, cost_usd, balance_usd }` instead of streaming bytes. Used by [Canvas](/guides/canvas) and [Muse](/guides/muse) audio kinds — most direct API callers don't need this.
</ParamField>

## Response

### Default (streaming)

`200 OK` with audio bytes. Flat pricing — duration doesn't change the cost.

| Header               | What                         |
| -------------------- | ---------------------------- |
| `X-Kyma-Model`       | `elevenlabs-sfx`             |
| `X-Kyma-Cost-USD`    | flat `$0.027` per generation |
| `X-Kyma-Balance-USD` | remaining balance            |

### With `?save_to_blob=1`

`200 OK` with JSON:

```json theme={null}
{
  "object": "audio.generation",
  "job_id": "mmj_...",
  "kind": "audio",
  "model": "elevenlabs-sfx",
  "url": "https://blob.vercel-storage.com/mmj/.../mmj_....mp3",
  "duration_sec": 3,
  "cost_usd": 0.027,
  "balance_usd": 47.97
}
```

## Errors

| Status | `error.code`       | When                                   |
| ------ | ------------------ | -------------------------------------- |
| `400`  | `not_an_sfx_model` | `model` is not an SFX SKU              |
| `400`  | `prompt_too_long`  | prompt > 500 chars                     |
| `400`  | `invalid_duration` | `duration_seconds` outside `[0.5, 22]` |
| `401`  | `auth_error`       | missing or invalid API key             |
| `402`  | `billing_error`    | balance too low                        |
| `502`  | `provider_error`   | upstream provider failure              |

## See also

* [`POST /v1/audio/music`](/api-reference/audio-music) — full music tracks
* [`POST /v1/audio/speech`](/api-reference/audio-speech) — voice narration