Stock Library

The Stock Library is Kolbo's unified, multi-source catalog of ready-made media — photos, videos, illustrations, vectors, 3D models, music, and sound effects — aggregated behind one search. Use it to find b-roll, references, or project assets.

Library vs generation. These endpoints find existing assets. Searching, browsing and importing are free (no credits), with one exception: paid audio (Kolbo AI music and sound effects, Coverr music) costs credits to import unless you have a subscription or already own the track. To create new content, use image generation or video generation.

License. Your use of any asset is governed by the Asset Library License & Terms of Use. In short: Kolbo's own AI-generated music and sound effects are licensed for commercial use; third-party licensed assets (photos, videos, vectors, 3D) may be used only as original footage — not fed into AI generation/editing tools, and not used for AI training.

Sources today: Kolbo AI (kolbo-ai — our own AI-generated sound effects, music, and images), Pexels (photos, videos), Unsplash (photos), Pixabay (photos, illustrations, vectors, videos), Coverr (videos, music), Sketchfab (3D models), and Freesound (sound effects). Every route requires your X-API-Key.

Attribution. Every asset carries author, providerUrl, license, and a ready-to-render attribution string. When you display results you must credit the provider and the creator per their license.

Paid audio

Three catalogs are paywalled: Kolbo AI music (source=kolbo-ai, mediaType=music), Kolbo AI sound effects (kolbo-ai / sfx), and Coverr music (coverr / music). Every other source and media type — including Freesound SFX and all photos, videos, vectors and 3D — is free.

• Subscribers get these tracks free and see every asset untouched.
• Everyone else buys a track once and then owns it: every later import of that same track is free. The price comes from the live catalog — read it from meta.priceCredits rather than hardcoding it.
• On Search and Asset, a paywalled asset you do not own comes back with meta.owned: false, meta.priceCredits set, downloadVariants: [], any meta.stems removed, and previewUrl swapped to a watermarked render when one exists. An owned track has meta.owned: true and meta.priceCredits: 0 and keeps its variants.
• The charge happens on Import, and only after the file has been copied successfully. Whether an import is paid is decided from the asset the id resolves to, not from the mediaType you send. Insufficient credits → 402 STOCK_MUSIC_INSUFFICIENT_CREDITS.
• Daily ceiling. A paid-audio import is refused once you have 300 audio downloads logged that day — every stock music and SFX download or import from any source (free Freesound clips and in-app downloads included) plus licensed Music Library acquisitions count toward it. It binds subscribers too. Past it, a paid-audio import returns 429 STOCK_AUDIO_DAILY_LIMIT until midnight (server time).
• Shared-credit projects. Pass a project id (projectId on search/asset, project_id on import) to resolve the subscription tier, ownership and payer against that project — a collaborator in a shared-credit project inherits its tier and bills the project's credit balance. A project you are not a member of grants nothing.

Rate limits

Sources

List the enabled sources and which media types + filters each supports. Takes no parameters.

Endpoint

GET /api/v1/stock/sources

{
  "success": true,
  "mediaTypes": ["image", "illustration", "vector", "video", "3d", "music", "sfx"],
  "sources": [
    {
      "key": "kolbo-ai", "label": "Kolbo AI", "label_he": null,
      "description": null, "description_he": null, "enabled": true,
      "mediaTypes": ["sfx", "music", "image"],
      "filters": {
        "sfx": ["query","category","subcategory","collectionId","packId","lengthBucket","order"],
        "music": ["query","genre","mood","theme","instrument","vocals","collectionId","order","bpmMin","bpmMax","durationMin","durationMax"],
        "image": ["query","collectionId","packId","orientation","subject","setting","timeOfDay","copySpace","peopleCount","order"]
      },
      "attribution": null, "order_index": 0
    },
    { "key": "pexels", "label": "Pexels", "mediaTypes": ["image", "video"], "filters": { "image": ["orientation","size","color","query"], "video": ["orientation","size","query"] }, "attribution": { "label": "Photos & videos provided by Pexels", "url": "https://www.pexels.com" } },
    { "key": "unsplash", "label": "Unsplash", "mediaTypes": ["image"], "filters": { "image": ["orientation","color","query"] } },
    { "key": "pixabay", "label": "Pixabay", "mediaTypes": ["image","illustration","vector","video"] },
    { "key": "coverr", "label": "Coverr", "mediaTypes": ["video","music"], "filters": { "video": ["category","orientation","order","query"], "music": ["order","query"] } },
    { "key": "sketchfab", "label": "Sketchfab", "mediaTypes": ["3d"], "filters": { "3d": ["query","category"] } },
    { "key": "freesound", "label": "Freesound", "mediaTypes": ["sfx"], "filters": { "sfx": ["query","order"] } }
  ]
}

