Find any resource in Clueso by type, optionally filtered by name or exact id. One tool for listing and searching across the workspace.
type:
• projects | folders | clueprints | workspaces
• backgrounds | voices | image_gen_style_packs | element_components
(voices carry `gender`, `tags`, `accent`, `preview_url` and — where one has been written — a free-text `description` of tone and pace, which is the field actually worth choosing on. `tags` is a small closed vocabulary, so it groups voices rather than telling them apart. Choose deliberately: voiceover is the film's clock, and regenerating speech later rescales the clip and every element time and keyframe with it.)
• images | videos | music | sfx — media; each result carries a `source` ('org' = your saved-media library, 'stock' = a stock/curated provider). Scope with `source`, pick the library with `provider` (see below). Stock results are a short described shortlist — pick the best fit and use its `src`. Stock video results also carry `safe_src` and a `video_files` tier list with one entry marked `recommended` — use `safe_src` (or the recommended tier) in add_elements; tiers above 1080p can exceed its ~200MB source cap and fail. For a Freesound music/sfx result, `src` is an OPAQUE handle (not a playable URL) — pass it straight to add_audio and the original is fetched + hosted by Clueso server-side; a `preview_url` is included only so you can tell what it sounds like.
(image_gen_style_packs = generation style presets for generate_media kind='image' style_id; element_components = saved components (e.g. animations) from THIS WORKSPACE only — there is no community library for components (unlike clueprints); each reports param_keys. Insert one AS-IS with add_elements(component_id=...), or generate a variant from it with base_component_id.)
Filters (all optional):
• query — for stock media it's the search phrase (real semantic search for provider='clueso'; provider keyword search otherwise). For clueprints a query runs a relevance-ranked search across your workspace + the global community library (search_summary, relevance_reason, tags, is_community, fork_count). For everything else it's a case-insensitive name substring.
• provider — which stock library to search (ONE call, no merging). Choose by strength:
images → 'pexels' (default; realistic photography) or 'pixabay' (illustrations, vectors, icons, clip-art — set image_type)
videos → 'pexels' (default; real-world footage) or 'pixabay' (motion graphics — set video_type='animation')
music → 'clueso' (default; our curated, brand-safe library with the best descriptions/search — try this FIRST) or 'freesound' (niche/genre tracks)
sfx → 'freesound' (default; vast sound-effect library) or 'clueso' (curated sfx)
• image_type — images + provider='pixabay': 'photo' | 'illustration' | 'vector'
• video_type — videos + provider='pixabay': 'film' | 'animation'
• id — exact id; returns just that one record (any type)
• source — media only: 'org' | 'stock' | 'all' (default = org + stock). Under 'all', stock is appended only when a query is given. sfx is stock only.
• folder_id — projects + saved media (images/videos/music): restrict to a folder
• engine / language — voices only
• creator_id / mine_only — clueprints only
• orientation — stock images/videos: 'landscape' | 'portrait' | 'square'
• color — stock images: a color name/hex, e.g. 'blue'
• size — stock videos: 'large' | 'medium' | 'small'
• min_duration / max_duration — stock videos + freesound audio: length bounds in seconds
• page / limit — paging for large sets (projects, components, clueprints — a clueprint list is sliced to the limit with no marker when more exist, so page through rather than assuming the first page is everything); stock media ignores these (fixed shortlist)
Returns { type, count, items: [{ id, name, type, ... }] }. Feed the returned id straight into the consuming tool (set_voice, update_clips background, generate_media style_id, add_audio src, use_clueprint, etc.). Any `duration` on a returned item is in SECONDS — pass it straight to add_audio's source_duration.
