Similar Sound Effects

GET

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

On this pageEndpoint

▼

Endpoint
Headers
Query Parameters
Response
Example
Errors

Endpoint

Given an SFX asset ID — or a list of them — find other sound effects that sound similar. Useful for building "more like this" pickers, filling out a soundscape with related ambiences, growing a variety pack from the clips you already picked, or matching a placeholder clip to its closest neighbor in the catalog.

Headers

Name	Type	Description
x-api-key	required	Your API key

Query Parameters

Parameter	Type	Description
asset_id	string required unless asset_ids	The Roblox asset ID of the SFX to find similar clips for. Use this or `asset_ids`, not both.
asset_ids	string optional	Comma-separated list of up to 100 asset IDs (e.g. `asset_ids=123,456,789`). Results match the acoustic profile of the whole set rather than any one clip, and none of the seeds are returned. Seeds that can't be resolved (unknown, not yet analyzed, or not public) are skipped and listed in `meta.seeds_ignored`; if none resolve, the response is a 404. Order doesn't matter.
limit	number optional	Maximum results to return (default: 20, max: 100)
offset	number optional	Pagination offset (default: 0)
filters	object optional	JSON-encode the object and pass as a single querystring value (e.g. `filters={"categories":["impact"]}`). Narrow your results: `categories`—Array of UCS-style category names `subcategories`—Array of subcategories `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.
max_score	number optional	Drops results whose `score` is at or above this threshold (between `0` and `1`). Useful for filtering out near-duplicates of the seed sound — common in SFX libraries with many uploads of the same generic clip. Omit to return all results.
dedupe	boolean optional	Shortcut for filtering near-duplicates without picking a number — equivalent to a sensible default `max_score`. If both are set, `max_score` wins.

Response

Returns SFX clips that are acoustically similar to the given asset.

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.

response.json

{
  "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
    }
  ],
  "meta": {
    "total": number,
    "limit": number,
    "offset": number,

    // --- asset_ids requests only ---
    "seeds_used": number,        // seeds that resolved and were blended
    "seeds_ignored": ["string"]  // seeds skipped: unknown, not yet analyzed, or not public
  }
}

Example Request

Take one hero sound — say, the footstep you already love — and fan it out into a variety pack of similar clips so repeated plays don't feel mechanical. Assumes a client from the Quickstart.

Luau (Roblox)

-- Build a footstep variety pack from one hero sound
local HERO_FOOTSTEP_ID = "9120386436"

local result, err = AudioScape:sfxSimilar({
    asset_id = HERO_FOOTSTEP_ID,
    limit = 5,
})
if not result then warn(err) return end

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

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

-- Grow the pack from the clips you already picked: pass the list as the seed
-- (SDK 0.22.0+, or asset_ids over HTTP) and results match the set as a whole.
local more = AudioScape:sfxSimilar(footsteps, { limit = 5, dedupe = true })

Error Responses

400Bad Request

Missing or invalid asset ID, both asset_id and asset_ids given, or more than 100 asset_ids.

400.json

{
  "error": "asset_id is required and must be a numeric string"
}

401Unauthorized

Invalid or missing API key.

401.json

{
  "error": "Invalid API key"
}

404Not Found

The given asset ID is not in our SFX catalog — or, for asset_ids, none of the given IDs resolved (asset_ids not found).

404.json

{
  "error": "asset_id not found"
}

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