Videos verstehen

Informationen zum Erstellen von Videos finden Sie in der Anleitung zu Gemini Omni Flash.

Gemini-Modelle können Videos verarbeiten und so viele neue Anwendungsfälle für Entwickler ermöglichen, für die in der Vergangenheit domänenspezifische Modelle erforderlich gewesen wären. Zu den Vision-Funktionen von Gemini gehören unter anderem die Möglichkeit, Videos zu beschreiben, zu segmentieren und Informationen daraus zu extrahieren, Fragen zu Videoinhalten zu beantworten und auf bestimmte Zeitstempel in einem Video zu verweisen.

Sie können Videos auf folgende Weise als Eingabe für Gemini bereitstellen:

Eingabemethode Max. Größe Empfohlener Anwendungsfall
File API 20 GB (kostenpflichtig) / 2 GB (kostenlos) Große Dateien (über 100 MB), lange Videos (über 10 Minuten), wiederverwendbare Dateien
Cloud Storage-Registrierung 2 GB (pro Datei, keine Speicherlimits) Große Dateien (über 100 MB), lange Videos (über 10 Minuten), persistente, wiederverwendbare Dateien
Inlinedaten unter 100 MB Kleine Dateien (unter 100 MB), kurze Dauer (unter 1 Minute), einmalige Eingaben
YouTube-URLs – Öffentliche YouTube-Videos

Hinweis: Die File API wird für die meisten Anwendungsfälle empfohlen, insbesondere für Dateien, die größer als 100 MB sind, oder wenn Sie die Datei in mehreren Anfragen wiederverwenden möchten.

Weitere Informationen zu anderen Methoden für die Dateieingabe, z. B. die Verwendung externer URLs oder in Google Cloud gespeicherter Dateien, finden Sie in der Anleitung zu Methoden für die Dateieingabe.

Videodatei hochladen

Der folgende Code lädt ein Beispielvideo herunter, lädt es mit der Files API, wartet, bis es verarbeitet wurde, und verwendet dann die hochgeladene Dateireferenz, um das Video zusammenzufassen.

Python

from google import genai

client = genai.Client()

myfile = client.files.upload(file="path/to/sample.mp4")

response = client.models.generate_content(
    model="gemini-3.8-flash", contents=[myfile, "Summarize this video. Then create a quiz with an answer key based on the information in this video."]
)

print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/sample.mp4",
    config: { mimeType: "video/mp4" },
  });

  const response = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: createUserContent([
      createPartFromUri(myfile.uri, myfile.mimeType),
      "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
    ]),
  });
  console.log(response.text);
}

await main();

Ok

uploadedFile, _ := client.Files.UploadFromPath(ctx, "path/to/sample.mp4", nil)

parts := []*genai.Part{
    genai.NewPartFromText("Summarize this video. Then create a quiz with an answer key based on the information in this video."),
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
)

fmt.Println(result.Text())

REST

VIDEO_PATH="path/to/sample.mp4"
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}"<)
NUM_BYTES=$(wc -c  "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO

tmp_header_file=upload-header.tmp

echo "Starting file upload..."
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D ${tmp_header_file} \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}&qu>ot; \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2 /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

echo "Upl>oading vide>o data..."
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2 /dev/null  file_info.json

file_uri=$(jq -r ".file.uri" file_info.json)
echo file_uri=$file_uri

echo "File uploaded successfully. File URI: ${file_uri}"

# --- 3. Generate content using the uploaded video file ---
echo "Generating content from video..."
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: applicati>on/json'>; \
    -X POST \
    -d '{
      "contents": [{
        &quot;parts":[
          {"file_data":{"mime_type": "'"${MIME_TYPE}"'", "file_uri": "'"${file_uri}"'"}},
          {"text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}]
        }]
      }' 2 /dev/null  response.json

jq -r ".candidates[].content.parts[].text" response.json

Verwenden Sie immer die Files API, wenn die Gesamtgröße der Anfrage (einschließlich Datei, Text-Prompt, Systemanweisungen usw.) größer als 20 MB ist, die Videodauer erheblich ist oder wenn Sie dasselbe Video in mehreren Prompts verwenden möchten. Die File API akzeptiert Videodateiformate direkt.

Weitere Informationen zum Arbeiten mit Mediendateien finden Sie unter Files API.

Videodaten inline übergeben

Anstatt eine Videodatei mit der File API hochzuladen, können Sie kleinere Videos direkt in der Anfrage an generateContent übergeben. Dies eignet sich für kürzere Videos mit einer Gesamtgröße der Anfrage von unter 20 MB.

Hier ein Beispiel für die Bereitstellung von Inlinedaten für Videos:

Python

from google import genai
from google.genai import types

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(data=video_bytes, mime_type='video/mp4')
            ),
            types.Part(text='Please summarize the video in 3 sentences.';)
        ]
    )
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const base64VideoFile = fs.readFileSync("path/to/small-sample.mp4", {
  encoding: "base64",
});

