Video analyseren met de Gemini API

Videoanalyse met Gemini

Gemini verwerkt video door frames te bemonsteren (standaard 1 fps) en de audio-track te analyseren als geintegreerde multimodale input. Dit maakt analyses mogelijk die zowel visuele als auditieve informatie combineren: wat er gezegd wordt, wat er te zien is, en hoe die twee zich tot elkaar verhouden.

Typische toepassingen: beveiligingsvideo doorzoeken, content-moderatie, educatieve video doorzoekbaar maken, productdemonstraties automatisch documenteren, en sport- of media-analyse.

Video uploaden en verwerken

Upload het bestand via de Files API. Een upload heeft even verwerkingstijd nodig voordat je er een prompt op kunt loslaten, dus poll je op de status tot het bestand ACTIVE is.

from google import genai
import time
import os

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

video_file = client.files.upload(file="productdemo.mp4")
print(f"Upload gestart: {video_file.name}")

while video_file.state.name == "PROCESSING":
    print("Video wordt verwerkt...")
    time.sleep(10)
    video_file = client.files.get(name=video_file.name)

if video_file.state.name == "FAILED":
    raise RuntimeError("Verwerking mislukt")

print(f"Status: {video_file.state.name}")
print(f"URI: {video_file.uri}")

Videoverwerking duurt langer dan audio of afbeeldingen. Geupload materiaal blijft standaard 48 uur beschikbaar via de Files API.

Video samenvatten

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        video_file,
        """Geef een gestructureerde samenvatting van deze video:
        - Onderwerp en doel van de video
        - Tijdlijn van hoofdonderwerpen (met tijdstempels)
        - Belangrijkste inzichten of conclusies
        - Aanbevolen doelgroep""",
    ],
)
print(response.text)

YouTube-URL meesturen zonder te uploaden

Je kunt een publieke YouTube-URL nu rechtstreeks meesturen in plaats van eerst te downloaden en uploaden. Dat scheelt een hele uploadstap.

from google.genai import types

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri="https://www.youtube.com/watch?v=VIDEO_ID")
            ),
            types.Part(text="Vat deze video samen in vijf bullets met tijdstempels."),
        ]
    ),
)
print(response.text)

Specifieke scenes opzoeken

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        video_file,
        "Op welke tijdstempels wordt het installatieproces gedemonstreerd? Geef een beschrijving per stap.",
    ],
)
print(response.text)

Alleen een fragment analyseren

Je hoeft niet de hele video te laten verwerken. Met video_metadata knip je een fragment uit en kun je desgewenst de bemonsteringssnelheid (fps) verhogen, bijvoorbeeld om snelle handelingen beter te volgen.

from google.genai import types

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri=video_file.uri, mime_type="video/mp4"),
                video_metadata=types.VideoMetadata(
                    start_offset="120s",
                    end_offset="180s",
                    fps=5,
                ),
            ),
            types.Part(text="Beschrijf stap voor stap wat er in dit fragment gebeurt."),
        ]
    ),
)
print(response.text)

Visuele gebeurtenissen detecteren

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        video_file,
        """Detecteer en rapporteer:
        1. Alle scene-overgangen (tijdstempel plus beschrijving)
        2. Tekst die op scherm verschijnt
        3. Personen die in beeld komen (beschrijving, geen identificatie)
        4. Objecten of producten die prominent zichtbaar zijn

        Formaat: JSON-array per categorie.""",
    ],
)
print(response.text)

Content-moderatie voor video

import json

def moderate_video(video_path: str) -> dict:
    video_file = client.files.upload(file=video_path)

    while video_file.state.name == "PROCESSING":
        time.sleep(10)
        video_file = client.files.get(name=video_file.name)

    response = client.models.generate_content(
        model="gemini-3.5-flash",
        contents=[
            video_file,
            """Analyseer deze video op ongepaste inhoud.
            Geef een score 0-100 voor elk van de volgende categorieen:
            - geweld (0=geen, 100=extreem)
            - expliciete inhoud (0=geen, 100=extreem)
            - hatelijke uitspraken (0=geen, 100=extreem)
            - misleidende informatie (0=geen, 100=zeker)

            Geef ook tijdstempels van problematische fragmenten.
            Formaat: JSON.""",
        ],
        config=types.GenerateContentConfig(response_mime_type="application/json"),
    )
    return json.loads(response.text)

Gebruik response_mime_type="application/json" zodat het model gegarandeerd geldige JSON teruggeeft in plaats van tekst met code-fences eromheen.

Transcriptie met video-context

Anders dan pure audioverwerking kan Gemini bij video ook de context gebruiken van wat er zichtbaar is:

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        video_file,
        """Maak een transcriptie van alles wat gezegd wordt.
        Voeg toe wat er tegelijk op scherm te zien is als dat relevant is voor de context.
        Gebruik formaat: [tijdstempel] [AUDIO] tekst / [BEELD] beschrijving""",
    ],
)
print(response.text)

Video doorzoekbaar maken

import json

def create_video_index(video_path: str) -> list:
    video_file = client.files.upload(file=video_path)
    while video_file.state.name == "PROCESSING":
        time.sleep(10)
        video_file = client.files.get(name=video_file.name)

    response = client.models.generate_content(
        model="gemini-3.5-flash",
        contents=[
            video_file,
            """Maak een doorzoekbare index van deze video.
            Maak voor elk onderwerp of elke scene een entry met:
            - start_time (MM:SS)
            - end_time (MM:SS)
            - topic (korte titel)
            - description (1-2 zinnen)
            - keywords (array van zoekwoorden)

            Retourneer een JSON-array.""",
        ],
        config=types.GenerateContentConfig(response_mime_type="application/json"),
    )
    return json.loads(response.text)

Ondersteunde formaten en limieten

De onderstaande waarden gelden voor de Gemini API per juni 2026. Limieten en tokenkosten kunnen per model verschillen, dus controleer bij twijfel de officiele documentatie.