Music Library

Search Kolbo's catalog of licensed stock / production music and resolve downloadable track URLs.

Deprecated — still works. The /v1/music-library/* endpoints are now thin adapters over the unified Stock Library. For new integrations, use GET /api/v1/stock/search with mediaType=music instead — it adds semantic "vibe" search over Kolbo's own AI music catalog (kolbo-ai) plus Coverr, and GET /api/v1/stock/asset/:source/:id resolves downloads. Notable adapter changes: track id values are now composite "source:sourceId" strings, and the stems / lyrics endpoints return an empty result with guidance (the unified catalog does not expose stems or lyrics). These routes will not be removed without a major-version deprecation cycle.

The Music Library is Kolbo's catalog of licensed, ready-made background tracks. Use it to score a video, ad, or voiceover with an existing track.

Library vs generation. These endpoints find an existing track and are free (no credits). To compose a brand-new, original song, use music generation instead.

All endpoints are read-only and authenticated with your X-API-Key.

Search

Relevance search over the catalog with optional filters and sort.

Endpoint

POST /api/v1/music-library/search

Body Parameters

Parameter	Type	Description
`query`	string	Keyword search, e.g. `"uplifting corporate"`. Max 200 chars. Falls back to `mood`/`genre` when omitted.
`mood`	string	Mood filter (e.g. `"Energetic"`). See Facets for valid values.
`genre`	string	Genre filter (e.g. `"Soundtrack"`). See Facets.
`bpmMin` / `bpmMax`	number	Beats-per-minute range.
`durationMin` / `durationMax`	number	Track duration range, in seconds.
`hasStems`	boolean	Only tracks with separated stems.
`hasLyrics`	boolean	Only tracks with lyrics.
`sort`	string	`duration-asc`, `duration-desc`, `bpm-asc`, `bpm-desc`, or `title`. Omit for relevance order.
`limit`	number	Results per page (max 40, default 20).
`offset`	number	Pagination offset.

Example

curl -X POST https://api.kolbo.ai/api/v1/music-library/search \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "query": "uplifting corporate", "genre": "Corporate", "durationMax": 120, "limit": 5 }'

Response

{
  "success": true,
  "tracks": [
    {
      "id": "12345",
      "title": "Bright Horizons",
      "artist": "Studio Collective",
      "album": "Corporate Vol. 3",
      "durationSeconds": 118,
      "bpm": 120,
      "musicalKey": "C major",
      "genres": ["Corporate"],
      "moodTags": ["Uplifting", "Hopeful"],
      "instruments": ["Piano", "Strings"],
      "artworkUrl": "https://.../artwork.jpg",
      "audioUrl": "https://.../preview_128.mp3",
      "audioUrl128": "https://.../preview_128.mp3",
      "audioUrl320": "https://.../320.mp3",
      "audioUrlWav": "https://.../master.wav",
      "hasStems": true,
      "hasLyrics": false,
      "versionsCount": 3
    }
  ],
  "count": 5,
  "total": 0,
  "sorted": false
}

When sort is supplied the response includes sorted: true and a total reflecting the sorted pool size; pagination then slices through that pool.

Analyze Script

AI helper that turns a video or voiceover script into a music search you can feed straight into Search.

Endpoint

POST /api/v1/music-library/analyze-script

Body Parameters

Parameter	Type	Description
`script`	string	The script or scene description to analyze (up to ~8000 chars). Required.

Example

curl -X POST https://api.kolbo.ai/api/v1/music-library/analyze-script \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "script": "A founder walks through an empty office at dawn, reflecting on the journey before the team arrives." }'

Response

{
  "success": true,
  "query": "inspiring cinematic",
  "mood": "Emotional",
  "genre": "Soundtrack",
  "keywords": ["reflective", "hopeful", "piano", "build", "cinematic"]
}

Browse Catalog

Stable paginated browse with no query.

Endpoint

GET /api/v1/music-library/catalog

Query Parameters

Parameter	Type	Description
`limit`	number	Results per page (max 50, default 50).
`offset`	number	Pagination offset.
`sort`	string	Same options as Search.

curl "https://api.kolbo.ai/api/v1/music-library/catalog?limit=20&sort=bpm-desc" \
  -H "X-API-Key: kolbo_live_..."

The response shape matches Search (tracks, count, total, sorted).

Distinct genres, moods, and instruments plus the BPM and duration ranges — use these to build precise filtered searches.

Endpoint

GET /api/v1/music-library/facets

Response

{
  "success": true,
  "genres": ["Corporate", "Soundtrack", "Hip Hop", "..."],
  "moods": ["Uplifting", "Tense", "Emotional", "..."],
  "instruments": ["Piano", "Guitar", "Drums", "..."],
  "bpmRange": { "min": 60, "max": 180 },
  "durationRange": { "min": 30, "max": 360 }
}

Track Audio

Resolve the downloadable 128 kbps / 320 kbps / WAV URLs for a single track. Call this after the user picks a track.

Endpoint

GET /api/v1/music-library/track/:id/audio

curl https://api.kolbo.ai/api/v1/music-library/track/12345/audio \
  -H "X-API-Key: kolbo_live_..."

Response

{
  "success": true,
  "id": "12345",
  "urls": {
    "128": "https://.../128.mp3",
    "320": "https://.../320.mp3",
    "wav": "https://.../master.wav"
  }
}

Stems and alternate versions (instrumental, 30s cut, looped) of a master track.

Adapter note: the unified Stock Library catalog does not expose stems or alternate versions — this endpoint now returns empty stems / versions arrays with a guidance message.

Endpoint

GET /api/v1/music-library/track/:id/related

Response

{
  "success": true,
  "stems": [
    { "id": "12345-drums", "name": "Drums", "type": "stem", "audioUrl320": "https://.../drums.mp3" }
  ],
  "versions": [
    { "id": "12345-30s", "name": "30s Cut", "type": "version", "audioUrl320": "https://.../30s.mp3" }
  ]
}

Track Lyrics

Lyrics text, lyrical theme, and explicit flag for a single track.

Adapter note: the unified Stock Library catalog does not expose lyrics — this endpoint now returns hasLyrics: false with a guidance message.

Endpoint

GET /api/v1/music-library/track/:id/lyrics

Response

{
  "success": true,
  "hasLyrics": true,
  "lyrics": "Verse 1...",
  "lyricalTheme": "perseverance",
  "explicit": false
}

Typical Flow

From a script → POST /music-library/analyze-script to derive query / mood / genre.
Search → POST /music-library/search with that query plus any filters. Use the audioUrl preview to let the user listen.
Pick → GET /music-library/track/:id/audio for the final downloadable URLs (WAV for editing, 320 for delivery).
Optionally GET /music-library/track/:id/related for an instrumental or stems, or .../lyrics for vocal tracks.

Notes

All Music Library endpoints are free — they do not consume credits.
If a filtered search returns no tracks, call Facets for exact valid genre/mood values and retry.
Errors return { "success": false, "error": "...", "code": "..." }. A 503 means the music library is not configured on that environment.

On this page