const contents = [
  {
    inlineData: {
      mimeType: "video/mp4",
      data: base64VideoFile,
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: contents,
});
console.log(response.text);

REST

VIDEO_PATH=/path/to/your/video.mp4

if [[ "$(base64 --vers>&ion 21)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {
              "inline_data": {
                "mime_type":"video/mp4",
                "data": "'$(base64 $B64FLAGS> $VIDEO_PATH)'"
              }
            },
            {"text": "Please summarize the video in 3 sentences."}
        ]
      }]
    }' 2 /dev/null

YouTube-URLs übergeben

Sie können YouTube-URLs wie folgt direkt als Teil Ihrer Anfrage an die Gemini API übergeben:

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=9hE5-98ZeCg')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const contents = [
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: contents,
});
console.log(response.text);

Ok

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

func main() {
  ctx := context.Background()
  client, err := genai.NewClient(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }

  parts := []*genai.Part{
      genai.NewPartFromText("Please summarize the video in 3 sentences."),
      genai.NewPartFromURI("https://www.youtube.com/watch?v=9hE5-98ZeCg","video/mp4"),
  }

  contents := []*genai.Content{
      genai.NewContentFromParts(parts, genai.RoleUser),
  }

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-3.8-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
            {"text": "Please summarize the video in 3 sentences."},
            {
              "file_data": {
                "file_uri": "https>://www.youtube.com/watch?v=9hE5-98ZeCg"
              }
            }
        ]
      }]
    }' 2 /dev/null

Beschränkungen :

  • Im kostenlosen Abo können Sie pro Tag maximal 8 Stunden YouTube-Video hochladen.
  • Im kostenpflichtigen Abo gibt es keine Beschränkung basierend auf der Videolänge.
  • Bei Modellen vor Gemini 2.5 können Sie pro Anfrage nur ein Video hochladen. Bei Gemini 2.5 und neueren Modellen können Sie pro Anfrage maximal 10 Videos hochladen.
  • Sie können nur öffentliche Videos hochladen (keine privaten oder nicht gelisteten Videos).

Agentisches Videoverständnis

Standardmäßig wird bei Videoeingaben eine statische Verarbeitung verwendet (Extrahieren von Frames mit 1 FPS). Die Modelle Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash und 3.5 Flash Lite unterstützen auch das agentische Videoverständnis, bei dem das Modell die Video- Timeline dynamisch durchsucht, Transkripte selektiv prüft und Frame- Raten und Auflösung basierend auf dem Prompt spontan anpasst.

Modus Beschreibung Unterstützte Modelle
Statisch (Standard) Extrahiert Frames mit einer festen Rate (1 FPS) und platziert sie in einem Durchgang in den Kontext. Funktioniert gut für kurze Clips. Alle Gemini-Modelle
Agentisch Das Modell durchsucht die Video-Timeline dynamisch und lädt nur die Inhalte, die basierend auf dem Prompt benötigt werden. Bis zu 88% tokeneffizienter und ~7% höhere Qualität bei langen Inhalten. Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite

Verarbeitungsmodus auswählen

Als allgemeine Richtlinie sollten Sie mit dem agentischen Modus beginnen, insbesondere wenn Sie die Antwortqualität oder die Tokeneffizienz optimieren möchten.

  • Agentisch:Videos im Langformat oder Abfragen, die auf bestimmte Momente abzielen. Das Modell durchsucht die Timeline dynamisch, um kontextbezogene Informationen zu finden, ohne das Kontextfenster zu füllen.
  • Statisch:Latenzempfindliche Anfragen zu kurzen Clips (unter 5 Minuten) oder Fälle, in denen eine präzise Analyse auf Frame-Ebene für den gesamten Clip erforderlich ist.