mediaTypes at the top level is the full set the library can expose; each source's own mediaTypes is what that source supports and what you are allowed to see. Only sources with enabled: true are returned, ordered by order_index.

Categories

Dynamic category/topic chips per source. Pass the returned providerParam as the category filter on Search.

Endpoint

GET /api/v1/stock/categories?source=pixabay&mediaType=image

Query Parameters

{
  "success": true,
  "count": 20,
  "categories": [
    {
      "source": "pixabay", "mediaType": "all", "key": "nature", "label": "Nature",
      "label_he": null, "providerParam": "nature", "paramType": "category",
      "thumbnailUrl": null, "order_index": 3, "group": null
    }
  ]
}

Rows come back sorted by source then order_index. paramType tells you which search parameter the row's providerParam belongs to (category or subcategory).

For Kolbo SFX (source=kolbo-ai&mediaType=sfx), categories are 2-level: top-level groups (group: null) and their sub-filters (each carries a group pointing to its parent, and paramType: "subcategory"). Pass a group's providerParam as category and a sub-filter's as subcategory.

Collections

Kolbo's own SFX library is organized into category collections (one per taxonomy group, kind: "category") and curated themed packs (kind: "pack" — e.g. Horror, Car Chase, In The Kitchen, Outer Space, Movie Trailer). Each has a cover image.

Endpoint

GET /api/v1/stock/collections?mediaType=sfx&kind=pack

Query Parameters

{
  "success": true,
  "count": 12,
  "collections": [
    {
      "id": "6a3c...", "slug": "sfx-col-horror", "title": "Horror", "title_he": null,
      "description": null, "coverUrl": "https://media.kolbo.ai/...",
      "kind": "pack", "categoryKey": null, "mediaType": "sfx", "order_index": 2
    }
  ]
}

Use a collection/pack id as packId or collectionId in Search to browse just that set.

Search

Unified search. With source=all (default) results from every provider that supports the media type are merged into one interleaved feed.

Endpoint

GET /api/v1/stock/search

Query Parameters

Every filter value above is truncated to 256 characters; only string values are forwarded.

curl "https://api.kolbo.ai/api/v1/stock/search?query=ocean%20waves&source=all&mediaType=video&perPage=4" \
  -H "X-API-Key: kolbo_live_..."

Semantic "vibe" search (Kolbo AI)

The kolbo-ai source is Kolbo's own AI-generated library: sound effects (mediaType=sfx), music (mediaType=music), and images (mediaType=image). For all three, a query is matched semantically — describe the feeling or use, not just keywords:

# Sound effects by vibe
curl "https://api.kolbo.ai/api/v1/stock/search?source=kolbo-ai&mediaType=sfx&query=tense%20ominous%20build-up%20for%20a%20horror%20reveal" \
  -H "X-API-Key: kolbo_live_..."

# Music by vibe
curl "https://api.kolbo.ai/api/v1/stock/search?source=kolbo-ai&mediaType=music&query=uplifting%20hopeful%20corporate%20background" \
  -H "X-API-Key: kolbo_live_..."

# Images by vibe
curl "https://api.kolbo.ai/api/v1/stock/search?source=kolbo-ai&mediaType=image&query=quiet%20minimal%20workspace%20with%20room%20for%20a%20headline" \
  -H "X-API-Key: kolbo_live_..."

Kolbo AI audio assets ship downloadVariants with per-file labels: SFX use mp3 and wav, music uses 320 (MP3), wav, and midi; images ship a single original. Each label appears only when that file exists for the asset, so read the labels rather than assuming — and pass one back as variant on Import. Kolbo AI music and SFX are paid audio: without a subscription or prior purchase the variants list comes back empty, but import still works (it charges meta.priceCredits) and resolves variant labels server-side. (External visual providers still want concrete keywords, not a vibe.)

Filter relaxation (Kolbo AI)

Stacked Kolbo AI filters can intersect on nothing even when each one has matches. Instead of returning an empty page, the kolbo-ai source drops filters one at a time, least-essential first, until something comes back:

The names of any dropped filters are returned in relaxedFilters (top level on a single-source search, per entry in sources[] under source=all). An empty or missing relaxedFilters means every filter was applied. Scope filters — packId and collectionId — are never relaxed: a pack or collection with no match returns an empty page.

Response

{
  "success": true,
  "assets": [
    {
      "source": "pexels",
      "sourceId": "12685044",
      "mediaType": "video",
      "title": "",
      "thumbnailUrl": "https://images.pexels.com/videos/.../poster.jpeg",
      "previewUrl": "https://images.pexels.com/videos/.../poster.jpeg",
      "width": 3840, "height": 2160, "durationSeconds": 20,
      "downloadVariants": [
        { "label": "uhd-2160p", "url": "https://...", "width": 3840, "height": 2160, "ext": "mp4", "fileSizeBytes": 12345678 }
      ],
      "author": { "name": "CityXcape", "url": "https://www.pexels.com/@cityxcape" },
      "providerUrl": "https://www.pexels.com/video/...",
      "license": { "name": "Pexels License", "attributionRequired": false, "url": "https://www.pexels.com/license/" },
      "tags": [],
      "attribution": "Video by CityXcape on Pexels"
    }
  ],
  "page": 1, "perPage": 4, "total": 8500, "hasMore": true, "partial": false, "nextCursor": null,
  "sources": [ { "source": "pexels", "total": 8000, "hasMore": true, "nextCursor": null }, { "source": "pixabay", "total": 500, "hasMore": true, "nextCursor": null } ]
}

