@kolbo/mcp/README.md

Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code

# @kolbo/mcp

## Personal fonts

Browse **My fonts** with `list_fonts({source:"custom"})` (the default), or the read-only **Font collection** with `source:"global"`. Use `source:"all"` to search both. Mix up to three family IDs across both sources in the same generation; inspect actual styles/scripts with `get_font`. Collection fonts do not need uploading and cannot be renamed or deleted by users.

Use `list_fonts` / `get_font` to discover My Fonts. Local stdio clients upload one OTF/TTF/WOFF2 (up to 5 MiB) with `upload_font`; remote shell clients use `create_font_upload_ticket`, and browser clients use `font_upload_widget`. Poll `get_font_upload_status` until ready, then pass the returned family ID in `font_ids` to image creation/editing or image-mode Creative Director. `rename_font` and `delete_font` manage the library.

Only models reporting `supports_custom_fonts: true` accept these selections. Fonts and backend-generated specimens never go through media upload. See [Personal Fonts](https://docs.kolbo.ai/developer-api/personal-fonts). Availability requires a published client and deployed backend containing these tools; source changes alone do not update installed clients.

## No-background images

`generate_image` and `generate_image_edit` accept `background: "transparent"` for models whose `list_models` record reports `supports_transparent_background: true`. Kolbo also appends the exact phrase `no background` once to the effective prompt, while the structured setting requests the native alpha channel through the configured provider route. Use `output_format: "png"` or `"webp"` (PNG is selected automatically when omitted). Prompt wording alone is not sufficient, and unsupported models reject the request instead of silently returning an opaque image.

Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Desktop via MCP (Model Context Protocol).

Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.

**✨ Interactive widgets (v1.30+):** in claude.ai, Claude Desktop, and Codex Desktop, generations render as live Kolbo cards — real-time progress with model + settings chips, an inline result gallery / video or audio player, and one-click **Animate · Edit · Recreate · Download** actions. Multi-audio generations render every track with its own player and Download button. Library and model searches render as browsable grids with audio preview. Text-only clients (Claude Code, Codex CLI, Cursor) keep the classic text responses.

## Set up — paste one prompt, or one config block (keyless, no API key)

### Flow sessions and nodes

Flow tools create, inspect, precisely edit, organize, validate and run saved node workflows in an explicit project. Use `get_flow_schema`, `get_flow_session` and revision-checked `update_flow_session` for prompts, Assistant system prompts, settings, groups and connections. Runs use explicit aggregate credit limits and persisted run IDs. Compatible Flow API routes are required. See [Flow MCP workflow and contract](docs/FLOW-MCP.md).

### Easiest: paste this prompt to your AI

Copy this and paste it to Claude, ChatGPT, Cursor, or any AI assistant — it installs Kolbo itself (picks local config or remote connector based on what it can do):

```
Connect the Kolbo AI MCP server (generate images, video, music and more).

- If you can run terminal commands (Claude Code, Cursor, Claude Desktop, or any local setup): run "npx -y @kolbo/mcp install" — it auto-configures Kolbo in the right place. If you can't run it, give me the command to run. Then I'll restart the app.
- If you're a browser chat (claude.ai, ChatGPT): add a custom connector with URL https://api.kolbo.ai/mcp under Settings → Connectors, then Connect → log in → Allow.

No API key needed — on first use a Kolbo login opens in my browser and I click Allow. When set up, confirm Kolbo is connected and offer to generate a test image of a sunset.
```

### Or set it up yourself — one command

<!--
  AI ASSISTANT SETUP INSTRUCTIONS — if you are an AI agent reading this to set up Kolbo for a user, do exactly this:
  1. If you can run a terminal command (Claude Code, Cursor, Claude Desktop): run `npx -y @kolbo/mcp install` — it writes the keyless config to the right file for every installed agent. (Don't hand-edit settings.json; the installer is deterministic.) Then tell the user to restart the app. On the first generation a Kolbo login opens in the browser — they click Allow (no API key).
  2. If you're a web chat that can't run commands (claude.ai, ChatGPT): tell the user to add the connector URL https://api.kolbo.ai/mcp under Settings → Connectors instead.
  The plugin below is an optional slash-command upgrade.
-->

Run this once — it sets up the **full** Kolbo experience (the MCP tools **and** the routing skill) for every installed agent (Claude Desktop, Claude Code, Cursor), keyless:

```bash
npx -y @kolbo/mcp install
```

Or add the config by hand — this block is identical for every MCP client and carries **no API key** (on first use it logs you in via the browser):

```json
{
  "mcpServers": {
    "kolbo": {
      "command": "npx",
      "args": ["-y", "@kolbo/mcp@latest"]
    }
  }
}
```

| Client | Where the config goes |
|--------|----------------------|
| **Claude Code** | `~/.claude.json` (or `claude mcp add kolbo -- npx -y @kolbo/mcp@latest`) |
| **Claude Desktop** | `claude_desktop_config.json` |
| **Cursor** | `.cursor/mcp.json` |
| **Kolbo Code** | configured automatically on `kolbo auth login` |

Restart your app, then ask it to generate something. The first time, a Kolbo login opens in your browser — click **Allow** (no API key to create). _Prefer an API key? Create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer) and add `"env": { "KOLBO_API_KEY": "kolbo_live_..." }` to the block above._

### Browser-only (claude.ai / ChatGPT / Codex): connector + skill

1. Add the custom connector **`https://api.kolbo.ai/mcp`** under Settings → Connectors, then Connect → log in → Allow.
2. [Download the Skill](https://kolbo.ai/skills/kolbo.zip) and upload it (Claude.ai: Settings → Features → Skills; ChatGPT/Codex: Settings → Skills). Codex CLI: unzip into `~/.codex/skills/`.

The Skill is the canonical routing layer. Without it the tools still work, but the model will not load Seedance / Visual DNA / filmmaking rules.

### Optional upgrade: add the Kolbo skill for slash-commands + smart routing

The config above is all you need. If you want one-word slash-commands (`/kolbo:marketing-studio`, `/kolbo:product-photoshoot`, …) and automatic routing to the best tool with the right defaults, install the Kolbo skill on top — it's an enhancement layer, not a requirement:

```bash
# Claude Code plugin (canonical skill + MCP configuration)
claude plugin marketplace add Zoharvan12/kolbo-claude-plugin
claude plugin install kolbo@kolbo

# Skill only — installs the bundled official skill without changing MCP settings
npx -y @kolbo/mcp@latest skill
```

The skill-only command installs the canonical single `kolbo` skill and does not change MCP configuration. The Claude Code plugin and `npx -y @kolbo/mcp install` routes configure MCP as well. Official installer-created skill folders are marked as Kolbo-managed and refresh automatically when the MCP server starts on a newer package; unmarked or hand-authored folders are never overwritten. The canonical skill ships inside [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so however you connect, the behavior matches. See the full setup guide at [docs.kolbo.ai/developer-api/claude-code-skill](https://docs.kolbo.ai/developer-api/claude-code-skill).

### Use it

Just ask your agent naturally:

**Generation**
- *"Generate an image of a sunset over mountains"*
- *"Create a 5-second video of waves crashing"*
- *"Build a 4-scene storyboard for a coffee shop ad"*
- *"Remove the background from this image"*
- *"Make a lo-fi hip hop beat"*
- *"Read this out loud with a British female voice"*

**Marketing & UGC**
- *"Make me a UGC ad for my sneaker brand — 9:16, talking-head style"*
- *"TV spot for my new beverage, 15 seconds, cinematic"*
- *"Unboxing video for this product photo"*

**Brand & product imagery**
- *"Pinterest pin for my candle brand, cottagecore mood"*
- *"Hero banner for my landing page, wide format"*
- *"Lifestyle shot of my product in a kitchen"*
- *"4 ad creative variants for Meta and TikTok"*

**Marketplace listings**
- *"Generate Amazon main image + 5 secondary images for my product"*
- *"Full A+ content set for my Shopify listing"*

**Analysis & utility**
- *"Ask Claude about the latest AI news with web search on"*
- *"Analyze this video and tell me what prompts are shown on screen"*
- *"What's in this image?"*
- *"Create a Visual DNA profile called 'Alex' from these images"*
- *"Use the same brand as last time"* (loads a persisted brand kit from the workspace)

Without the optional skill, the config block alone already exposes every tool — you just describe what you want. With the skill installed, each of these is also routed to the right MCP tool with the right defaults — UGC mode picks 9:16 + sound-off + no-captions, marketplace mode enforces compliance (pure white bg, no text, no props), product photoshoot mode uses the right aspect for the platform (2:3 Pinterest, 16:9 hero banner, 1:1 IG feed), etc. The routing logic is shared with [Kolbo Code](https://github.com/Zoharvan12/kolbo-code), so the behavior is identical however you connect.

## Available Tools

**Generation**
| Tool | Description |
|------|-------------|
| `generate_image` | Text → image. Supports `preset_id` from `list_presets type="image"`. |
| `generate_image_edit` | Existing image(s) + prompt → edited image. Supports `preset_id` from `list_presets type="image_edit"`. |
| `generate_video` | Text → video |
| `generate_video_from_image` | Still image + motion prompt → video |
| `generate_video_from_video` | Input video → restyled video, or burn in subtitles (video-to-video). `prompt` optional — prompt-less models (VEED Subtitles, Act Two, Wan Animate) use `preset` / `source_language` / `translation_language`, plus `srt_content` / `srt_file_url` / `vocabulary` / `customization` for VEED |
| `generate_elements` | Reference images/videos/audio + prompt → animated video |
| `generate_first_last_frame` | First frame + last frame → interpolated video |
| `generate_lipsync` | Source image/video + audio → lipsynced video (Sync-3 adds active-speaker selection, emotion, model mode, temperature) |
| `generate_creative_director` | One brief → N coordinated scenes (image or video) |
| `generate_music` | Text (+ optional lyrics) → song. Style, title, negative tags, length, and Suno fine-controls (style weight, weirdness, audio weight, persona / singing voice) |
| `generate_speech` | Text + voice → spoken audio. `eleven_model` (eleven_v4 / eleven_v3 / eleven_multilingual_v2) picks which ElevenLabs model speaks an ElevenLabs voice (stock or own clone; omit = the voice's default; same price; `turbo` needs v4). Full expressive/style control: Google/Gemini named voice-direction presets (`style_instructions_preset_id`: warm/dramatic/whisper/…) or free-form `style_instructions`, preset styles + emotions (DeepDub / MiniMax / Cartesia), speed, accent/`language`, and per-provider voice settings (ElevenLabs stability/similarity/style/speaker boost/seed, `enforce_language`, `output_format` mp3/wav, `text_normalization`; DeepDub accent/variance/tempo, MiniMax pitch/volume/intensity/timbre), plus `audio_effect` (phone/radio/megaphone/small_room/hall/distant) + `audio_effect_strength` for any voice at no extra credits. Status returns the same fields for reuse. |
| `generate_sound` | Text → sound effect. Duration, prompt influence, and per-provider controls (Stable Audio guidance, Kie loop/tempo/key, Seed-Audio voice/speed/volume/pitch + reference audio/image, output format, Mirelo SFX 2.0 negative prompt / variations / seed / bitrate) |
| `generate_3d` | Text or reference images → 3D model (GLB/FBX/OBJ/USDZ) |
| `transcribe_audio` | Audio/video URL or file → text + SRT subtitles. Language, speaker diarization, audio-event tagging, and SRT formatting (words/line, lines/subtitle, caption stretch) |
| `separate_audio_stems` | Audio/video URL (or a Kolbo `generation_id`) → Dialogue / Music / Effects / without-dialogue (M&E) layers. Kolbo's own masking pipeline with a speech classifier on top, so a centred engine or ambience is not handed back mislabelled as dialogue. 5 credits, runs inline |
| `clean_dialogue_leftovers` | Strip voices still faintly audible in an M&E layer. 17 credits — escalation only, it trades bed fidelity to remove the leak |
| `separate_ambience` | Pull room tone / atmosphere out of the Effects (or Music) bed as its own layer. 17 credits |

Every image/video/creative-director tool accepts `visual_dna_ids` and `moodboard_id` for character/style consistency across outputs — you can compose `create_visual_dna` → `generate_image` (with the DNA applied server-side) in a single agent turn. `generate_creative_director` also accepts `moodboard_ids` plural for blending.

Every generation tool also accepts an optional `resolution` arg. Images use `"1K"` (~1024px) / `"2K"` (Full HD) / `"3K"` (QHD) / `"4K"` (UHD); videos use vertical-pixel tiers like `"720p"` / `"1080p"` / `"1440p"` / `"2160p"`. Values are model-dependent — call `list_models` and read the chosen model's `supported_resolutions` and `resolutionMultipliers`. Omit to use the model default.

Every generation tool also accepts an optional `project_id` arg that routes the generation into a specific project (owned or shared with edit+). Call `list_projects` to discover IDs. When omitted, generations land in the user's auto-created "API Generations" project. `project_id` is per-call, NOT sticky — pass it on every call once the user names a working project. Misplaced work is recoverable via `move_media` / `move_session`.

**Chat & Vision**
| Tool | Description |
|------|-------------|
| `chat_send_message` | Multi-turn chat with any Kolbo model. Pass `media_urls` to analyze images, videos, or audio — auto-routes to Gemini for vision. Supports web search and deep think. |
| `chat_list_conversations` | List past chat threads |
| `chat_get_messages` | Fetch messages in a conversation |

**Visual DNA** (reusable character/style/product profiles)
| Tool | Description |
|------|-------------|
| `create_visual_dna` | Create a profile from URLs or local files |
| `update_visual_dna` | Edit name, description, stills, sheet, or type in place (never delete+recreate) |
| `list_visual_dnas` | List your profiles |
| `get_visual_dna` | Fetch one profile |
| `delete_visual_dna` | Delete a profile |

**Moodboards**
| Tool | Description |
|------|-------------|
| `list_moodboards` | Browse presets + your moodboards |
| `get_moodboard` | Fetch one moodboard with all image URLs |
| `create_moodboard` / `update_moodboard` / `delete_moodboard` | Create / edit in place / delete |

**Color DNA** — sticky, account-wide: the ACTIVE palette strict-grades every generation until deactivated. Opt a single generation out with `skip_color_palette`.
| Tool | Description |
|------|-------------|
| `list_color_palettes` | List your palettes (+ org) |
| `analyze_color_palette` | Extract colors from 1-5 image URLs (free, does not save) |
| `create_color_palette` | Save a palette (colors from analyze or manual); auto-activates by default |
| `update_color_palette` | Rename / replace colors |
| `delete_color_palette` | Delete a palette |
| `activate_color_palette` | Make a palette the sticky active one |
| `deactivate_color_palette` | Clear the active palette |

**Media Library**
| Tool | Description |
|------|-------------|
| `media_upload_widget` | Open an in-chat upload card so claude.ai users can upload LOCAL files (image / video / audio / document) — chat attachments are unreachable from remote MCP, so this is the way to bring them in. Returns stable CDN URLs |
| `create_upload_ticket` | Get a short-lived upload ticket and POST local files yourself — no upload card, no user interaction. For agents with shell access (Claude Code, Codex, Cursor, CI) talking to Kolbo over a remote connector |
| `upload_media` | Upload a local file (path or URL), or inline `source_base64` + `filename`, → stable Kolbo CDN URL for reuse |
| `list_media` | Browse media library — filter by `project_id`, `folder_id`, `type`, `category` (ai / uploaded / edited / favorites / training-lab), `source_type`, `sort`, `search`, pagination |
| `list_media_folders` | List the user's media folders (owned + shared) — discover `folder_id` values to pass to `list_media` |
| `create_media_folder` | Create a new folder (name, optional description / color / icon) |
| `update_media_folder` | Rename / recolor / re-icon a folder (owner only) |
| `delete_media_folder` | Soft-delete a folder (owner only; items remain in library) |
| `add_media_to_folder` | Add up to 500 media items to a folder (idempotent) |
| `remove_media_from_folder` | Remove media items from a folder |
| `share_media_folder` | Share a folder by user email (owner only) |
| `unshare_media_folder` | Revoke a user's access to a folder (owner only) |
| `favorite_media` | Mark a media item as favorited (idempotent) — pass `media_id` from `list_media` |
| `unfavorite_media` | Remove a media item from favorites (idempotent) — pass `media_id` from `list_media` |
| `get_media` | Fetch one media item's full details by id |
| `delete_media` | Soft-delete a media item (30-day trash) |
| `restore_media` | Restore a trashed item |
| `permanently_delete_media` | Hard-delete (NOT reversible — confirm with user first) |
| `move_media` | Re-assign a media item to a different project |
| `bulk_delete_media` | Soft-delete up to 1000 items in one call |
| `bulk_restore_media` | Restore up to 1000 trashed items |
| `bulk_permanently_delete_media` | Hard-delete up to 1000 (NOT reversible) |
| `bulk_move_media` | Move up to 1000 items to a project (atomic — all-or-nothing) |
| `move_folder_contents` | Move every item in a folder to a project |
| `get_media_stats` | Counts + storage bytes per type (optionally per project) |

**Artifacts**
| Tool | Description |
|------|-------------|
| `publish_html_artifact` | Publish an HTML page, SVG, or Mermaid diagram and get a public shareable URL on `sites.kolbo.ai`. Pass `share_token` from a prior publish to update the same URL in place (old content kept in version history). |

**SYNCI Music Library** (licensed production music)
| Tool | Description |
|------|-------------|
| `search_music_library` | Search the licensed catalog; results contain watermarked previews only. |
| `analyze_script_for_music` | Turn a script or scene description into a music search. |
| `browse_music_library` | Browse the catalog without a query. |
| `get_music_library_facets` | List genres, moods, instruments, BPM, and duration filters. |
| `get_music_track_audio` | Get watermarked preview URLs for a track. |
| `acquire_clean_music_track` | Spend one SYNCI vendor credit and return clean MP3/WAV signed URLs. Idempotent with `request_id`. |
| `import_music_track_to_library` | Spend one vendor credit and copy a clean MP3/WAV into Kolbo's media library. |
| `get_music_track_related` | Get stems/alternate-version metadata (purchasing remains unsupported). |
| `get_music_track_lyrics` | Get lyrics metadata. |

**Stock Library** (multi-source stock media: Pexels, Pixabay, Sketchfab 3D, Music)
| Tool | Description |
|------|-------------|
| `search_stock_media` | Search photos/videos/illustrations/vectors/3D/music across providers. `source="all"` returns one interleaved feed. Find ready-made assets / b-roll (distinct from `generate_image`/`generate_video`). |
| `get_stock_sources` | List enabled sources + which media types/filters each supports. |
| `get_stock_categories` | List dynamic category/topic chips (pass `providerParam` as the `category` filter). |
| `get_stock_asset` | Get one asset with all download variants, author, license, and attribution. |
| `analyze_script_for_stock` | AI: turn a script into b-roll search terms (`queries[]`, `mediaType`, `keywords`). |
| `import_stock_asset` | Copy a stock asset into the media library (CDN copy, stable URL). Free. |

**Blender Bridge**
| Tool | Description |
|------|-------------|
| `blender_list_sessions` | List the caller's connected Blender processes before choosing a target session |
| `blender_get_scene` | Queue a bounded scene summary or full scene inspection |
| `blender_search_docs` | Inspect local Blender RNA and return relevant official API/manual URLs without fetching them |
| `blender_capture_viewport` | Capture the active viewport to managed cache and optionally Kolbo media |
| `blender_apply_operations` | Apply approved structured object, material, world, camera, light, animation, duplication, or deletion operations |
| `blender_import_media` | Import a Kolbo media item or exact-allowlisted Kolbo-owned HTTPS media/CDN asset using smart GLB/image/video placement |
| `blender_render` | Render a still or an animation capped by Blender at 250 scene frames and 100,000,000 pixel-frames, to managed output and optionally Kolbo media |
| `blender_undo` | Undo the most recent Blender change in the selected process |
| `blender_file_operation` | Perform sensitive new/open/save/save-as operations with in-Blender approval |
| `blender_execute_python` | Execute explicitly reviewed Python plus a required plain-language purpose with full host authority; approval required unless trusted mode is visibly active |
| `blender_get_command_status` | Read bounded command status/result/error plus absolute `expires_at`; records and idempotency claims expire after 24 hours, and `awaiting_approval` means stop and wait for the user |

**Premiere Pro & After Effects Bridge**
Requires the Kolbo Studio panel open in Premiere Pro or After Effects with **AI agents** switched on in its header. Every edit is approved by the editor inside the panel; scripts are shown in full before they run.

| Tool | Description |
|------|-------------|
| `adobe_list_sessions` | List the caller's Premiere Pro / After Effects windows connected through the Kolbo panel |
| `adobe_get_project` | Queue a read-only project inspection (no approval) |
| `adobe_get_timeline` | Queue a read-only inspection of the active sequence (tracks, clips with start/end, playhead) or composition (layers), bounded by `max_clips` |
| `adobe_import_media` | Import one Kolbo media id or Kolbo-owned HTTPS URL into the Kolbo.AI / My Media bin for its type |
| `adobe_place_on_timeline` | Import and place one Kolbo media item at the playhead of the work sequence / active comp (no time or track control in v1) |
| `adobe_create_sequence` | Create and open a Premiere Pro sequence matching the open sequence's settings, no dialog (Premiere only) |
| `adobe_import_captions` | Import a Kolbo-hosted SRT onto the active Premiere sequence (Premiere only) |
| `adobe_edit_composition` | After Effects: one undo step of structured edits - comps, timed and trimmed Kolbo media, titles with stroke, solids, transforms, keyframes, audio fades, layer deletion |
| `adobe_run_script` | Approval-gated ExtendScript for real motion graphics (shape layers, trim paths, text animators, effects, expressions, cameras); the editor reviews the exact code |
| `adobe_capture_frame` | Render a comp/sequence frame to the Kolbo library so the agent can check its work |
| `adobe_get_command_status` | Read command status/result/error; `awaiting_approval` means stop and wait for the editor |

**DaVinci Resolve Bridge**
Requires DaVinci Resolve Studio with the Kolbo plugin open (Workspace → Workflow Integrations → Kolbo AI) and **AI agents** switched on in its header. Every edit is approved by the editor inside the plugin; scripts are shown in full before they run.

| Tool | Description |
|------|-------------|
| `resolve_list_sessions` | List the caller's DaVinci Resolve windows connected through the Kolbo plugin |
| `resolve_get_project` | Queue a read-only project inspection: timelines, frame rate, resolution, playhead (no approval) |
| `resolve_get_timeline` | Queue a read-only inspection of the current timeline: clips per track with start/end, markers, playhead |
| `resolve_import_media` | Import one Kolbo media id or Kolbo-owned HTTPS URL into the Kolbo.AI Media Pool bin |
| `resolve_edit_timeline` | Structured edits: new timelines, timed and trimmed Kolbo clips on chosen tracks, transitions, audio fades, Fusion titles, markers, clip deletion |
| `resolve_run_script` | Approval-gated JavaScript against Resolve's scripting API (colour, Fusion, render jobs); the editor reviews the exact code |
| `resolve_capture_frame` | Export a timeline frame to the Kolbo library so the agent can check its work |
| `resolve_get_command_status` | Read command status/result/error; `awaiting_approval` means stop and wait for the editor |

**Discovery & Account**
| Tool | Description |
|------|-------------|
| `list_models` | Current model catalog with costs and capabilities |
| `list_voices` | TTS voices (presets + cloned) |
| `list_presets` | Generation presets across image/image-edit/video/music/text-to-video catalogs. Pass the selected exact id as `preset_id`; never claim a preset was applied without it. |
| `list_cinematic_presets` | "Cinema mode" presets grouped by dimension (camera, lens, focal_length, aperture, angle, shot_type, color_palette, lighting) — pass ids via the `cinematic` arg on `generate_image` / `generate_image_edit`. Only when the user wants a specific cinematic look |
| `list_projects` | List owned + shared projects (id, name, description, role, is_default) — call first to resolve a project name into the `project_id` you pass to generation tools |
| `get_project` | Full project record including the unclipped description — read this before `update_project` |
| `move_session` | Move ONE session (generation, chat, transcription…) and ALL its generations + media to another project |
| `bulk_move_sessions` | Move up to 100 sessions into one project in a single call — mixed types allowed, per-session failures reported |
| `list_session_generations` | A session's generations as complete groups (prompt + all its outputs) — the ids the two organize tools below take |
| `move_generations_to_session` | Move selected generations (and only THEIR output media) into another existing session |
| `split_session` | Carve selected generations out into a brand-new named session, atomically |
| `undo_session_organization` | Reverse a move/split within 15 minutes, using the `operation_id` it returned |
| `create_doc` / `list_docs` / `get_doc` / `update_doc` / `share_doc` / `delete_doc` | AI Docs (Magic Pad): author project-scoped HTML documents, edit them, get public share links |
| `generate_character_sheet` | Generate a multi-angle character sheet from reference images (credits) → pass URL to create_visual_dna or update_visual_dna |
| `list_visual_dna_folders` / `create_visual_dna_folder` / `update_visual_dna_folder` / `delete_visual_dna_folder` / `move_visual_dna_to_folder` | Organize Visual DNA characters into user folders (create/rename/recolor/delete + move DNAs in/out) |
| `create_project` / `update_project` / `archive_project` / `unarchive_project` | Project lifecycle (create/rename/describe/archive; deletion stays in-app) |
| `transfer_project` / `list_project_transfers` / `respond_project_transfer` | Hand a project you own to another Kolbo account (they accept; same ids; cast assets copied; payer history unchanged) |
| `list_skills` / `create_skill` / `update_skill` / `delete_skill` | Skills — reusable named personas for the chat tool; `description` is the system instruction |
| `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Same four tools under their original names. Still supported and unchanged; new integrations should use the `*_skill` names |
| `create_video_editor_session` / `export_video_editor_session` | Build an editable timeline from Kolbo-hosted clips, audio and text, then export it to MP4. No new media is generated; identical snapshots reuse the same export job |
| `get_creative_director_status` | Re-check a Creative Director batch by generation_id until all parallel scenes finish (use after a `_timed_out` Director run) |
| `list_sessions` | Enumerate sessions across all types, filterable by project, `type`, and `types[]` |
| `rename_session` / `delete_session` / `restore_session` | Rename a session; soft-delete leftovers after a move; restore from trash |
| `add_project_context` / `list_project_context` / `delete_project_context` / `get_project_profile` / `regenerate_project_profile` | Project knowledge base (RAG): feed scripts/URLs/notes, read the synthesized living brief |
| `list_project_assets` / `link_project_asset` / `unlink_project_asset` / `update_project_asset` | Project cast: tag Visual DNAs / moodboards onto a project, write each DNA's description and purpose note |
| `create_moodboard` / `update_moodboard` / `delete_moodboard` | Build/edit moodboards from image URLs (AI style analysis → master prompt) |
| `clone_voice` / `import_elevenlabs_voice` / `delete_voice` | Custom voices: clone from an audio sample, import by ElevenLabs ID, delete |
| `trim_video` | Frame-accurate server-side trim of a Kolbo-hosted video (async job, tool waits) |
| `check_credits` | Check credit balance; widget hosts show total and plan, credit-pack, and redemption breakdown, while text hosts retain the plain-text response |
| `get_generation_status` | Check one or many generations (`generation_ids`); `wait=true` blocks server-side until done — replaces client polling loops |

## Environment Variables

Both are optional — the local install logs in via the browser on first use.

| Variable | Required | Description |
|----------|----------|-------------|
| `KOLBO_API_KEY` | No | Set a `kolbo_live_` key to skip the browser login (create one at [app.kolbo.ai/developer](https://app.kolbo.ai/developer)). |
| `KOLBO_API_URL` | No | Custom API URL (default: `https://api.kolbo.ai/api`) |

## Links

- [API Documentation](https://docs.kolbo.ai/developer-api)
- [Kolbo AI Platform](https://kolbo.ai)
- [Get API Key](https://app.kolbo.ai)

### Chat thinking level

`chat_send_message` accepts optional `thinking_level`, using an ID from `list_models` with `type: "text"`. The server validates it against the resolved model; omitted or invalid values use `thinkingDefault`. Existing safeguards and legacy `deep_think` take precedence. Discover allowed levels through `thinkingLevels`; no package update is required when the server changes a model capability. For the Auto model, optional `routing_mode` accepts `fast`, `balanced`, or `smart`; omitted uses the server default of `balanced`.

## Agentic Video Editor

| Tool | Purpose |
| --- | --- |
| `get_video_editor_schema` | Complete writable settings and operation contract |
| `list_video_editor_sessions` | Paginated project timelines |
| `get_video_editor_session` | Full saved timeline and revision |
| `update_video_editor_session` | Atomic rename, settings, tracks, clips, trims, speed, captions and effects |

`create_video_editor_session` also accepts optional advanced `session_data` instead of clips/audio/texts. Read the schema and saved revision before editing. Changes affect saved state; reload an already-open editor before manual editing. Existing create/export names and arguments remain supported.

### URL downloads

`download_media_from_url` starts a server download for a public media page URL. Use `get_download_status` with the returned `job_id` (not `get_generation_status`) and wait for `completed` before using `resultUrl`. `cancel_download` cancels an active job. This produces a cloud file and saves it to the account library when library sync succeeds; it does not write to the caller's computer. Video returns a verified MP4, audio returns MP3; maximum 500 MB. Existing `upload_media` still handles local/direct-file uploads. SDK routes reuse the authenticated utility pipeline at `POST /v1/downloads`, `GET /v1/downloads/:jobId`, and `DELETE /v1/downloads/:jobId`.

Video-edit widgets keep source-video and mask-video previews, image references, and audio references through generation and completion. Click a video thumbnail to inspect the source. Local edit inputs preview through their uploaded CDN URLs.