Verarbeitungsmodus festlegen

Python

import time
from google import genai
from google.genai import types

client = genai.Client()

video_file = client.files.upload(file="path/to/lecture.mp4")

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

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_uri(
            file_uri=video_file.uri,
            mime_type=video_file.mime_type,
            media_processing="AGENTIC",
        ),
        "What are the three main arguments presented?",
    ],
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

let videoFile = await ai.files.upload({
  file: "path/to/lecture.mp4",
  config: { mimeType: "video/mp4" },
});

while (videoFile.state === "PROCESSING&>quot;) {
  await new Promise((resolve) = setTimeout(resolve, 2000));
  videoFile = await ai.files.get({ name: videoFile.name });
}

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: videoFile.uri,
            mimeType: videoFile.mimeType,
          },
          mediaProcessing: "AGENTIC",
        },
        { text: "What are the three main arguments presented?" },
      ],
    },
  ],
});
console.log(response.text);

Ok

uploadedFile, _ := client.Files.UploadFromPath(ctx, "path/to/lecture.mp4", nil)
parts := []*genai.Part{
    {
        &FileData: genai.FileData{
            FileURI:  uploadedFile.URI,
            MIMEType: uploadedFile.MIMEType,
        },
        MediaProcessing: genai.MediaProcessingAgentic,
    },
    genai.NewPartFromText("What are the three main arguments presented?"),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [
        {
          "file_data": {
            "file_uri": "'${file_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing&quot;: "AGENTIC"
        },
        {"text": "What are the three main arguments presented?"}
      ]
    }]
  }'

Hinweis:Prüfen Sie response.candidates[0].content.parts, um zu bestätigen, dass die agentische Verarbeitung verwendet wurde. Das Vorhandensein von tool_call- und tool_response-Teilen mit dem Tooltyp MEDIA_PROCESSING zeigt an, dass das Modell das Video dynamisch durchsucht hat.

Hinweis:Im Gegensatz zu anderen serverseitigen Tools (z. B. Google Suche oder URL-Kontext) ist es bei der agentischen Videoverarbeitung nicht erforderlich, include_server_side_tool_invocations=True in ToolConfig festzulegen, damit Toolaufrufe und -ergebnisse zurückgegeben oder gestreamt werden. Die tool_call- und tool_response-Teile für die Videonavigation werden automatisch zurückgegeben, wenn media_processing="AGENTIC" für einen beliebigen Eingabeteil festgelegt ist.

Antwortstruktur

Wenn die agentische Verarbeitung aktiviert ist, enthält die Antwort zusätzliche Teile, die die interne Navigationsspur offenlegen:

  • tool_call Teile (tool_type: "MEDIA_PROCESSING"): werden jedes Mal ausgegeben, wenn das Modell ein Videosegment oder ein Audiotranskript anfordert.
  • tool_response Teile (tool_type: "MEDIA_PROCESSING"): das Ergebnis jeder Ladeoperation.

Sie müssen diese Teile nicht manuell verarbeiten oder beantworten. Übergeben Sie die vollständige Antwort als Unterhaltungschronik und sie werden automatisch verarbeitet.

Wenn include_thoughts=True in ThinkingConfig festgelegt ist, werden die Begründungsschritte als thought: true-Teile zwischen den Toolaufruf-/Antwortpaaren angezeigt. Wenn Gedanken deaktiviert sind, wird der Gedankentext weggelassen, aber die Toolteile sind weiterhin vorhanden.

Das folgende Beispiel zeigt die Antwortnutzlast mit verschachtelten Toolaufruf- und Antwortteilen:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "thought": true,
            "text": "Inspecting transcript for key discussion topics..."
          },
          {
            "thought_signature": "sig_A",
            "tool_call": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought_signature": "sig_B",
            "tool_response": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought": true,
            "text": "Loading visual frames to verify slide content..."
          },
          {
            "thought_signature": "sig_C",
            "tool_call": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought_signature": "sig_D",
            "tool_response": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought": true,
            "text": "Synthesizing answer from gathered evidence..."
          },
          {
            "text": "The three main arguments presented in the lecture are...",
            "thought_signature": "sig_E"
          }
        ]
      }
    }
  ]
}

