Music Library

The Music Library is Kolbo's licensed production-music catalog. Use it to score a video, ad, or voiceover with an existing, rights-cleared track.

Every endpoint is authenticated with your X-API-Key.

Library vs generation. These endpoints find an existing track. To compose a brand-new original song, use music generation instead.

Rate limits

Requests that fail (4xx / 5xx) do not count against these limits. Separately, clean acquisitions count toward a daily ceiling of 300 music / sound-effect downloads per user (resets at midnight server time); past it the paid routes return 429 STOCK_AUDIO_DAILY_LIMIT.

Search

Relevance search over the catalog with optional filters and sort.

Endpoint

POST /api/v1/music-library/search

Request Body

Examples

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 (ASCAP)",
      "artistName": "Studio Collective",
      "artistId": "778",
      "artists": [{ "id": "778", "name": "Studio Collective", "role": "primary" }],
      "primaryArtist": { "id": "778", "name": "Studio Collective" },
      "album": "Corporate Vol. 3",
      "albumId": "91",
      "albumCode": "CORP3",
      "durationSeconds": 118,
      "bpm": 120,
      "musicalKey": "C major",
      "genre": "Corporate",
      "genres": ["Corporate"],
      "moodTags": ["Uplifting", "Hopeful"],
      "instruments": ["Piano", "Strings"],
      "tags": ["build", "positive"],
      "artworkUrl": "https://.../artwork.jpg",
      "audioUrl": "https://.../audio_128.mp3",
      "audioUrl128": "https://.../audio_128.mp3",
      "audioUrl320": "https://.../320.mp3",
      "audioUrlWav": "https://.../master.wav",
      "previewAudioUrl": "https://.../audio_128.mp3",
      "previewDownloadUrl": "https://.../download.mp3",
      "hqAvailable": true,
      "watermarked": false,
      "watermarkedUrl": "https://.../watermarked_128.mp3",
      "cleanAccess": true,
      "hasStems": true,
      "hasLyrics": false,
      "versionsCount": 3,
      "links": null
    }
  ],
  "count": 5,
  "total": 87,
  "sorted": false,
  "hasMore": true,
  "cleanAccess": true,
  "cleanTrackCredits": 50
}

The example above is the subscriber view. Top-level cleanAccess says whether the caller gets clean audio across the board; top-level cleanTrackCredits is the current per-track purchase price in Kolbo credits — returned as the price even to subscribers, who are never charged it. For a caller without clean access each track instead carries watermarked: true, cleanAccess: false, the watermarked URL in audioUrl / audioUrl128 / previewAudioUrl, null in audioUrl320 / audioUrlWav / previewDownloadUrl, and its own cleanTrackCredits. A track that caller has already bought comes back ungated with cleanTrackOwned: true and cleanTrackCredits: 0. hqAvailable is always truthful (a 320 / WAV master exists), even when those URLs are withheld. watermarkedUrl is a permanent public URL, and is null for the minority of masters whose watermarked file has not been rendered — for a non-subscriber such a track has no playable preview at all.

count is the number of tracks in this page, total the size of the whole result set, and hasMore whether another page exists (all three as described on the indexed path — see the callout below for the live fallback). sorted is true only when you passed a recognized sort value.

The per-track watermarked flag tells you whether the URLs on that track are a watermarked preview or already clean — read it rather than assuming. Regardless of its value, a licensed final use should go through Acquire Clean Track or Import, which return a file explicitly stamped watermarked: false and record the licence (and, for a non-subscriber, are where the track is bought).

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

Request Body

Examples

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"]
}

The model is asked for a 1–3 word query and single-word mood / genre; what is enforced is the clipping — query to 80 chars, mood and genre to 40 chars each (either can come back ""), and keywords to at most 5 tags of 40 chars. When the model returns no query, the first keyword is used; if there is neither you get 422 with code MUSIC_LIBRARY_SCRIPT_EMPTY.

Browse Catalog

Stable paginated browse with no query.

Endpoint

GET /api/v1/music-library/catalog

Query Parameters

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

Returns { success, tracks, count, total, sorted, cleanAccess, cleanTrackCredits } with the same track shape and gating as Search. There is no hasMore here — page until offset + count reaches total, or (when total is absent) until count comes back smaller than limit. total is omitted on the unsorted live fallback (when the local catalog mirror is not ready) — treat a missing total as "unknown", not zero.

Facets

Distinct genres, moods, and instruments plus the BPM and duration ranges — use these to build precise filtered searches. Cached server-side for 10 minutes.

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 }
}

bpmRange and durationRange are null when the catalog does not report them.

Track Audio

Re-resolve the playable URLs for a single track. Call this instead of caching URLs from a search response.

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",
  "previewAudioUrl": "https://.../128.mp3",
  "previewDownloadUrl": "https://.../download.mp3",
  "watermarked": false,
  "watermarkedUrl": "https://.../watermarked_128.mp3",
  "cleanAccess": true,
  "urls": {
    "128": "https://.../128.mp3",
    "320": "https://.../320.mp3",
    "wav": "https://.../master.wav"
  }
}

urls["320"] and urls.wav are null when the catalog does not expose that variant for the track (hqAvailable on the search result tells you in advance whether a WAV exists). These URLs are signed and short-lived.

