Videos verstehen

Informationen zur Videogenerierung finden Sie im Leitfaden 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), dauerhafte, wiederverwendbare Dateien
Inlinedaten Weniger als 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.

Informationen zu anderen Methoden für die Dateieingabe, z. B. die Verwendung externer URLs oder in Google Cloud gespeicherter Dateien, finden Sie im Leitfaden 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 Referenz der hochgeladenen Datei, um das Video zusammenzufassen.

Python

from google import genai
import time

client = genai.Client()

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

while not myfile.state or myfile.state.name != "ACTIVE":
    print("Processing video...")
    time.sleep(5)
    myfile = client.files.get(name=myfile.name)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "video", "uri": myfile.uri, "mime_type": myfile.mime_type},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
    ]
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } 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" },
  });

  let getFile = await ai.files.get({ name: myfile.name });
  while (getFile.state === 'PROCESSING') {
      getFile = await ai.files.get({ name: myfile.name });
      console.log(`current file status: ${getFile.state}`);
      console.log('File is still processing, retrying in 5 seconds');

      await new Promise((resolve) => {
          setTimeout(resolve, 5000);
      });
  }
  if (getFile.state === 'FAILED') {
      throw new Error('File processing failed.');
  }

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "video", uri: myfile.uri, mime_type: myfile.mimeType },
      { type: "text", text: "Summarize this video. Then create a quiz with an answer key based on the information in this video." }
    ],
  });
  console.log(interaction.output_text);
}

await main();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.FileState;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File myfile =
    client.files.upload(
        "path/to/sample.mp4", UploadFileConfig.builder().mimeType("video/mp4").build());

while (!myfile.state().isPresent()
    || myfile.state().get().knownEnum() != FileState.Known.ACTIVE) {
  System.out.println("Processing video...");
  Thread.sleep(5000);
  myfile = client.files.get(myfile.name().get(), null);
}

Content videoContent =
    VideoContent.builder()
        .uri(myfile.uri().get())
        .mimeType(VideoContentMimeType.of(myfile.mimeType().get()))
        .build();
Content textContent =
    TextContent.builder()
        .text(
            "Summarize this video. Then create a quiz with an answer key based on the information in this video.")
        .build();

List<Content> contents = Arrays.asList(videoContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

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

    myfile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp4", &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    })
    if err != nil {
        log.Fatal(err)
    }

    for myfile.State != genai.FileStateActive {
        fmt.Println("Processing video...")
        time.Sleep(5 * time.Second)
        myfile, err = client.Files.Get(ctx, myfile.Name, nil)
        if err != nil {
            log.Fatal(err)
        }
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.VideoContent{
            URI:      genai.Ptr(myfile.URI),
            MimeType: interactions.VideoContentMimeType(myfile.MIMEType).ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

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}" \
  -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 "Uploading video 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)
file_name=$(jq -r ".file.name" file_info.json)
echo file_uri=$file_uri

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

# Polling loop
echo "Waiting for file to be processed..."
while true; do
  curl -s "https://generativelanguage.googleapis.com/v1beta/${file_name}" \
    -H "x-goog-api-key: $GEMINI_API_KEY" > file_status.json
  state=$(jq -r ".state" file_status.json)
  echo "Current state: $state"
  if [ "$state" == "ACTIVE" ]; then
    break
  elif [ "$state" == "FAILED" ]; then
    echo "File processing failed."
    exit 1
  fi
  sleep 5
done

echo "Generating content from video..."
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "video", "uri": "'${file_uri}'", "mime_type": "'${MIME_TYPE}'"},
        {"type": "text", "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 ".steps[].content[0].text" response.json

Um die Tokeneffizienz und -leistung zu optimieren, sollten Sie die agentische Videoverarbeitung verwenden.

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 übergeben. Dies ist für kürzere Videos mit einer Gesamtgröße von weniger als 20 MB geeignet.

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

Python

from google import genai
import base64

video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "data": base64.b64encode(video_bytes).decode('utf-8'),
            "mime_type": "video/mp4"
        }
    ]
)
print(interaction.output_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 interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      data: base64VideoFile,
      mime_type: "video/mp4",
    }
  ],
});
console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