Verarbeitungsmodi für verschiedene Videos kombinieren

Sie können für jeden Videoteil in derselben Anfrage unterschiedliche Verarbeitungsmodi festlegen:

Python

from google import genai
from google.genai import types

client = genai.Client()

lecture = client.files.upload(file="path/to/long-lecture.mp4")
experiment = client.files.upload(file="path/to/short-experiment.mp4")

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_uri(
            file_uri=lecture.uri,
            mime_type=lecture.mime_type,
            media_processing="AGENTIC",  # Use agentic video understanding
        ),
        types.Part.from_uri(
            file_uri=experiment.uri,
            mime_type=experiment.mime_type,
            media_processing="STATIC",  # Use static processing
        ),
        "Compare the lecture content with the experiment results.",
    ],
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const lecture = await ai.files.upload({
  file: "path/to/long-lecture.mp4",
  config: { mimeType: "video/mp4" },
});
const experiment = await ai.files.upload({
  file: "path/to/short-experiment.mp4",
  config: { mimeType: "video/mp4" },
});

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: lecture.uri,
            mimeType: lecture.mimeType,
          },
          mediaProcessing: "AGENTIC", // Use agentic video understanding
        },
        {
          fileData: {
            fileUri: experiment.uri,
            mimeType: experiment.mimeType,
          },
          mediaProcessing: "STATIC", // Use static processing
        },
        { text: "Compare the lecture content with the experiment results." },
      ],
    },
  ],
});
console.log(response.text);

Ok

lecturePart := &genai.Part{
    FileData: &genai.FileData{
        FileURI:  lectureFile.URI,
        MIMEType: lectureFile.MIMEType,
    },
    MediaProcessing: genai.MediaProcessingAgentic, // Use agentic
}
experimentPart := &genai.Part{
    FileData: &genai.FileData{
        FileURI:  experimentFile.URI,
        MIMEType: experimentFile.MIMEType,
    },
    MediaProcessing: genai.MediaProcessingStatic, // Use static
}
parts := []*genai.Part{
    lecturePart,
    experimentPart,
    genai.NewPartFromText("Compare the lecture content with the experiment results."),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [
        {
          "file_data": {
            "file_uri": "'${lecture_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "AGENTIC"
        },
        {
          "file_data": {
            "file_uri": "'${experiment_uri}'",
            "mime_type": &quot;video/mp4"
          },
          "media_processing": "STATIC"
        },
        {"text": "Compare the lecture content with the experiment results."}
      ]
    }]
  }'

Kontext-Caching für lange Videos verwenden

Bei Videos, die länger als 10 Minuten sind, oder wenn Sie mehrere Anfragen für dieselbe Videodatei stellen möchten, verwenden Sie Kontext-Caching, um Kosten zu senken und die Latenz zu verbessern. Mit Kontext-Caching können Sie das Video einmal verarbeiten und die Tokens für nachfolgende Anfragen wiederverwenden. Das ist ideal für Chatsitzungen oder wiederholte Analysen von langen Inhalten.

Auf Zeitstempel im Inhalt verweisen

Sie können Fragen zu bestimmten Zeitpunkten im Video stellen, indem Sie Zeitstempel im Format MM:SS verwenden.

Python

prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?" # Adjusted timestamps for the NASA video

JavaScript

const prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?";

Ok

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
          // Adjusted timestamps for the NASA video
        genai.NewPartFromText("What are the examples given at 00:05 and " +
            "00:10 supposed to show us?"),
    }

REST

PROMPT="What are the examples given at 00:05 and 00:10 supposed to show us?"

Detaillierte Insights aus Videos extrahieren

Gemini-Modelle bieten leistungsstarke Funktionen zum Verstehen von Videoinhalten, indem sie Informationen aus den Audio- und visuellen Streams verarbeiten. So können Sie eine Vielzahl von Details extrahieren, z. B. Beschreibungen des Geschehens in einem Video erstellen und Fragen zu den Inhalten beantworten.

