> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budgetpixel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Stock Sound Effects
> Search BudgetPixel's free sound effect library from your code or AI agent — reviewed, AI-generated whooshes, impacts, UI sounds, Foley and ambiences under CC BY 4.0. Available on every plan, including Free.
The stock sound effect search gives programmatic access to the sounds at
[budgetpixel.com/sfx](https://budgetpixel.com/sfx): AI-generated whooshes, impacts, UI
sounds, Foley, ambiences, animals, vehicles and more. Every sound is listened to and scored
before it is listed. Each result comes with the audio file, its length and a ready-made
credit line.
```
GET https://api.budgetpixel.com/v1/stock/sound-effects
```
Available on **every plan, including Free**. The stock searches ([images](/stock-images),
sound effects and [music](/stock-music)) are the only endpoints a Free plan's API key can
call. Everything else in the API, and generation through the MCP connector, needs a paid
plan.
## Pricing
* **10 credits per search**, from your plan's credits.
* A search is charged when it succeeds, **including one that matches nothing**.
* Invalid parameters are refused with a `400` and cost nothing.
* Searches count toward the monthly spend limit you can set under
[Billing](https://budgetpixel.com/developers?tab=billing).
The endpoint searches existing sounds only; it never generates one. To make a new sound,
use the [sound effect generation endpoints](/concepts/models) (paid plans).
## Licence and credit
Every sound is licensed [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): you can
use it commercially, edit it, and use it in client work, provided you credit it where it
is used. Each result includes the credit line, so you don't have to compose one:
* `attribution.text`, for video descriptions, credits, show notes and README files.
* `attribution.html`, for web pages. It links the sound, BudgetPixel and the licence.
## Search
```bash curl theme={null}
curl "https://api.budgetpixel.com/v1/stock/sound-effects?query=door+creak&max_duration=3&limit=5" \
-H "Authorization: Bearer $BUDGETPIXEL_API_KEY"
```
```python Python theme={null}
import os, requests
r = requests.get(
"https://api.budgetpixel.com/v1/stock/sound-effects",
headers={"Authorization": f"Bearer {os.environ['BUDGETPIXEL_API_KEY']}"},
params={"query": "door creak", "max_duration": 3, "limit": 5},
timeout=30,
)
r.raise_for_status()
for sound in r.json()["data"]:
print(sound["title"], sound["duration_seconds"], sound["urls"]["original"])
print(" credit:", sound["attribution"]["text"])
```
```javascript Node.js theme={null}
const params = new URLSearchParams({ query: "door creak", max_duration: "3", limit: "5" });
const res = await fetch(`https://api.budgetpixel.com/v1/stock/sound-effects?${params}`, {
headers: { Authorization: `Bearer ${process.env.BUDGETPIXEL_API_KEY}` },
});
const { data } = await res.json();
for (const sound of data) console.log(sound.title, sound.urls.original, sound.attribution.text);
```
### Parameters
All parameters are optional. Send a `query`, a `category`, or both.
| Parameter | Values | What it does |
| - | - | - |
| `query` | Up to 200 characters | The sound, in a few plain words. |
| `category` | `transition`, `impact`, `stinger`, `ui`, `game`, `human`, `animals`, `vehicles`, `household`, `nature`, `ambience`, `foley` | Limit results to one category. |
| `min_duration` | Seconds, above 0 | Shortest clip to return. |
| `max_duration` | Seconds, above 0 | Longest clip to return. Use `1` for one-shots. |
| `sort` | `popular` (default), `newest`, `top` | With a query, `popular` puts the best matches first. `top` is highest rated. |
| `limit` | 1–20, default 20 | Results per page. The price is the same for any limit. |
| `offset` | 0–5000, default 0 | Results to skip. Fetch the next page with `offset + limit`; each page is a new search. |
### How the search matches
Write the query the way you would name the sound: `door creak`, `soft notification chime`,
`rain on a tin roof`.
* **Every word counts.** A result must carry most of what you asked for. Filler words
(`the`, `of`, `sound effect`) are ignored.
* **Rare words weigh more.** In `casino ambience`, `casino` decides the results.
* **Word forms match.** `ticking` finds `tick`, `chimes` finds `chime`.
* **A word the library does not have counts as a miss.** `flamethrower burst` returns
nothing when there is no flamethrower, rather than every burst.
* **Results that match more of your words come first**, then the more popular.
A long description, such as a prompt written for a generator, returns the sounds it names
or nothing. It does not return sounds that only share its adjectives. A few words work
better, and when nothing fits you can generate the sound instead.
### Response
```json theme={null}
{
"object": "list",
"data": [
{
"id": "1a613c5d-3b41-4546-acd7-721874cb96e6",
"type": "sound_effect",
"title": "Horror Door Creak",
"tags": ["creaky", "squeaky", "high-pitched", "horror", "door"],
"keywords": ["creaky door opening", "horror door squeak", "slow door creak", "old door opening sound", "spooky door squeak"],
"category": "household",
"duration_seconds": 2.566,
"format": "mp3",
"sample_rate": 44100,
"channels": 2,
"size_bytes": 52811,
"page_url": "https://budgetpixel.com/sfx/horror-door-creak-1a613c5d",
"urls": {
"original": "https://cdn.budgetpixel.com/audio-library/sfx/creaky-squeaky-highpitched-horror-door-1bnq7lk.mp3",
"cover": "https://cdn.budgetpixel.com/audio-library/art/1a613c5d-3b41-4546-acd7-721874cb96e6.webp"
},
"license": { "code": "CC-BY-4.0", "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" },
"attribution": {
"required": true,
"text": "“Horror Door Creak” by BudgetPixel AI (https://budgetpixel.com/sfx/horror-door-creak-1a613c5d) — CC BY 4.0",
"html": "Horror Door Creak by BudgetPixel AI, CC BY 4.0"
},
"ai_generated": true,
"model": "sonilo-sfx",
"prompt": "door creaking open slowly, horror squeak",
"downloads": 38,
"quality_score": 9.5,
"created_at": "2026-08-24T06:51:14Z"
}
],
"total": 11,
"limit": 5,
"offset": 0,
"has_more": true,
"credits_charged": 10
}
```
The example shows the first of the five results. `urls.original` is the audio file and `format` says whether it is WAV or MP3. Most sounds
are WAV; the earliest are MP3. `urls.cover` is square cover art, present for most sounds.
## From an AI agent (MCP)
The [MCP connector](/mcp-server) has the same search as the `search_stock_audio` tool
(with `kind` set to `sound_effect`). Sign in once, with no API key, and ask in plain words:
* *"Find a free door creak sound effect under three seconds, and give me the credit line"*
* *"I need a soft whoosh for a scene transition"*
The tool costs the same 10 credits per search and works on every plan, including Free.
## Errors
| Status | `code` | Meaning |
| - | - | - |
| 400 | `invalid_parameter` | A parameter is out of range or not an allowed value. The message lists the allowed values. Not charged. |
| 401 | `missing_api_key` / `invalid_api_key` | No key, or an unknown or revoked key. |
| 402 | `insufficient_credits` | Your balance is under 10 credits. [Get more credits](https://budgetpixel.com/pricing). |
| 429 | `rate_limited` | More than 60 sound effect and music searches a minute on the account, or the general [rate limits](/concepts/rate-limits). |
| 429 | `monthly_spend_limit_reached` | The monthly spend limit you set has been reached. |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.