String videoFileName = "/path/to/your/video.mp4";
byte[] videoBytes = Files.readAllBytes(Paths.get(videoFileName));
String base64Video = Base64.getEncoder().encodeToString(videoBytes);

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .data(base64Video)
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

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

    videoFileName := "/path/to/your/video.mp4"
    videoBytes, err := os.ReadFile(videoFileName)
    if err != nil {
        log.Fatal(err)
    }
    base64Video := base64.StdEncoding.EncodeToString(videoBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            Data:     genai.Ptr(base64Video),
            MimeType: interactions.VideoContentMimeTypeVideoMp4.ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

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

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'",
          "mime_type": "video/mp4"
        }
      ]
    }' 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

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
    ]
)
print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      uri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    }
  ],
});
console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .uri("https://www.youtube.com/watch?v=9hE5-98ZeCg")
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

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

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            URI: genai.Ptr("https://www.youtube.com/watch?v=9hE5-98ZeCg"),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

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

Beschränkungen :

  • In der kostenlosen Stufe können Sie pro Tag nicht mehr als 8 Stunden YouTube-Video hochladen.
  • Im kostenpflichtigen Abo gibt es kein Limit 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 maximal 10 Videos pro Anfrage 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 (Extrahieren von Frames mit 1 FPS) für alle Modelle verwendet, einschließlich Gemini 4. Die Modelle Gemini 4 Argon, 3.8 Flash, 3.6 Flash und 3.5 Flash Lite unterstützen auch agentisches Videoverständnis, einen optionalen Modus, in dem das Modell die Video zeitachse dynamisch durchsucht, Transkripte selektiv prüft und Frameraten und Auflösung adaptiv und spontan basierend auf dem Prompt anpasst.

Modus Beschreibung Unterstützte Modelle
Statisch (Standard) Extrahiert Frames mit einer festen Rate (1 FPS) und platziert sie in einem einzigen Durchlauf im Kontext. Standard für alle Gemini-Modelle, einschließlich Gemini 4. Alle Gemini-Modelle
Agentisch Das Modell navigiert dynamisch durch die Videozeitachse und lädt nur die Inhalte, die basierend auf dem Prompt benötigt werden. Bis zu 88% mehr Tokeneffizienz und ~7% höhere Qualität bei Inhalten im Langformat. Gemini 4 Argon, 3.8 Flash, 3.6 Flash, 3.5 Flash Lite

Verarbeitungsmodus auswählen

Wählen Sie den Verarbeitungsmodus aus, der Ihrer Videolänge und Ihrem Abfragetyp entspricht:

  • Statisch (Standard) : Am besten geeignet für kurze Clips (unter 5 Minuten), umfassende Zusammenfassungen von Videos, bei denen die gesamte Aufnahme relevant ist, latenzempfindliche Abfragen oder Frame-genaue Präzision im gesamten Clip. Bei kurzen Videos oder umfassenden Prompts, bei denen der Großteil des Videos geprüft werden muss, vermeidet die statische Verarbeitung die zusätzlichen Denk-Tokens (total_thought_tokens) und Tool-Aufruf-Roundtrips (total_tool_use_tokens), die durch die Zeitachsen-Navigation entstehen.
  • Agentisch:Am besten geeignet für Videos im Langformat (über 5–10 Minuten), die Suche nach der Nadel im Heuhaufen oder Abfragen, die auf bestimmte Momente oder Themen abzielen. Das Modell prüft zuerst Transkripte und lädt nur relevante visuelle Segmente bei Bedarf, wodurch die Tokennutzung für die Videoeingabe um bis zu 88% reduziert wird, ohne das Kontextfenster zu füllen.