For a caller without clean access the same gate as Search applies: previewAudioUrl and urls["128"] carry the watermarked URL, previewDownloadUrl, urls["320"] and urls.wav are null, watermarked: true, cleanAccess: false, and cleanTrackCredits gives the purchase price. A track the caller already bought is returned clean with cleanTrackOwned: true and cleanTrackCredits: 0.

Track Related

Stems and alternate versions (instrumental, cutdown, minus-mix) of a master track.

Endpoint

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

Accepts the same optional projectId query parameter as Track Audio.

Response

{
  "success": true,
  "stems": [
    {
      "id": "12345-drums",
      "name": "Drums",
      "variantLabel": "Drums",
      "type": "stem",
      "element": "drums",
      "stemRef": "stem_ab12cd",
      "audioUrl": "https://.../drums.mp3",
      "downloadUrl": "https://.../drums-download.mp3",
      "watermarked": false,
      "audioUrl128": "https://.../drums_128.mp3",
      "audioUrl320": "https://.../drums_320.mp3",
      "audioUrlWav": null
    }
  ],
  "versions": [
    { "id": "12345-30s", "name": "30s Cut", "type": "cutdown", "stemRef": null, "audioUrl": "https://.../30s.mp3" }
  ],
  "cleanAccess": true,
  "cleanTrackOwned": false
}

Stems and versions have no watermarked variant, so they are subscriber-or-owner content: for a caller without clean access every row keeps its metadata (name, type, element, stemRef) but audioUrl, downloadUrl, audioUrl128, audioUrl320 and audioUrlWav are all null, with watermarked: true and cleanAccess: false. Buying the master track unlocks its stems too — top-level cleanAccess is then true and cleanTrackOwned is true (it is false for subscribers, who never needed to buy).

type is one of stem, cutdown, minus_mix, alternative. Pass a row's stemRef as the stem field of Acquire Clean Track to buy a clean version of that stem instead of the master.

Track Lyrics

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

Endpoint

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

Response

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

lyrics and lyricalTheme are null when the track has none.

Acquire Clean Track

Resolve a clean, unwatermarked MP3 or WAV master (or a single stem) for final use — download or editing-timeline use. Free for subscribers and for a track you already own; otherwise this call buys the track for cleanTrackCredits Kolbo credits.

Endpoint

POST /api/v1/music-library/clean/:trackId

Request Body

termsVersion / termsAccepted are not read from the request — the terms version and acceptance timestamp are stamped server-side.

Examples

curl -X POST https://api.kolbo.ai/api/v1/music-library/clean/12345 \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "format": "wav", "purpose": "timeline", "requestId": "score-hero-cut-01" }'

Response

{
  "success": true,
  "trackId": "12345",
  "format": "wav",
  "kind": "master",
  "audioUrl": "https://.../clean.wav",
  "downloadUrl": "https://.../clean-download.wav",
  "watermarked": false,
  "creditsRemaining": null,
  "purchasedCredits": 50
}

kind is master or stem. purchasedCredits is present only when this call bought the track (the Kolbo credits charged); it is absent for subscribers and already-owned tracks. creditsRemaining is the vendor's remaining licence allowance (usually null), not your Kolbo credit balance. reused: true is added only when the call replayed a still-valid cached result for the same requestId; the field is absent on a fresh acquisition. The returned URLs are signed and expire — download promptly. Once the cached result has expired, the same requestId returns 409 SYNCI_CLEAN_REQUEST_USED; re-acquire with a new requestId (free, since the track is now owned or covered by your subscription).

Import Track to Media Library

Acquire one clean file and copy it into your media library as project-scoped stock audio, on a stable Kolbo CDN URL. Same entitlement and purchase rules as Acquire Clean Track, plus the CDN copy. purpose and stem are not accepted here — import always lands the master.

Endpoint

POST /api/v1/music-library/import

Request Body

Examples

curl -X POST https://api.kolbo.ai/api/v1/music-library/import \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "trackId": "12345", "format": "mp3", "requestId": "import-12345-01" }'

Response

{
  "success": true,
  "libraryItem": {
    "_id": "...",
    "mediaType": "audio",
    "url": "https://media.kolbo.ai/kolboai-media/stock-imports/music/...",
    "filename": "...mp3"
  },
  "alreadyImported": false,
  "format": "mp3",
  "creditsRemaining": null
}

The import response does not carry purchasedCredits; for a non-subscriber the purchase is still charged (once per track) exactly as on the clean route. The charge is taken when the clean file resolves, before the CDN copy — if the copy then fails (SYNCI_LIBRARY_FAILED), the track is already owned and a retry is not charged again.

The created item is sourceType: "stock" with metadata.stockSource: "music", so it shows up alongside other stock imports in the Media Library.

Typical Flow

1. From a script → POST /music-library/analyze-script to derive query / mood / genre.
2. Search → POST /music-library/search with that query plus filters from Facets. Play previewAudioUrl for the user.
3. Inspect → GET /music-library/track/:id/related for stems and cutdowns, .../lyrics for vocal tracks.
4. Commit → POST /music-library/import (with your own requestId) to land a clean file on Kolbo's CDN, or POST /music-library/clean/:trackId when you only need a short-lived download URL.

Errors

All errors return { "success": false, "error": "...", "code": "..." }. On the two paid routes error is a fixed, generic message per code (unlisted codes read "Music library action failed.") — branch on code and the HTTP status, not on the text.

Related