Search Sound Effects

POST

https://api.audioscape.ai/developer/v1/sfx/search

On this pageEndpoint

▼

Endpoint
Headers
Request Body
Response
Search Features
Example
Errors

Endpoint

Search the sound effects catalog using natural language. Describe what you need — "metal door slam", "footsteps on gravel", "laser blast" — and the API returns the most relevant clips. You can also browse by category without a query: pass filters.categories or filters.subcategories and the API picks a curated query for you. Fetch the full category hierarchy from /v1/sfx/taxonomy to power browse UIs.

Headers

Name	Type	Description
x-api-key	required	Your API key
Content-Type	required	Must be `application/json`

Request Body

Provide a query or filters.categories.

Parameter	Type	Description
query	string conditional	Free-text description of the sound. Optional if `filters.categories` is provided.
limit	number optional	Maximum results to return (default: 20, max: 100)
offset	number optional	Pagination offset (default: 0)
filters	object optional	Narrow your results: `categories`—Array of UCS-style category codes (e.g. `"WEAPON-FIRE"`, `"FOOTSTEP"`). Fetch the full list from /v1/sfx/taxonomy. `subcategories`—Array of UCS subcategories for finer-grained filtering. `duration`—Object with `min` and `max` in seconds (default: 0–400) `min_likes`—Minimum lifetime like count on Roblox (number) `created_after`—Earliest asset creation date — `YYYY-MM-DD`

Response

Returns matching SFX clips along with grouped category and subcategory facets.

response.json

{
  "tracks": [
    {
      "asset_id": number,
      "name": "string",
      "description": "string",
      "category": "string",
      "subcategory": "string",
      "tags": "string",
      "duration": number,
      "score": number,
      "created_at": "string",
      "updated_at": "string",
      "creator_id": number | null,
      "creator_name": "string"
    }
  ],
  "categories": [
    { "name": "string", "track_count": number }
  ],
  "subcategories": [
    { "name": "string", "category": "string", "track_count": number }
  ],
  "meta": {
    "total": number,
    "limit": number,
    "offset": number,
    "search_method": "semantic" | "text" | "hybrid" | "browse",
    "synthesized_query": "string" | null
  }
}

Search Features

Natural Language

Default

Describe the sound in plain language — "wooden footsteps on creaky floor", "sci-fi door whoosh", "menu select beep" — and get acoustically relevant results powered by CLAP embeddings.

Browse by Category

Skip the query entirely and pass filters.categories or filters.subcategories. The API picks a curated query so you get strong results without needing to know the right search terms. Check meta.synthesized_query to see what was used. Use /v1/sfx/taxonomy to fetch the full category list for browse UIs.

Keyword Fallback

If semantic search is unavailable, the API automatically falls back to keyword matching so you always get results. Check meta.search_method to see which method was used.

Example Request

Build a variety pool: fetch a batch of short impact sounds at load time, then pick one at random per swing for natural-feeling repetition. Assumes a client from the Quickstart.

Luau (Roblox)

-- Pre-fetch a pool of impact sounds at load, randomize per swing
local result, err = client:sfxSearch({
    query = "metal sword impact short",
    limit = 10,
    filters = { duration = { min = 0, max = 1 } },
})
if not result then warn(err) return end

local impactIds = {}
for _, sfx in result.tracks do
    table.insert(impactIds, sfx.asset_id)
end

local function playRandomImpact(parent)
    local sound = Instance.new("Sound")
    sound.SoundId = "rbxassetid://" .. impactIds[math.random(#impactIds)]
    sound.Parent = parent
    sound:Play()
end

When you already know the category — gun fire, footsteps, UI clicks — skip the query entirely. The API curates the pool for you.

Luau (Roblox)

-- Same shape, but pull straight from a category — skip the query
local result, err = client:sfxSearch({
    limit = 10,
    filters = {
        categories = { "WEAPON-FIRE" },
        duration = { min = 0, max = 1 },
    },
})
if not result then warn(err) return end

local fireIds = {}
for _, sfx in result.tracks do
    table.insert(fireIds, sfx.asset_id)
end

Error Responses

400Bad Request

Missing both query and filters.categories.

400.json

{
  "error": "query or filters.categories is required"
}

401Unauthorized

Invalid or missing API key.

401.json

{
  "error": "Invalid API key"
}

429Too Many Requests

You've exceeded your rate limit. See your current tier on the API Keys page.

429.json

{
  "message": "Too Many Requests"
}

500Internal Server Error

Something went wrong on our end. Try again or contact support if the issue persists.

Ready to get started?

Create your API key and start building with AudioScape today.

Get Your API Key