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 and are free (no credits). 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.

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. (External visual providers still want concrete keywords, not a vibe.)

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.

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. 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": "..." }
}

Re-importing the same (source, id) returns the existing item with alreadyImported: true — dedup is per user, and nothing is re-downloaded. 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

• All Stock Library endpoints are free — they do not consume credits.
• 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

All errors return { "success": false, "error": "...", "code": "..." }.

Related