AssetService:SearchAudioAsyncRead the docs →Search Sound Effects
POSThttps://api.audioscape.ai/developer/v1/sfx/searchOn this pageEndpoint▼
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, filters.categories or asset_ids.
| Parameter | Type | Description |
|---|---|---|
| query | string conditional | Free-text description of the sound. Optional if filters.categories or asset_ids is provided. Special shapes: a single numeric string is treated as an asset ID lookup; a comma-delimited list of numeric IDs (e.g. "123,456,789") is treated as a batch lookup. See Asset ID Lookup below. |
| asset_ids | string[] optional | Explicit batch ID lookup. Array of numeric strings, max 100 per call. When present, takes priority over query and bypasses all filters. Returns matching sounds in input order; IDs that don't exist (or are deleted, delisted, moderated, non-public, or not sound effects) appear in meta.missing_ids. |
| 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/or max in seconds (a missing bound defaults to 0 / 400). When set, assets with unknown duration are excluded; omit to skip duration filtering entirely.min_likes—Minimum lifetime like count on Roblox (number)created_after—Earliest asset creation date — YYYY-MM-DDexclude_voices—Boolean. Drops assets flagged with speech or sung vocals. The flags are conservative: treat this as a coarse first pass and check descriptions when a strict voice-free result is required. |
Response
Returns matching SFX clips along with grouped category and subcategory facets.
Each clip also carries additive optional MIR fields that may be null: true_peak_dbtp for level-matching (short clips have no reliable LUFS), plus sound_start_sec and sound_end_sec, the audible-sound boundaries you can use to trim leading and trailing silence.
{
"tracks": [
{
"asset_id": number,
"name": "string",
"description": "string",
"category": "string",
"subcategory": "string",
"tags": "string",
"duration": number | null,
"score": number,
"created_at": "string",
"updated_at": "string",
"creator_id": number | null,
"creator_name": "string",
// --- MIR fields (all optional, may be null) ---
"true_peak_dbtp": number, // true peak in dBTP; use for level-matching (short clips have no reliable LUFS)
"sound_start_sec": number, // audible-sound start — trim leading silence
"sound_end_sec": number, // audible-sound end — trim trailing silence
// --- Voice flags (optional, may be null when not yet enriched) ---
"has_speech": boolean, // spoken voice detected; conservative — may miss faint background walla
"has_vocals": boolean // sung vocals detected; same caveat
}
],
"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" | "id" | "ids-batch",
"synthesized_query": "string" | null,
"missing_ids": ["string"] // ID-lookup mode only, omitted when empty
}
}Search Features
Natural Language
DefaultDescribe 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.
Asset ID Lookup
When you already know the asset IDs (refreshing metadata for sounds a game already uses, rebuilding a saved list), skip the scoring pipeline with a direct lookup. Three input shapes work:
- Single ID via
query: "12345"— returns the sound if found, otherwise falls through to text search - Comma-delimited list via
query: "123,456,789"— batch lookup - Explicit array via
asset_ids: ["123","456"]— batch lookup, no fall-through
Up to 100 IDs per call. Filters and sort don't apply. Returned sounds keep input order, with the same fields as search results and a score of 1. IDs not found (deleted, delisted, moderated, non-public, never existed, or a music track) are listed in meta.missing_ids. meta.search_method is "id" for one ID, "ids-batch" for several. For music IDs, use the same lookup on /v1/search.
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.
-- Pre-fetch a pool of impact sounds at load, randomize per swing
local result, err = AudioScape: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()
endWhen you already know the category — gun fire, footsteps, UI clicks — skip the query entirely. The API curates the pool for you.
-- Same shape, but pull straight from a category — skip the query
local result, err = AudioScape: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)
endWhen you already have the asset IDs, look them up directly. Over HTTP, send asset_ids; through the SDK, pass the IDs as a comma-delimited query.
-- Fetch metadata for sounds you already know (up to 100 IDs)
local result, err = AudioScape:sfxSearch({
query = "9120533892,79323024570181",
})
if not result then warn(err) return end
for _, sfx in result.tracks do
print(sfx.asset_id, sfx.name, sfx.duration, sfx.category)
end
-- IDs that aren't public sound effects come back in result.meta.missing_idsError Responses
Missing query, filters.categories and asset_ids, or asset_ids that is empty, has non-numeric entries, or lists more than 100 IDs.
{
"error": "query, filters.categories or asset_ids is required"
}Invalid or missing API key.
{
"error": "Invalid API key"
}You've exceeded your rate limit. See your current tier on the API Keys page.
{
"message": "Too Many Requests"
}Something went wrong on our end. Try again or contact support if the issue persists.