Leitfaden zur agentischen Videoanalyse-API von Gemini

Eine zweistündige Vorlesung und ein 20-sekündiger Produktclip brauchen nicht dieselbe Analysemethode. Für lange Videos oder Fragen zu bestimmten Momenten ist Geminis neuer Modus für agentische Videoanalyse der bessere Ausgangspunkt. Googles Einsparungen von „bis zu“ 66 Prozent sind allerdings Benchmark-Werte – keine garantierte Reduzierung jeder API-Rechnung um 66 Prozent.

Die Verarbeitungsart richtet sich nach der Aufgabe – nicht nach der Videolänge

Geminis agentische Videoanalyse spielt ihre Stärken aus, wenn bestimmte Momente gefunden oder erneut untersucht werden müssen. Der statische Modus bleibt die unkompliziertere Wahl, wenn ein kurzer Clip schnell verarbeitet werden soll oder jedes Abtastintervall gleichmäßig berücksichtigt werden muss.

Google nennt zum Start vier Anwendungsfälle: das Auffinden von Momenten unter einer Sekunde, die Suche nach der „Nadel im Heuhaufen“ in langen Videos, die Erkennung von Anomalien sowie das Zählen von Aktionen oder Objekten. Die offizielle Ankündigung beschreibt Beispiele von 10-minütigen Anleitungen über 90-minütige Vorlesungen bis hin zu mehrstündigen Aufnahmen.

Eine veröffentlichte Grenze für die Videolänge gibt es nicht: Ein fünfminütiges Video mit einem versteckten Ereignis kann agentische Verarbeitung rechtfertigen, während eine längere, gleichförmige Aufnahme damit nicht automatisch besser aufgehoben ist.

Eine Funktion, zwei API-Formate

„Agentisch“ ist kein universelles JSON-Feld. Googles Startbeispiel verwendet die Interactions API und setzt processing: "agentic" innerhalb des Video-Inputs. Beim GenerateContent-Weg wird die Medienverarbeitung dagegen direkt am Media-Part angegeben.

Interactions API: Die Verarbeitung am Video-Input festlegen

Googles Ankündigungsbeitrag zeigt für ein YouTube-Video folgendes Python-Muster:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input=[
        {
            "type": "video",
            "uri": "https://youtu.be/7Z5Vy9JBANs",
            "processing": "agentic"
        },
        {
            "type": "text",
            "text": "What are the 3 most important announcements in this keynote?",
        },
    ],
)

print(interaction.output_text)

Die Einstellung gehört in das Videoobjekt – nicht in ein unabhängiges Feld auf oberster Ebene.

GenerateContent: Die Medienverarbeitung am Media-Part festlegen

Die Dokumentation zur Gemini-Videoanalyse beschreibt das GenerateContent-Format separat. In dieser Anforderungsstruktur verwendet der Medien-Input media_processing: "AGENTIC". In JavaScript lautet die entsprechende Camel-Case-Eigenschaft mediaProcessing.

Ein minimales Python-Beispiel sieht so aus:

from google import genai
from google.genai import types

client = genai.Client()
video_uri = "YOUR_VIDEO_FILE_URI"

response = client.models.generate_content(
    model="gemini-3.7-flash",
    contents=[
        types.Part.from_uri(
            file_uri=video_uri,
            mime_type="video/mp4",
            media_processing="AGENTIC",
        ),
        "Find the first product announcement and return its timestamp.",
    ],
)

print(response.text)

Bei einem lokalen Video ersetzt du YOUR_VIDEO_FILE_URI durch die URI, die der Gemini-Datei-Upload zurückgibt. Warte anschließend, bis die Datei bereit ist, bevor du den Media-Part mitsendest. Die aktuelle offizielle Dokumentation zur Videoanalyse hilft dabei, die SDK-Details für die installierte Client-Version zu überprüfen.

Übernimm beim Wechsel von client.interactions.create zu generateContent nicht einfach das Snippet der jeweils anderen API.

Was Geminis agentische Videoanalyse tatsächlich macht

Bei der statischen Videoverarbeitung wird ein Video mit einer festen Framerate abgetastet. Laut Google sind standardmäßig 1 Frame pro Sekunde eingestellt. Die Rate lässt sich über die API anpassen; anschließend erhält das Modell die abgetasteten Frames zur Analyse.

Der agentische Ablauf lässt Gemini die Zeitleiste durchsuchen und scannen, eine passende Geschwindigkeit wählen und je nach Frage visuelle Frames, Audio oder Transkripte heranziehen, statt die gesamte Aufnahme gleichmäßig zu laden:

1. Fordere den für die Frage relevanten Abschnitt oder die passende Modalität an.
2. Prüfe die zurückgegebenen Frames, Audiodaten oder das Transkript.
3. Untersuche ein engeres Zeitfenster erneut, wenn eine höhere zeitliche Genauigkeit nötig ist.

