Chat

Smart Select is the fallback, not a recommendation. Omitting model (or sending a blank string) 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. 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. An identifier that is not in the catalog returns 400 with code MODEL_NOT_FOUND.

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.
• 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: all three /v1/chat* routes use the default SDK generation limiter — 10 requests/minute per user — and share one bucket with every other route on that limiter: /v1/generate/video, /video/from-image, /music, /speech, /sound, /3d, /creative-director, /elements, /first-last-frame, /lipsync, /video-from-video, /v1/edit/video, and also several non-generation routes — /v1/media/upload, /v1/generate/:id/cancel, /v1/visual-dna creation, /v1/voices/clone, /v1/voices/import-elevenlabs, /v1/video/trim, /v1/moodboards reads and /v1/agents writes. Listing conversations and fetching messages count against it too, so a chatty client can rate-limit its own uploads. Image generation (30/min), media-library ops (120/min) and transcription (100/min) use separate 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, then — when you named an explicit model — a check that you hold at least that model's credit cost. 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. When the selected model has no native video/audio support, Kolbo first runs a Gemini analysis pass over the media and hands that analysis to your model — both models are billed on the same deduction, so credits_used is higher than the chat model's list price. Models that natively support the media type skip the extra pass. Your model is never swapped out; the analyzer only feeds it.

The skip is only evaluated for a named model. On a Smart Select turn there is no model to inspect at that point, so the analysis pass always runs and always bills — pass an explicit model with native video/audio support if you want to avoid the second leg.

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.

Media limits on an analysis turn fail 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 enforces two limits before running the analysis pass: at most 10 items total, and at most 500 MB per uploaded file. Breaching either one 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 and keep individual files under the size cap.

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, the lowest of any type; the interval table on the polling page does not list 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, provider — each null when the provider gave no structured detail).