Hinweis: Bei langen Videos oder komplexen Prompts, bei denen die agentische Verarbeitung mehr Zeit in Anspruch nimmt, verwenden Sie Streaming (stream=True) oder Hintergrundausführung (background=True). Dadurch bleibt die Verbindung aktiv, es werden Zwischenschritte der Argumentation angezeigt und Zeitüberschreitungen bei der Verbindung oder Authentifizierung werden vermieden.

Verarbeitungsmodus festlegen

Wenn Sie agentisches Videoverständnis verwenden möchten, legen Sie "processing": "agentic" für den Video teil im input Array fest.

Die agentische Videoverarbeitung kann bei langen Videos länger dauern, da das Modell mehrere Prüfdurchläufe durchführt, um durch die Zeitachse zu navigieren. Um zu vermeiden, dass der Fortschritt verloren geht, wenn eine Netzwerkverbindung unterbrochen wird, wird in diesem Beispiel background=True verwendet, um die Aufgabe asynchron auf dem Server auszuführen. Sie können Anfragen auch synchron ohne Hintergrundausführung ausführen, indem Sie den Parameter background weglassen. Dies funktioniert gut bei kürzeren Videos.

Weitere Informationen zum Polling, zum Abrufen von Ergebnissen und zum Verwalten von Hintergrundaufgaben finden Sie unter dem Leitfaden zur Hintergrundausführung.

Python

import time
from google import genai

client = genai.Client()

# Upload a long video
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)

# Use agentic processing with background execution
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": "agentic"
        },
        {"type": "text", "text": "What are the three main arguments presented?"}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

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

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

// Use agentic processing with background execution
let interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: "agentic"
    },
    { type: "text", text: "What are the three main arguments presented?" }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);

REST

# 1. Start the interaction in the background
interaction=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {"type": "text", "text": "What are the three main arguments presented?"}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'

Hinweis:Prüfen Sie interaction.steps, um zu bestätigen, dass die agentische Verarbeitung verwendet wurde. Das Vorhandensein von processing_call und processing_result zeigt an, dass das Modell dynamisch durch das Video navigiert hat.

Antwortschritte

Bei der agentischen Verarbeitung werden dem steps-Array zwei neue Schritttypen hinzugefügt:

  • processing_call: Das Modell hat ein Videosegment oder ein Audiotranskript angefordert, das durch id identifiziert wird.
  • processing_result: Das Ergebnis dieses Ladevorgangs, verknüpft durch call_id.

Diese werden mit thought-Schritten verschachtelt (wenn Zusammenfassungen aktiviert sind) und gehen dem letzten model_output-Schritt voraus. Sie können verwendet werden, um einen Fortschrittsverlauf in Ihrer UI anzuzeigen, erfordern aber keine Antwort.

Das folgende Beispiel zeigt die Antwortnutzlast mit verschachtelten Verarbeitungsschritten:

