> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Background music

> Search HeyGen's background-music catalog with natural language and get ready-to-use, pre-signed audio URLs for your videos via the HeyGen API.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-5.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=422da140ece4b799d490f85bb2013ca5)

Find background music by describing the vibe you want ("upbeat lofi hip-hop", "tense cinematic riser", "subtle ambient corporate") and get back ranked tracks, each with a pre-signed download URL. Search is semantic, not keyword-based, so plain-language descriptions work best.

## Search the Catalog

Send a `GET` request to `/v3/audio/sounds` with a natural-language `query`:

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/audio/sounds?query=upbeat%20corporate%20background%20music&limit=3" \
  -H "x-api-key: YOUR_API_KEY"
```

Each result in `data` has an `id`, `name`, `description`, `audio_url` (a pre-signed WAV link), `duration` in seconds, and a `score` (0–1 semantic similarity), returned highest-first with `type` `music`. The [reference](https://heygen-1fa696a7.mintlify.site/reference/search-audio-music-or-sound-effects.md) has the full schema.

Parameters worth tuning:

* `limit`: 1–50 results per page (default `10`).
* `min_score`: minimum similarity, default `0.7`. Tracks scoring below it are omitted, so raise it for tighter matches and lower it to widen the net.
* `type`: `music` (the default) searches the background-music catalog; `sound_effects` searches [sound effects](https://heygen-1fa696a7.mintlify.site/sound-effects.md).
* `token`: when `has_more` is `true`, pass the returned `next_token` as `token` to fetch the next page.

> [!NOTE]
>
> Each `audio_url` is a pre-signed link with a limited lifetime. Download the file (or hand the URL to a downstream step) soon after searching rather than caching it for later.

> [!TIP]
>
> Searching from an AI agent instead of code? The same catalog is available through the [HeyGen MCP](https://heygen-1fa696a7.mintlify.site/mcp/overview.md) via the `search_audio_sounds` tool.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.