Für visuelle Beschreibungen nimmt das Modell mit einer Rate von 1 Frame pro Sekunde (FPS) Stichproben aus dem Video. Diese Standard-Samplingrate eignet sich gut für die meisten Inhalte, aber es kann sein, dass Details in Videos mit schnellen Bewegungen oder schnellen Szenenwechseln nicht erfasst werden. Für solche Inhalte mit schnellen Bewegungen sollten Sie eine benutzerdefinierte Framerate festlegen.

Python

prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

JavaScript

const prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.";

Ok

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
        genai.NewPartFromText("Describe the key events in this video, providing both audio and visual details. " +
      "Include timestamps for salient moments."),
    }

REST

PROMPT="Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

Videoverarbeitung anpassen

Sie können die Videoverarbeitung in der Gemini API anpassen, indem Sie Clipping-Intervalle festlegen oder eine benutzerdefinierte Framerate-Samplingrate angeben. Diese Anpassungsoptionen werden nur unterstützt, wenn das Video im Modus "static" verarbeitet wird.

Clipping-Intervalle festlegen

Sie können Videos zuschneiden, indem Sie videoMetadata mit Start- und End-Offsets angeben.

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-3.8-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=XEzRZ35urlk'),
                video_metadata=types.VideoMetadata(
                    start_offset='1250s',
                    end_offset='1570s'
                )
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-3.8-flash';

async function main() {
const contents = [
  {
    role: 'user',
    parts: [
      {
        fileData: {
          fileUri: 'https://www.youtube.com/watch?v=9hE5-98ZeCg',
          mimeType: 'video/*',
        },
        videoMetadata: {
          startOffset: '40s',
          endOffset: '80s',
        }
      },
      {
        text: 'Please summarize the video in 3 sentences.',
      },
    ],
  },
];

const response = await ai.models.generateContent({
  model,
  contents,
});

console.log(response.text)

}

await main();

Benutzerdefinierte Framerate festlegen

Sie können eine benutzerdefinierte Framerate-Samplingrate festlegen, indem Sie ein fps-Argument an videoMetadata übergeben.

Python

from google import genai
from google.genai import types

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-3.8-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(
                    data=video_bytes,
                    mime_type='video/mp4'),
                video_metadata=types.VideoMetadata(fps=5)
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

Standardmäßig wird 1 Frame pro Sekunde (FPS) aus dem Video gesampelt. Für lange Videos sollten Sie eine niedrige FPS-Rate (unter 1) festlegen. Das ist besonders nützlich für meist statische Videos (z.B. Vorträge). Verwenden Sie eine höhere FPS-Rate für Videos, die eine detaillierte zeitliche Analyse erfordern, z. B. zum Verstehen von schnellen Aktionen oder zur Bewegungserkennung bei hoher Geschwindigkeit.

Unterstützte Videoformate

Gemini unterstützt die folgenden MIME-Typen für Videoformate:

  • video/mp4
  • video/mpeg
  • video/quicktime
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