{
  "steps": [
    {
      "type": "thought",
      "signature": "sig_thought_1",
      "summary": [
        {
          "type": "text",
          "text": "Inspecting transcript for key discussion topics..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_01",
      "signature": "sig_call_01"
    },
    {
      "type": "processing_result",
      "call_id": "call_01",
      "signature": "sig_result_01"
    },
    {
      "type": "thought",
      "signature": "sig_thought_2",
      "summary": [
        {
          "type": "text",
          "text": "Loading visual frames to verify slide content..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_02",
      "signature": "sig_call_02"
    },
    {
      "type": "processing_result",
      "call_id": "call_02",
      "signature": "sig_result_02"
    },
    {
      "type": "thought",
      "signature": "sig_thought_3",
      "summary": [
        {
          "type": "text",
          "text": "Synthesizing answer from gathered evidence..."
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The three main arguments presented in the lecture are..."
        }
      ]
    }
  ]
}

Verarbeitungsmodi für verschiedene Videos kombinieren

Legen Sie für jedes Video in derselben Anfrage unterschiedliche Verarbeitungsmodi fest:

Python

import time
from google import genai

client = genai.Client()

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

# Use agentic processing with background execution
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": lecture.uri,
            "mime_type": lecture.mime_type,
            "processing": "agentic"  # Use agentic video understanding
        },
        {
            "type": "video",
            "uri": experiment.uri,
            "mime_type": experiment.mime_type,
            "processing": "static"  # Use static processing
        },
        {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print(interaction.output_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" }
});

// Use agentic processing with background execution
let interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: lecture.uri,
      mime_type: lecture.mimeType,
      processing: "agentic" // Use agentic video understanding
    },
    {
      type: "video",
      uri: experiment.uri,
      mime_type: experiment.mimeType,
      processing: "static" // Use static processing
    },
    { type: "text", text: "Compare the lecture content with the experiment results." }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);

REST

# 1. Start the interaction in the background
interaction=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${lecture_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {
        "type": "video",
        "uri": "'${experiment_uri}'",
        "mime_type": "video/mp4",
        "processing": "static"
      },
      {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'

Mehrfachdialogbasierte Videounterhaltungen

Der Videokontext bleibt über mehrere Unterhaltungsrunden hinweg erhalten. Bei Verwendung der agentischen Verarbeitung gilt Folgendes:

  • Zustandsbehafteter Modus (mit previous_interaction_id): Der Server behält den Videokontext bei. Es sind keine zusätzlichen Maßnahmen erforderlich.
  • Zustandsloser Modus (mit step_list): Im zustandslosen Modus enthält die Antwort processing_call- und processing_result-Schritte, die den Videokontext codieren. Sie müssen alle Schritte aus der Antwort in die step_list der nächsten Anfrage einfügen, um den Videokontext beizubehalten. Wenn Sie sie weglassen, wird derzeit kein API-Fehler zurückgegeben, aber der Videokontext geht verloren, was die Antwortqualität bei Folgefragen erheblich verringert. Zurückgegebene Schritte, die in nachfolgenden Anfragen gesendet werden, tragen zur Anzahl der Eingabetokens bei.

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?"

JavaScript

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

Java

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

Go

prompt := "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 Informationen 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, einschließlich der Generierung von Beschreibungen dessen, was in einem Video passiert, und der Beantwortung von Fragen zu den Inhalten.

Für visuelle Beschreibungen nimmt das Modell das Video mit einer Rate von 1 Frame pro Sekunde (FPS) auf. Diese Standard-Abtastrate funktioniert gut für die meisten Inhalte, aber es ist möglich, dass Details in Videos mit schnellen Bewegungen oder schnellen Szenenwechseln verloren gehen.

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.";

Java

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

Go

prompt := "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-Abtastung bereitstellen. Diese Anpassungsoptionen werden nur unterstützt, wenn das Video im Modus "static" verarbeitet wird.

Clipping-Intervalle festlegen

Sie können Videos zuschneiden, indem Sie start_offset und end_offset im Konfigurationsobjekt processing angeben.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "start_offset": 1200,
                "end_offset": 1500,
            },
        },
        {"type": "text", "text": "Summarize this section of the video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        start_offset: 1200,
        end_offset: 1500,
      },
    },
    { type: "text", text: "Summarize this section of the video." },
  ],
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "start_offset": 1200,
          "end_offset": 1500
        }
      },
      {"type": "text", "text": "Summarize this section of the video."}
    ]
  }' 2> /dev/null

Benutzerdefinierte Framerate festlegen

Sie können eine benutzerdefinierte Framerate-Abtastung festlegen, indem Sie ein fps-Argument im Konfigurationsobjekt processing übergeben.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "fps": 0.5,  # Sample 1 frame every 2 seconds
            },
        },
        {"type": "text", "text": "Describe the scene changes in this video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        fps: 0.5, // Sample 1 frame every 2 seconds
      },
    },
    { type: "text", text: "Describe the scene changes in this video." },
  ],
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "fps": 0.5
        }
      },
      {"type": "text", "text": "Describe the scene changes in this video."}
    ]
  }' 2> /dev/null

