01
Before you start
Agentic video understanding currently supports Gemini 3.7 Flash, Gemini 3.6 Flash and Gemini 3.5 Flash-Lite. You need Gemini API access plus a supported video input.
Static processing remains the default. To use the new behavior through the Interactions API, set the video's processing field to agentic.
02
Upload a reusable video with the Files API
For large, long or reusable recordings, Google's video guide recommends the Files API. It currently lists limits of 20 GB for paid access and 2 GB for free access. Wait until an uploaded file reaches an active state before using its URI in an interaction.
03
Python implementation pattern
Using the current google-genai SDK, create a client, upload or reference a video, then call client.interactions.create with a supported model such as gemini-3.7-flash.
A minimal video item contains type: "video", a video URI, the MIME type and processing: "agentic". Add the user's retrieval question as a separate text input.
04
JavaScript and REST use the same per-video setting
The JavaScript SDK follows the same structure through ai.interactions.create. In REST, send the request to the Interactions API and include "processing": "agentic" on the video object.
Because processing is attached to each video, you can mix modes in one request: for example, agentic processing for a long lecture and static processing for a short experiment clip.
05
Analyze a public YouTube video
Google's launch announcement says agentic video understanding works with uploaded videos and public YouTube videos. You can pass a public YouTube URL as the video URI and use agentic processing on supported models.
YouTube URL support is still Preview. Google currently says the feature is available at no charge, but pricing and rate limits are likely to change, so keep that dependency easy to update.
06
Write prompts that benefit from selective inspection
- Find every moment where a speaker mentions a specific feature.
- Locate the exact transition where an interface changes state.
- Identify the strongest short explanation of a topic inside a long recording.
- Compare transcript claims with what is visibly happening on screen.
Broad prompts such as a generic summary can still work, but targeted retrieval gives the model a clearer reason to navigate the timeline selectively.
07
Understand pricing before production
Agentic video has no separate add-on fee. Standard token pricing for the selected Gemini model still applies. Gemini 3.7 Flash is currently listed at $0.75/M input and $3.75/M output on the standard paid tier.
Google's up-to-88% token and up-to-66% cost reductions are vendor benchmark results. Measure actual token use, latency and answer quality on your own workload rather than assuming those maximums.
08
Common implementation mistakes
- Forgetting the processing field and unknowingly testing static mode.
- Using a Gemini model that does not currently support agentic video.
- Treating YouTube Preview behavior as permanent.
- Assuming benchmark savings apply equally to every video.
- Using agentic mode automatically for short clips without comparing static processing.
For production systems, log model, processing mode, token usage, latency and task outcome so the choice between static and agentic processing can be evidence-driven.
Sources
Primary and supporting sources
Facts were rechecked against the linked sources immediately before publication. Pricing, product availability and rollout status can change.