Video Analysis

Ask questions about any video — timestamps, counts, summaries, verbatim transcripts — with Kolbo's agentic video understanding.

Kolbo's official video understanding. Instead of sampling a video at a fixed frame rate, the model navigates the timeline itself — loading frames, audio and the transcript only where your question needs them. Long videos stay accurate and cheap, and questions like "at what second does X happen?" are answered directly.

No model selection — video analysis always uses Kolbo's video-understanding model. Pick a tier with quality instead.

This endpoint accepts an optional project_id body field that attributes the charge to a specific project. See Projects.

Endpoint

POST /api/v1/analyze/video

Synchronous — there is no generation id and nothing to poll. The response is returned when the analysis is done; the server's socket timeout for this route is 10 minutes, so set your HTTP client timeout accordingly. If the agentic call has not finished within about 4 minutes, Kolbo falls back to standard (non-agentic) analysis in the same request instead of failing.

Rate limited by the shared SDK generation bucket: 30 requests per minute per account. Rejected or failed requests do not count. See Errors & Limits.

Request Body

Field	Type	Required	Description
`video_url`	string	No*	Publicly reachable `http(s)` URL of a video file (a Kolbo media URL from Media Library or any public direct file link). Internal / private-network addresses are rejected. A `youtube.com` / `youtu.be` link passed here is also treated as YouTube
`youtube_url`	string	No*	A `youtube.com` / `youtu.be` link. Any other host returns `400`
`prompt`	string	No	Your question or task ("At what timestamp does the logo appear?", "Count the speakers", "Summarize the three main arguments"). Must be a string if sent. Omit for a full description plus a verbatim transcript. Only the first 2,000 characters are used
`quality`	string	No	`standard` (default, `gemini-3.5-flash-lite`) or `hq` (`gemini-3.7-flash`) — higher accuracy for short clips, at a higher token price. Any other value returns `400`
`project_id`	string	No	Attribute the charge to a specific project

*One of video_url or youtube_url is required. Each call analyzes one video — both fields are single strings, not arrays. If you send both, video_url is used and youtube_url is ignored.

Local files: upload them first via the Media Library upload endpoint and pass the returned URL.

Response

{
  "success": true,
  "analysis": "[Measured source video metadata]\nVideo 1: Display dimensions: 1920x1080; aspect ratio: 16:9; ...\n\nThe logo first appears at 0:42, bottom-left ...",
  "model": "gemini-3.5-flash-lite",
  "agentic": true,
  "usage": { "input_tokens": 18420, "output_tokens": 1210 },
  "credits_used": 2
}

Field	Description
`success`	`true` on success
`analysis`	The answer / description text. The text starts with a `[Measured source video metadata]` block (display dimensions, aspect ratio, orientation, duration, frame rate, rotation; or a "Source metadata unavailable" line when the video could not be probed) before the model's answer
`model`	The analyzer model identifier for the requested tier: `gemini-3.5-flash-lite` (`standard`) or `gemini-3.7-flash` (`hq`)
`agentic`	`true` when the timeline-navigating mode ran. If agentic mode fails or times out, the same model answers in standard mode and this is `false`. It is also `false` when the video could not be handed to the provider by URL and was sent inline instead (small files only)
`usage`	`{ input_tokens, output_tokens }` the charge was computed from, or `null` if the provider reported none. In agentic mode, on-demand frame/audio/transcript loads count as input and reasoning tokens count as output
`credits_used`	Credits deducted for this call, or `null` if the deduction failed (the analysis is still returned)

Errors

Status	`code`	When
`400`	`INVALID_INPUT`	Neither `video_url` nor `youtube_url`; URL is not `http(s)`; `youtube_url` is not a YouTube link; URL points to an internal address; `quality` is not `standard` / `hq`
`400`	`INVALID_PROMPT`	`prompt` sent as a non-string
`400`	`SDK_PROJECT_INVALID_ID`	`project_id` is not a valid id
`403`	`INSUFFICIENT_CREDITS`	Balance check failed before analysis started. Body also carries `balance`, `required` and `pricing_url`
`403`	`SDK_PROJECT_ACCESS_DENIED`	You lack `edit` permission on that project
`404`	`SDK_PROJECT_NOT_FOUND`	`project_id` not found or not accessible
`429`	—	Rate limit exceeded (see above)

If the video cannot be loaded (unreachable URL, not a video, unsupported format) the request fails with an error and nothing is charged.

curl -X POST https://api.kolbo.ai/api/v1/analyze/video \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://media.kolbo.ai/.../launch.mp4", "prompt": "At what timestamp does the product price appear on screen?"}'

YouTube summary

curl -X POST https://api.kolbo.ai/api/v1/analyze/video \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{"youtube_url": "https://www.youtube.com/watch?v=...", "prompt": "Summarize the talk and list every tool mentioned with its timestamp"}'

Full transcript + description

curl -X POST https://api.kolbo.ai/api/v1/analyze/video \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://media.kolbo.ai/.../interview.mp4", "quality": "hq"}'

Transcription — when you need SRT subtitle files or word-level timings
Chat — attach a video to a chat message; the same video understanding runs behind any chat model

Video Analysis

Endpoint

Request Body

Response

Errors

Billing

Examples

Timestamp question

YouTube summary

Full transcript + description

On this page