Technische Details zu Videos

  • Unterstützte Modelle und Kontext: Alle Gemini-Modelle können Videodaten verarbeiten.
    • Modelle mit einem Kontextfenster von 1 Million Tokens können standardmäßig Videos mit einer Länge von bis zu 3 Stunden (bei niedriger Media-Auflösung) oder bis zu 1 Stunde (bei hoher Media-Auflösung) verarbeiten.
  • Verarbeitungsmodi: Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite, und neuere Modelle unterstützen zwei Videoverarbeitungsmodi:
    • Statisch: Frames werden mit 1 FPS extrahiert und in den Kontext gesetzt (Standard für alle Modelle). Audio wird mit 1 kbit/s (einzelner Kanal) verarbeitet. Zeitstempel werden jede Sekunde hinzugefügt. Am besten geeignet für kurze Clips oder wenn jeder Frame wichtig ist (z. B. bei der Frame-by-Frame-Analyse). Beachten Sie, dass bei schnellen Aktionssequenzen aufgrund der Samplingrate von 1 FPS Details verloren gehen können.
    • Agentisch: Das Modell durchsucht das Video dynamisch und lädt Transkript und/oder Frames und/oder Audio bei Bedarf. Dadurch werden bis zu 88 % weniger Tokens für lange Inhalte verwendet. Die Navigation kann jedoch die Zeit bis zum ersten Token (Time to First Token, TTFT) bei kurzen Clips (unter 5 Minuten) aufgrund interner Begründungen und Tool-Roundtrips vor Beginn der Generierung leicht erhöhen. Die Antworten enthalten MEDIA_PROCESSING-Toolaufruf- und -Antwortteile, um den Begründungskontext über mehrere Turns hinweg beizubehalten. Am besten geeignet für Videos im Langformat, um die Tokenkosten und die Antwortqualität zu optimieren. Wird von Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash und 3.5 Flash Lite unterstützt. Weitere Informationen finden Sie unter Agentisches Videoverständnis.
  • Tokenberechnung (statischer Modus): Jede Sekunde Video wird so tokenisiert: folgt:
    • Einzelne Frames (gesampelt mit 1 FPS):
      • Wenn media_resolution auf „low“ gesetzt ist, werden Frames mit 66 Tokens pro Frame tokenisiert.
      • Andernfalls werden Frames mit 258 Tokens pro Frame tokenisiert.
    • Audio: 32 Tokens pro Sekunde.
    • Metadaten sind ebenfalls enthalten.
    • Gesamt: Etwa 100 Tokens pro Sekunde Video bei der Standard-Media-Auflösung (niedrig) oder etwa 300 Tokens pro Sekunde Video bei hoher Media-Auflösung.
  • Tokenberechnung (agentischer Modus): Die Tokennutzung variiert je nach Komplexität der Inhalte und Navigationsstrategie des Modells. Tokens für die Navigationsbegründung die während der Videoanalyse generiert werden, werden als Denk-Tokens (thoughts_token_count) gezählt, während Frames, Audio und Transkript, die bei Bedarf geladen werden, als Tool-Prompt-Tokens (tool_use_prompt_token_count) gezählt werden. Bei der agentischen Verarbeitung werden für lange Inhalte in der Regel bis zu 88% weniger Tokens insgesamt verwendet als bei der statischen Verarbeitung, da das Modell nur das Transkript und/oder die Frames und/oder das Audio lädt, die zum Beantworten des Prompts erforderlich sind (siehe die Anleitung zu Tokens).
  • Media-Auflösung: Mit Gemini 3 können Sie die multimodale Vision-Verarbeitung mit dem media_resolution Parameter detailliert steuern. Der Parameter media_resolution bestimmt die maximale Anzahl von Tokens, die pro Eingabebild oder Video-Frame zugewiesen werden. Höhere Auflösungen verbessern die Fähigkeit des Modells, kleinen Text zu lesen oder kleine Details zu erkennen, erhöhen aber die Tokennutzung und die Latenz. Die Parameter media_resolution und media_processing sind unabhängig: Sie können beide für denselben Videoteil festlegen.

Weitere Informationen zur Tokenberechnung finden Sie in der Anleitung zu Tokens.

  • Zeitstempelformat: Wenn Sie in Ihrem Prompt auf bestimmte Momente in einem Video verweisen, verwenden Sie das MM:SS Format (z.B. 01:15 für 1 Minute und 15 Sekunden).
  • Prompt-Platzierung: Wenn Sie Text und ein einzelnes Video kombinieren, platzieren Sie den Text-Prompt nach dem Videoteil im Array contents.

Nächste Schritte

  • Medienauflösung: Steuern Sie die Auflösung von Video-Frames, um ein ausgewogenes Verhältnis zwischen Qualität und Tokennutzung zu erreichen.
  • Tokens: Informationen zur Tokenisierung von Videoinhalten im statischen und agentischen Verarbeitungsmodus.
  • Systemanweisungen: Mit Systemanweisungen können Sie das Verhalten des Modells entsprechend Ihren spezifischen Anforderungen und Anwendungsfällen steuern.
  • Files API: Weitere Informationen zum Hochladen und Verwalten von Dateien für die Verwendung mit Gemini.
  • Strategien für Prompts mit Dateien: Die Gemini API unterstützt Prompts mit Text-, Bild-, Audio- und Videodaten, auch als multimodale Prompts bezeichnet.
  • Sicherheitshinweise: Generative KI Modelle liefern manchmal unerwartete Ausgaben, z. B. Ausgaben, die ungenau, voreingenommen oder anstößig sind. Die Nachbearbeitung und die menschliche Bewertung sind unerlässlich, um das Risiko von Schäden durch solche Ausgaben zu begrenzen.