Background music API for video: Sume's keyless BGM catalog

Sume's background music API is a keyless catalog of curated tracks: GET https://api.sume.com/v1/bgm/catalog lists 66 of them with an audio_url, length, tempo, energy, and license, and POST /v1/bgm/pick chooses one track for a mood or product you describe. Neither call needs a Sume API key.

The API reference lists the BGM routes as public, and their descriptions are in the Sume API reference, read on 2026-09-27. Counts and matching rules come from Sume's catalog code that day; current behavior may change. To mix a track under a voiceover, see Add background music to a video with an API.

Which BGM endpoints are there, and do they need a key?

None of them does. The docs list six /v1 routes that work without a Sume API key, and three are the background music (BGM) catalog, so a plain HTTPS request is enough. Sume curates the catalog; there is no per-user upload.

curl "https://api.sume.com/v1/bgm/categories"

curl "https://api.sume.com/v1/bgm/catalog?category=tech&energy=upbeat&limit=5"

What does each track include?

Every row in tracks[] has the same fields, and the response names the catalog version (bgm_catalog_v3 today). The API reference says existing first-party ids stay stable, so a Sume original's id is safe to store.

• id, slug, name, description, and category.
• audio_url and preview_url. In the current code both point at the same MP3 file.
• duration_seconds (30–262 seconds across the catalog), bpm (62–132), energy (calm, upbeat, dramatic, or neutral), and loopable (true for all 66 tracks).
• license, attribution, source_name, source_url, and featured, covered in the next section.
• Matching lists: moods, genres, tags, video_genres, product_categories, and locales. Tags mix English and Korean words, and 9 tracks list ko as their only locale.

Which licenses do the catalog tracks carry?

Read license on every track before you use it. The catalog uses two values:

• sume-original (48 tracks): Sume's own loops, served from https://media.sume.com/assets/bgm/. Their attribution is null and their source_name is Sume.
• cc-by-4.0 (18 tracks): third-party tracks under CC BY 4.0, linked at their author's official URLs instead of being copied to Sume. They are marked featured, and each carries an attribution string.
• For those CC BY tracks, Sume's API reference says to keep track.attribution with any public use, so store that string next to the track id.

How do I filter the catalog?

Add any of these query parameters: category, mood, genre, energy, tag, video_genre, product_category, and locale, plus limit (1–200). energy takes one of its four values. In the current code, limit defaults to 100, a track must match every filter you send, the other filters ignore case and accept partial words, and featured tracks sort first.

GET /v1/bgm/categories returns the 9 categories below, and each one also carries a Korean label in name_ko.

How does /v1/bgm/pick choose a track?

Describe the video in a context object. The API reference names mood, genre, energy, tags, product category, and user prompt as the signals it scores; the current code also scores video_genre, locale, and duration_seconds. Optional min_score and auto_expand set how strict the match is.

• Ties among the top scores break deterministically, not at random, so the same context gets the same track.
• In the current code, a strict match needs a score of at least min_score (default 6). With auto_expand on, the default, a miss first accepts any score of 3 or more, then rescores without energy if you sent one, then ignores the context and picks from the whole catalog; relaxed_filters lists energy and mood_and_tags for those last two steps.
• Besides track and score, the response carries matched_signals, relaxed_filters, candidate_count, catalog_version, and match_tier: strict, widened, or catalog_fallback when auto_expand is false and nothing reached min_score.
• A pick can return a CC BY track, so check its license first.

curl -X POST https://api.sume.com/v1/bgm/pick \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "mood": "calm",
      "energy": "calm",
      "product_category": "skincare",
      "user_prompt": "30-second product ad for a night cream"
    }
  }'

Can I use a catalog track as a Timeline soundtrack?

Only a Sume original, in the current code. Timeline 1.0 checks each media URL against the Sume media host and refuses a soundtrack.url hosted anywhere else with 400 unsupported_media_source. A sume-original track's audio_url is on media.sume.com and passes that host check; a cc-by-4.0 track's URL is on its author's site, so Timeline refuses it.

The unbilled POST /v1/timeline-1.0/plan runs the same Sume-host URL check without creating a job or reserving credits, so test the timeline there before a paid render. If no catalog track fits, generate one with the Music Router.