Paginate by incrementing page (the same page is requested from each provider, so the interleaved feed stays consistent).

total is the sum across providers; a per-source sources[].total can be null when that provider does not report one. partial: true and a sources[].error: true entry mean one provider failed and the feed is incomplete — distinct from a genuinely empty result, and worth retrying. partial is only returned on the source=all fan-out; a single-source search omits it. nextCursor appears when a cursor-paginated provider (Sketchfab) participated; pass it back as cursor. Kolbo AI semantic searches, and every Kolbo AI image search or browse, report total: null — rely on hasMore. A single-source search to a kolbo-ai feed also returns relaxedFilters (see Filter relaxation).

Assets from a paid-audio catalog additionally carry meta.owned and meta.priceCredits, and arrive without download variants until you own the track or subscribe.

Asset

Resolve a single normalized asset with all download variants.

Endpoint

GET /api/v1/stock/asset/:source/:id

curl "https://api.kolbo.ai/api/v1/stock/asset/pexels/12685044?mediaType=video" \
  -H "X-API-Key: kolbo_live_..."

Returns { "success": true, "asset": { ... } } with the same asset shape as Search. An unresolvable id returns 404 STOCK_NOT_FOUND.

Analyze Script (auto b-roll)

AI helper that turns a video/voiceover script into concrete stock b-roll search terms you can feed into Search.

Endpoint

POST /api/v1/stock/analyze-script

Request Body

curl -X POST https://api.kolbo.ai/api/v1/stock/analyze-script \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "script": "Aerial shots of a coastal city at sunrise, then a team collaborating in a modern office." }'

{
  "success": true,
  "queries": ["coastal city sunrise", "aerial drone ocean", "team collaborating office", "modern office interior"],
  "mediaType": "video",
  "keywords": ["coast", "sunrise", "drone", "office", "teamwork"]
}

queries holds up to 6 concrete visual phrases (the model is asked for 3–6; only "at least one" is enforced, each clipped to 60 chars), mediaType is "video" or "image" (anything else becomes "image"), and keywords holds up to 6 tags. If no query at all can be derived you get 422 with code STOCK_SCRIPT_EMPTY.

Import

Copy a stock asset into your media library — downloaded to Kolbo's CDN with a stable URL so it can be used in projects and generations. Free, except for paid audio you do not yet own, which is charged once (after the copy succeeds). The licensed music source is not importable here — use Import Track to Media Library for it.

Endpoint

POST /api/v1/stock/import

Request Body

curl -X POST https://api.kolbo.ai/api/v1/stock/import \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "source": "pexels", "id": "12685044", "mediaType": "video" }'

{
  "success": true,
  "alreadyImported": false,
  "libraryItem": { "_id": "...", "mediaType": "video", "url": "https://media.kolbo.ai/...", "filename": "..." }
}

libraryItem is the full media-library record. Its mediaType is the library type, not the stock type: music and sfx become audio, 3d becomes 3d_model, and illustration / vector become image.

Re-importing the same (source, id) returns the existing item with alreadyImported: true — dedup is per user, ignores variant (a second import with a different variant still returns the first copy), skips items you have deleted, and nothing is re-downloaded or re-charged. The created item is sourceType: "stock" with metadata.stockSource, metadata.stockSourceId, metadata.variant, and the author/license/attribution copied onto it, so it stays separate from your own uploads in the Media Library.

Typical Flow

1. From a script → POST /stock/analyze-script to get queries[] + mediaType.
2. Search → GET /stock/search for each query (source=all). Show thumbnailUrl + attribution.
3. Resolve → GET /stock/asset/:source/:id for the full download variants.
4. Use it → POST /stock/import to copy the asset into the media library (stable CDN URL), then reference it in a project or generation.

Notes

• Search, categories, collections, asset, analyze-script and import are free — the only credit charge is importing a paid-audio track you do not already own.
• Always display the provider + creator credit (attribution) when you show results.
• Pixabay vectors currently ship as a high-resolution raster (true SVG requires Pixabay full API access); meta.vectorRasterOnly flags these.

Errors

Errors return { "success": false, "error": "...", "code": "..." }. The plain required-field checks (source and id are required on import, script is required on analyze-script) return 400 with no code.

Related