Unterstützte Videoformate

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

  • video/mp4
  • video/mpeg
  • video/mov
  • 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 Token können standardmäßig Videos mit einer Länge von bis zu 3 Stunden (bei niedriger Medienauflösung) oder bis zu 1 Stunde (bei hoher Medienauflösung) verarbeiten.
  • Verarbeitungsmodi: Gemini 4 Argon, 3.8 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 (Einzelkanal) 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-Prüfung). Bei schnellen Actionsequenzen können aufgrund der Abtastrate von 1 FPS Details verloren gehen.
    • Agentisch: Das Modell navigiert dynamisch durch das Video und lädt Transkript und/oder Frames und/oder Audio bei Bedarf. Dadurch werden bis zu 88 % weniger Tokens für Inhalte im Langformat verwendet. Die Navigation kann jedoch die Zeit bis zum ersten Token (Time to First Token, TTFT) und die Gesamtzahl der verwendeten Tokens bei kurzen Clips (unter 5 Minuten) oder umfassenden Abfragen aufgrund interner Argumentation und Tool-Roundtrips erhöhen. Am besten geeignet für Videos im Langformat und gezielte Abfragen, um die Tokenkosten und die Antwortqualität zu optimieren. Wird von Gemini 4 Argon, 3.8 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 (Abtastung 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-Medienauflösung (niedrig) oder etwa 300 Tokens pro Sekunde Video bei hoher Medienauflösung.
  • Tokenberechnung (agentischer Modus): Die Tokennutzung variiert je nach Inhalt skomplexität und der Navigationsstrategie des Modells. Tokens für die Navigationsargumentation die während der Videoerkundung generiert werden, werden als Denk-Tokens (total_thought_tokens) gezählt, während Frames, Audio und Transkripte, die bei Bedarf geladen werden, als Tool-Nutzungs-Tokens (total_tool_use_tokens) gezählt werden. Bei der agentischen Verarbeitung werden in der Regel bis zu 88% weniger Tokens als bei der statischen Verarbeitung für Inhalte im Langformat verwendet, da das Modell nur das Transkript und/oder die Frames und/oder das Audio lädt, die zum Beantworten des Prompts erforderlich sind (siehe den Leitfaden zu Tokens).
  • Medienauflösung: Mit Gemini 3 wird mit dem Parameter media_resolution eine detaillierte Steuerung der multimodalen Vision-Verarbeitung eingeführt. Der Parameter media_resolution bestimmt die maximale Anzahl von Tokens, die pro Eingabebild oder Videoframe 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 processing sind unabhängig: Sie können beide für dieselbe Videoeingabe festlegen.

Weitere Informationen zur Tokenberechnung finden Sie im Leitfaden 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 input Array.
  • Zeitüberschreitungen bei langen Anfragen: Bei Videos, die eine längere Verarbeitungszeit oder eine komplexe mehrstufige Problemlösung erfordern, verwenden Sie Streaming (stream=True) oder die Hintergrundausführung (background=True). Bei synchronen Nicht-Streaming-Anfragen, bei denen bei hoher Nachfrage Backend-Wiederholungen auftreten, können die Gültigkeitszeiträume für Verbindungs- oder Authentifizierungstokens überschritten werden, was zu unerwarteten Fehlern vom Typ 401 Unauthorized oder Zeitüberschreitungen führen kann. Beim Streaming bleibt die Verbindung aktiv und es werden Zwischenschritte der Argumentation und des Tool-Aufrufs angezeigt.

Nächste Schritte

  • Medienauflösung: Steuern Sie die Auflösung von Videoframes, um ein ausgewogenes Verhältnis zwischen Qualität und Tokennutzung zu erreichen.
  • Tokens: Informationen zur Tokenisierung von Videoinhalten im statischen und agentischen Verarbeitungsmodus.
  • Hintergrundausführung: Führen Sie zeitaufwendige Aufgaben zum Videoverständnis asynchron aus, um Zeitüberschreitungen bei der Verbindung zu vermeiden.
  • 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 zur 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 geben manchmal unerwartete Ausgaben aus, 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.