Statisches Sampling bietet Entwicklern eine klare Regel für die Abdeckung. Bei der agentischen Verarbeitung entscheidet das Modell stärker selbst, wo es hinsieht. Deshalb sollten Produktionssysteme Zeitstempel und Zählungen anhand repräsentativer Aufnahmen überprüfen.

Die Einsparungsangabe bedeutet keinen Rabatt von 66 Prozent

Google berichtet für gängige Videoanalyse-Benchmarks die folgenden Ergebnisse, wobei die größten Verbesserungen bei langen Videos hervorgehoben werden:

Geminis agentische Videoanalyse verwendet laut Googles Startankündigung die reguläre Tokenpreisstruktur der Gemini API. Eine zusätzliche Funktionsgebühr fällt nicht an. Die tatsächlichen Kosten hängen dennoch vom Modell, den abgerufenen Inhalten, der Anfrage und der Ausgabe ab. Weitere Informationen zu Token- und Modellpreisen findest du im Leitfaden zu den Preisen der Gemini 3.7 Flash API.

Bei wiederholten Fragen zu derselben Aufnahme solltest du den Videokontext cachen, sofern der API-Workflow das unterstützt. Googles praxisnahe Notizen zur Videoanalyse in Google Cloud nennen Context Caching als wichtigen Hebel für wiederholte Analysen und niedrigere Kosten.

Verfügbarkeit und Grenzen des Rollouts

Agentische Videoanalyse ist eine Verarbeitungsfunktion für drei Modelle der Flash-Familie und kein separat angekündigtes Videomodell. Google zufolge wurde sie am 1. September 2026 für die folgenden Modelle und Oberflächen eingeführt:

Der geplante Rollout für die Consumer-App und YouTube ist kein Beleg dafür, dass die Funktion bereits für jedes Konto verfügbar ist.

Vor dem Standardwechsel: ein Produktionstest mit vier Läufen

Die Startankündigung nennt Leistungsversprechen, zeigt aber nicht, wie sich der Modus bei deinen konkreten Videos verhält. Stelle deshalb einen kleinen Testsatz zusammen, bevor du einen bestehenden statischen Workflow ersetzt.

1. Zeitstempel abrufen: Verwende Clips mit Szenenwechseln, kurzen Auftritten und einem Ereignis, bei dem die exakte Start- und Endzeit wichtig ist. Vergleiche die zurückgegebenen Zeitstempel mit einer von Menschen geprüften Referenz.
2. Schnelle Aktionen zählen: Nutze Aufnahmen mit wiederholten Bewegungen oder Objekten, die durchs Bild laufen. Prüfe die Gesamtzahl und ob die Antwort das Zählfenster nachvollziehbar erläutert.
3. Audio und Transkript abgleichen: Stelle Fragen, bei denen gesprochene Worte und sichtbare Handlung voneinander abweichen. Kontrolliere, dass die Antwort nicht stillschweigend eine Modalität durch die andere ersetzt.
4. Betriebsverhalten prüfen: Verarbeite dieselben Dateien in beiden Modi und protokolliere Input- und Output-Tokens, Latenz, Wiederholungsversuche, leere Antworten, übersehene Ereignisse sowie das Ergebnis des statischen Fallbacks. Behalte den Fallback bei, wenn die selektive Abfrage Belege übersieht oder eine nicht akzeptable Verzögerung verursacht.

Leite aus dem Startbeitrag keine starre Regel wie „Agentisch ab X Minuten“ ab. Die veröffentlichten Informationen sprechen für eine aufgabenbasierte Auswahl, nicht für eine universelle Grenze bei der Videolänge.

FAQ zur agentischen Videoanalyse-API von Gemini

Ist die agentische Videoanalyse ein neues Gemini-Modell?

Nein. Google beschreibt sie als Videoanalyse-Funktion, die für Gemini 3.7 Flash, Gemini 3.6 Flash und Gemini 3.5 Flash-Lite verfügbar ist.

Kann ich statt einer YouTube-URL ein hochgeladenes Video verwenden?

Ja. Google nennt hochgeladene Videodateien und YouTube-Videos als unterstützte API-Eingaben. Bei einer lokalen Datei lädst du sie zunächst hoch und übergibst anschließend die zurückgegebene Datei-URI im Media-Part, sobald die Verarbeitung abgeschlossen ist.

Kostet die agentische Videoverarbeitung extra?

Google zufolge fällt keine zusätzliche Funktionsgebühr an. Es gelten die normalen Tokenpreise der Gemini API. Die endgültige Rechnung hängt vom abgerufenen Inhalt und vom restlichen Umfang der Anfrage ab.

Verarbeite einen repräsentativen Testsatz in beiden Modi und behalte die agentische Verarbeitung nur dort als Standard bei, wo die gemessene Qualität der Belege und die Tokenkosten zu den Zielvorgaben deiner Anwendung passen.