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_idbody field that attributes the charge to a specific project. See Projects.
Endpoint
POST /api/v1/analyze/videoSynchronous. The response is returned when the analysis is done — allow several minutes for long videos.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
video_url | string | No* | Public https URL of the video (a Kolbo media URL from Media Library or any public file). Formats: mp4, mov, webm, mpeg, avi, 3gpp, wmv, flv |
youtube_url | string | No* | A youtube.com / youtu.be link |
prompt | string | No | Your question or task ("At what timestamp does the logo appear?", "Count the speakers", "Summarize the three main arguments"). Omit for a full description plus a verbatim transcript |
quality | string | No | standard (default) or hq — higher accuracy for short clips, at a higher token price |
project_id | string | No | Attribute the charge to a specific project |
*Exactly one of video_url or youtube_url is required.
Local files: upload them first via the Media Library upload endpoint and pass the returned URL.
Response
{
"success": true,
"analysis": "The 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 |
|---|---|
analysis | The answer / description text |
agentic | true when the timeline-navigating mode ran. If the provider declines it, the same model answers in standard mode and this is false |
usage | Token usage the charge was computed from |
credits_used | Credits deducted for this call (null if billing was deferred) |
Billing
Billed by the analyzer's real token usage (see Credits & Billing). Agentic navigation loads only the parts of the video the question needs, so a long video usually costs far less than its length suggests.
Examples
Timestamp question
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"}'Related
- 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