Chat

Smart Select is the fallback, not a recommendation. Omitting model (or sending a blank string or null) routes the message through the auto-select router. The literal values "auto", "smart-select", "smart_select", "smartselect", "auto-select" and "kolbo_smart_select_router" all normalize to the same router — matching is case-insensitive and trims whitespace. On a Smart Select turn, routing_mode (fast, balanced or smart) narrows the pool the router picks from. The @kolbo/mcp tool chat_send_message deliberately steers agents toward a specific identifier instead, because auto-routing can land on a different model than the caller expects; pass an explicit model unless you actually want the router to choose.

Model identifiers are Kolbo-specific — they do not always match upstream provider names. Fetch identifiers from GET /api/v1/models?type=chat and use the identifier field. Known aliases and provider-prefixed forms of an identifier are mapped to the canonical one, but display names are not. An identifier Kolbo does not recognize is rejected with 400 MODEL_NOT_FOUND; the message suggests near matches.

deep_think: true takes over the turn — it ignores model. Deep think does not layer reasoning onto your selected model. It routes the whole turn to Kolbo's fixed reasoning model regardless of what you sent in model, and that is the model the status response reports and the one the deduction is attributed to. Three further consequences on a deep-think turn:

• Smart Select never runs — the router is skipped entirely, and neither routing_mode nor thinking_level has any effect.
• Web search never runs, even with web_search: true. The augmentation step is not reachable from the deep-think path, so no sources are retrieved and no citations appear.
• The video/audio analysis pass never runs. Media you pass in media_urls does not get the Gemini pre-analysis described below, so a deep-think turn answers as if the video or audio was not there.

Send deep_think: false (or omit it) whenever you need your own model, live sources, or media analysis.

Omitting session_id does not always start a fresh conversation. The API reuses one auto session per (user, project, day), named API Chat - YYYY-MM-DD. Two messages sent the same day without a session_id land in the same conversation and share context. To guarantee an isolated thread, keep your own session_id per logical conversation.

Rate limit: POST /v1/chat uses the SDK generation limiter — 30 requests/minute per user — and shares one bucket with every other route on that limiter: /v1/generate/video, /video/from-image, /music (plus its reference-audio, edit-section, import, extend and cover routes), /speech, /sound, /3d, /creative-director, /elements, /first-last-frame, /lipsync, /video-from-video, /v1/edit/video, /v1/analyze/video, and also several non-generation routes — /v1/media/upload, /v1/generate/:id/cancel, /v1/visual-dna create/update and character sheets, /v1/voices/clone, /v1/voices/import-elevenlabs, /v1/video/trim, /v1/lipsync-plans writes and /v1/skills (alias /v1/agents) writes. Requests rejected with an error status do not consume the budget. The two read routes — listing conversations and fetching messages — sit on the separate media-library limiter (120/min). Image generation (30/min) and transcription (100/min) also have their own buckets, and GET /v1/generate/:id/status has no per-route limiter, so polling never eats your generation budget. A global safety net still sits above every route, polling included: 5,000 requests/minute per API key (keyed on the key itself, so each key gets its own bucket rather than sharing your office IP's).

Request bodies are capped at 1 MB. A larger JSON payload is rejected by the body parser before the handler runs. Pass long documents as media_urls instead of pasting them into message.

Insufficient credits fail synchronously. Two gates run before the message is queued, both returning 403 with code INSUFFICIENT_CREDITS on the initial POST rather than during polling: a blanket check that your balance is at least 1 credit (its body also carries balance, required and pricing_url), then — when you named an explicit model — a check that you hold at least that model's credit cost (its body is just success, error and code). Smart Select skips the second check (the model is not known yet), so an auto-routed turn can still fail after the POST succeeds.

API chat opts out of user memory. Neither your personal memories nor the auto-generated project-context summaries are injected into the prompt. Every message sent through POST /v1/chat also stamps its session as already-mined, so the auto-memory and project-context workers skip it — note this applies to any session you post into, including one you originally started in the Kolbo web app. The stamp is not permanent: the next message sent to that session from the web app clears both markers and mining resumes.

They are not fully isolated from the project, though: the conversation still lives in a project, and that project's linked Visual DNAs / moodboards (the "cast" directive) and its file knowledge base (vector search over project files) are still injected on every turn. Send project_id pointing at an empty project if you want a clean-room conversation.

Citation sources are not returned by the API. The answer text carries the [n] markers, but the URL list behind them lives in message metadata that neither GET /v1/generate/:id/status nor GET /v1/chat/conversations/:sessionId/messages returns. Ask the model to spell out the URLs in its answer if you need them.

Video and audio are a two-step, two-model turn. Whenever the turn carries a video, an audio file or a YouTube link, Kolbo first runs a dedicated Gemini analysis pass over the media and hands that analysis to your model — and both models are billed, so credits_used is higher than the chat model's list price. This happens even when your model natively accepts video or audio: there is no model you can pick to skip the second leg. Your model is never swapped out; the analyzer only feeds it. Any images on the same turn are analyzed in that pass too.

Images behave differently from video/audio. An image-only turn never triggers the two-step path. If your model has native vision the images are passed to it directly; if it is text-only, Kolbo pre-analyzes the images and injects the description as text so your model still answers. That image-analysis pass is not billed — only video/audio analysis adds credits.

The media count limit on an analysis turn fails silently. Once any video, audio file or YouTube link is present, Kolbo counts every image, video, audio file and YouTube link on the turn and allows at most 10 items. Breaching it aborts the whole analysis pass — no error is returned, your model still answers, and the reply reads as if the media was not there. Split large batches across messages. (The pipeline's 500 MB per-file check applies only to direct file uploads, which this endpoint does not accept; URLs in media_urls are not size-checked at this step.)

A YouTube link in message counts as media. URLs are extracted from the message text itself, so a bare YouTube link triggers the same Gemini analysis pass (and its billing) even when media_urls is empty.

Chat is the one endpoint that does not return generation_id. The job handle is message_id. Every other generation endpoint returns generation_id, so a shared poll helper written as pollUntilDone(started.generation_id, …) — including the reference loop in Polling & Cancellation — receives undefined here and polls /v1/generate/undefined/status, which answers 400 Invalid generation ID format. Pass started.message_id (or just use started.poll_url).

Note also that the status response for that same job reports the id back under generation_id, not message_id — the two names refer to the same value. And poll_interval_hint is 2 seconds on chat.

Poll until state leaves processing. The status endpoint deliberately holds a chat turn at processing until text or media actually lands, because the message is flagged complete before the streamed tokens are persisted — a naive "stop at first completed" poller reads an empty reply. A genuinely empty completion is released after 90 seconds. Failed turns return state: "failed" with error plus a failure object (message, category, code, retryable, severity — each null when no structured detail was recorded). An unknown or foreign id returns 404 Generation not found; a malformed one 400 Invalid generation ID format.